capsule-narrative 0.1.0__py3-none-any.whl

capsule/__init__.py

@@ -0,0 +1,3 @@
+"""timecapsule — A git-like filesystem that creates narrative commits."""
+
+__version__ = "0.1.0"

capsule/daemon.py

@@ -0,0 +1,174 @@
+"""timecapsule daemon — entry point that wires watcher, git, store, and narrator.
+
+Watches a directory tree for file changes. After 2 minutes of inactivity
+on a file, snapshots it to the timecapsule repo with a narrative commit
+message (generated by Ollama if available, otherwise structural)."""
+
+import argparse
+import os
+import signal
+import sys
+import time
+from pathlib import Path
+
+from . import git_ops
+from .store import TimelineStore
+from .watcher import FileWatcher, IDLE_SECONDS
+
+
+def _snapshot_callback(filepath: str):
+    """Called when a file has been idle long enough to snapshot."""
+    from .narrator import generate_message as gen_msg
+
+    store = TimelineStore()
+    repo = git_ops.ensure_repo()
+
+    # Get current content
+    if not os.path.isfile(filepath):
+        return
+
+    with open(filepath, "rb") as f:
+        current_content = f.read().decode("utf-8", errors="replace")
+
+    # Get previous snapshot content and message for context
+    branch = git_ops._branch_name(filepath)
+    previous_content = None
+    previous_message = None
+
+    try:
+        commits = list(repo.iter_commits(branch, max_count=1))
+        if commits:
+            previous_message = commits[0].message.strip()
+            rel_path = os.path.basename(filepath)
+            try:
+                previous_content = repo.git.show(f"{commits[0].hexsha}:{rel_path}")
+            except Exception:
+                previous_content = None
+    except Exception:
+        pass
+
+    # Generate narrative message
+    message = gen_msg(
+        filepath=filepath,
+        current_content=current_content,
+        previous_content=previous_content,
+        previous_message=previous_message,
+    )
+
+    # Snapshot to git
+    hexsha = git_ops.snapshot_file(filepath, message, repo)
+    if hexsha:
+        store.record_snapshot(filepath, hexsha, message, branch)
+        print(f"[snapshot] {os.path.basename(filepath)} › {message[:60]}...", flush=True)
+
+
+def watch(paths: list[str], idle: int = IDLE_SECONDS, foreground: bool = True, once: bool = False):
+    """Start the file watcher and run until interrupted."""
+    print(f"🕰️  timecapsule watching: {', '.join(paths)}")
+    print(f"   idle threshold: {idle}s | snapshots: ~/.capsule/timecapsule")
+    print(f"   press Ctrl+C to stop\n")
+
+    watcher = FileWatcher(paths, _snapshot_callback, idle_seconds=idle)
+
+    def _handle_signal(sig, frame):
+        watcher.stop()
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, _handle_signal)
+    signal.signal(signal.SIGTERM, _handle_signal)
+
+    watcher.start()
+    print("   ✓ watcher started")
+
+    # If --once, do one pass of all files and exit
+    if once:
+        _scan_all_files(paths)
+        watcher.stop()
+        print("\n   ✓ one-time scan complete")
+        return
+
+    try:
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        watcher.stop()
+        print("\n   ✗ watcher stopped")
+
+
+def _scan_all_files(paths: list[str]):
+    """Immediately snapshot all tracked files (one-time mode)."""
+    from .narrator import generate_message as gen_msg
+
+    store = TimelineStore()
+    repo = git_ops.ensure_repo()
+
+    ext_filter = {
+        ".py", ".js", ".ts", ".rs", ".go", ".md",
+        ".txt", ".json", ".yaml", ".toml", ".css",
+        ".html", ".jsx", ".tsx", ".java", ".c", ".cpp",
+        ".h", ".sh", ".ps1", ".bat", ".sql", ".rb",
+        ".php", ".swift", ".kt", ".scala", ".zig",
+    }
+
+    for root_path in paths:
+        for dirpath, _, filenames in os.walk(root_path):
+            for fn in filenames:
+                if fn.startswith(".") or fn.startswith("__"):
+                    continue
+                ext = os.path.splitext(fn)[1].lower()
+                if ext in ext_filter:
+                    fp = os.path.join(dirpath, fn)
+                    _snapshot_callback(fp)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="🕰️  timecapsule — narrative snapshots of your work",
+    )
+    parser.add_argument(
+        "paths", nargs="*", default=["."],
+        help="Directories to watch (default: current directory)",
+    )
+    parser.add_argument(
+        "--idle", type=int, default=IDLE_SECONDS,
+        help=f"Idle seconds before snapshot (default: {IDLE_SECONDS})",
+    )
+    parser.add_argument(
+        "--once", action="store_true",
+        help="Snapshot all files once and exit (no daemon)",
+    )
+    parser.add_argument(
+        "--browse", action="store_true",
+        help="Open the timeline browser TUI",
+    )
+    parser.add_argument(
+        "--status", action="store_true",
+        help="Show capsule stats and exit",
+    )
+
+    args = parser.parse_args()
+
+    if args.browse:
+        from .tui import run_browser
+        run_browser()
+        return
+
+    if args.status:
+        store = TimelineStore()
+        repo = git_ops.ensure_repo()
+        count = store.total_snapshots()
+        files = len(store.get_all_files())
+        repo_path = str(git_ops.REPO_PATH)
+        print(f"🕰️  timecapsule status")
+        print(f"   snapshots: {count}")
+        print(f"   tracked files: {files}")
+        print(f"   repository: {repo_path}")
+        return
+
+    watch(args.paths, idle=args.idle, once=args.once)
+
+
+if __name__ == "__main__":
+    main()

capsule/git_ops.py

@@ -0,0 +1,160 @@
+"""Git operations for timecapsule.
+
+Manages a dedicated hidden repository at ~/.capsule/timecapsule.git.
+Each tracked file gets its own orphan branch named after its canonical path.
+This keeps the user's real .git untouched and makes cleanup trivial.
+
+Uses git command-line calls for low-level operations since gitpython's
+LooseObjectDB doesn't handle bare repo blob creation well across versions."""
+
+import os
+import re
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+import git
+
+CAPSULE_DIR = Path.home() / ".capsule"
+REPO_PATH = CAPSULE_DIR / "timecapsule"
+
+
+def _branch_name(filepath: str) -> str:
+    """Derive a branch name from a file path.
+
+    Converts a path like:
+      C:/Users/ngugi/project/main.py
+    to:
+      home-ngugi-project-main-py (safe for git refs).
+    """
+    abs_path = os.path.normpath(os.path.abspath(filepath))
+    parts = []
+    for p in Path(abs_path).parts:
+        if ":" in p:
+            continue
+        sanitized = re.sub(r"[^\w-]", "-", p.lower().strip("-"))
+        if sanitized:
+            parts.append(sanitized)
+    name = "-".join(parts)
+    return name[:250]
+
+
+def _git(*args: str, env: Optional[dict] = None, _input: Optional[str] = None) -> str:
+    """Run a git command in the timecapsule repo."""
+    cmd = ["git", "--git-dir", str(REPO_PATH)] + list(args)
+    result = subprocess.run(
+        cmd,
+        capture_output=True, text=True, input=_input,
+        env={**os.environ, **(env or {})},
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"git {' '.join(args)}: {result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+def ensure_repo() -> git.Repo:
+    """Create and return the timecapsule bare repository."""
+    CAPSULE_DIR.mkdir(parents=True, exist_ok=True)
+    if not (REPO_PATH / "HEAD").exists():
+        repo = git.Repo.init(str(REPO_PATH), bare=True)
+    else:
+        repo = git.Repo(str(REPO_PATH))
+    return repo
+
+
+def snapshot_file(filepath: str, message: str, repo: git.Repo) -> Optional[str]:
+    """Snapshot a file's current state into its orphan branch.
+
+    Creates a tree object from the file and commits it as a new root
+    commit on the file's orphan branch. If the branch already exists,
+    the commit becomes a child of the previous tip.
+
+    Returns the commit hexsha or None on failure.
+    """
+    abs_path = os.path.normpath(os.path.abspath(filepath))
+    if not os.path.isfile(abs_path):
+        return None
+
+    branch = _branch_name(abs_path)
+    rel_path = os.path.basename(abs_path)
+
+    # Create blob via hash-object
+    blob_hash = _git("hash-object", "-w", abs_path)
+
+    # Create tree with the blob
+    # git mktree expects: mode SP type SP hash TAB path
+    tree_input = f"100644 blob {blob_hash}\t{rel_path}\n"
+    with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".txt") as f:
+        f.write(tree_input)
+        tree_path = f.name
+
+    try:
+        tree_hash = _git("mktree", "--missing", _input=open(tree_path, "r").read())
+    finally:
+        os.unlink(tree_path)
+
+    # Get parent commit if branch exists
+    parent = None
+    try:
+        parent = _git("rev-parse", f"refs/heads/{branch}")
+    except RuntimeError:
+        pass
+
+    # Create commit
+    env = {
+        "GIT_AUTHOR_NAME": "timecapsule",
+        "GIT_AUTHOR_EMAIL": "capsule@localhost",
+        "GIT_COMMITTER_NAME": "timecapsule",
+        "GIT_COMMITTER_EMAIL": "capsule@localhost",
+    }
+
+    commit_args = ["commit-tree", tree_hash, "-m", message]
+    if parent:
+        commit_args.extend(["-p", parent])
+
+    commit_hash = _git(*commit_args, env=env)
+
+    # Update branch ref
+    _git("update-ref", f"refs/heads/{branch}", commit_hash)
+
+    return commit_hash
+
+
+def get_timeline(filepath: str, repo: git.Repo, max_count: int = 50) -> list[dict]:
+    """Get the commit history for a file's branch.
+
+    Returns list of {hexsha, message, committed_datetime, author}.
+    """
+    branch = _branch_name(filepath)
+    try:
+        commits = list(repo.iter_commits(branch, max_count=max_count))
+    except (ValueError, git.BadName):
+        return []
+
+    results = []
+    for c in commits:
+        results.append({
+            "hexsha": c.hexsha,
+            "message": c.message.strip(),
+            "committed_datetime": c.committed_datetime.isoformat(),
+            "committed_timestamp": c.committed_datetime.timestamp(),
+            "author": str(c.author),
+        })
+    return results
+
+
+def get_file_at_commit(filepath: str, commit_hexsha: str, repo: git.Repo) -> Optional[str]:
+    """Retrieve file contents at a given commit."""
+    branch = _branch_name(filepath)
+    rel_path = os.path.basename(filepath)
+    try:
+        return repo.git.show(f"{commit_hexsha}:{rel_path}")
+    except git.GitCommandError:
+        return None
+
+
+def list_tracked_files(repo: git.Repo) -> list[str]:
+    """List all files that have been snapshot (by their branch names)."""
+    refs = repo.git.for_each_ref("refs/heads/", format="%(refname:short)").splitlines()
+    return [r for r in refs if r.strip()]

capsule/narrator.py

@@ -0,0 +1,173 @@
+"""LLM-powered narrator that generates narrative commit messages from diffs.
+
+Uses Ollama if available (qwen2.5-coder:1.5b or similar small model).
+Gracefully falls back to structural template messages if Ollama is not running."""
+
+import os
+import subprocess
+import time
+import json
+from pathlib import Path
+from typing import Optional
+
+
+def _check_ollama() -> bool:
+    """Check if Ollama is available and running."""
+    try:
+        result = subprocess.run(
+            ["ollama", "list"],
+            capture_output=True, text=True, timeout=5,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired, Exception):
+        return False
+
+
+def _ollama_generate(model: str, prompt: str, timeout: int = 30) -> Optional[str]:
+    """Generate text using Ollama's API."""
+    import urllib.request
+    import urllib.error
+
+    data = json.dumps({
+        "model": model,
+        "prompt": prompt,
+        "stream": False,
+        "options": {
+            "num_predict": 128,
+            "temperature": 0.7,
+        }
+    }).encode()
+
+    try:
+        req = urllib.request.Request(
+            "http://localhost:11434/api/generate",
+            data=data,
+            headers={"Content-Type": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            result = json.loads(resp.read().decode())
+            return result.get("response", "").strip()
+    except Exception:
+        return None
+
+
+# Template message generators (fallback when no LLM available)
+
+SNAPSHOT_TEMPLATES = [
+    "Modified {filename}",
+    "Updated {filename}",
+    "Edited {filename}",
+    "Changes to {filename}",
+    "Work in progress on {filename}",
+]
+
+
+def _template_message(filepath: str, diff: str) -> str:
+    """Generate a structural commit message from the diff."""
+    import random
+
+    filename = os.path.basename(filepath)
+    ext = os.path.splitext(filename)[1].lower()
+
+    # Count changes roughly
+    lines_added = len([l for l in diff.splitlines() if l.startswith("+") and not l.startswith("+++")])
+    lines_removed = len([l for l in diff.splitlines() if l.startswith("-") and not l.startswith("---")])
+
+    if lines_added == 0 and lines_removed == 0:
+        return f"Saved {filename} (no substantive changes detected)"
+
+    # File-type specific templates
+    lang_map = {
+        ".py": "Python",
+        ".js": "JavaScript", ".jsx": "JSX", ".ts": "TypeScript", ".tsx": "TSX",
+        ".rs": "Rust", ".go": "Go", ".java": "Java",
+        ".md": "Markdown", ".txt": "text",
+        ".css": "CSS", ".html": "HTML",
+        ".json": "JSON", ".yaml": "YAML", ".toml": "TOML",
+    }
+    lang = lang_map.get(ext, "code")
+
+    if lines_added > 0 and lines_removed > 0:
+        return f"Modified {filename}: +{lines_added}/-{lines_removed} lines in {lang} file"
+    elif lines_added > 0:
+        return f"Added {lines_added} lines to {filename} ({lang})"
+    elif lines_removed > 0:
+        return f"Removed {lines_removed} lines from {filename} ({lang})"
+
+    return f"Updated {filename}"
+
+
+def generate_message(filepath: str, current_content: str,
+                     previous_content: Optional[str] = None,
+                     previous_message: Optional[str] = None,
+                     model: str = "qwen2.5-coder:1.5b") -> str:
+    """Generate a narrative commit message for a file change.
+
+    Uses Ollama if available; falls back to template messages.
+
+    Args:
+        filepath: Absolute path to the file.
+        current_content: The file's current contents.
+        previous_content: The file's contents at last snapshot (if any).
+        previous_message: The previous commit message (for continuity).
+        model: Ollama model to use.
+
+    Returns:
+        A commit message string.
+    """
+    filename = os.path.basename(filepath)
+
+    # If no previous version, it's a first snapshot
+    if previous_content is None:
+        return f"Initial snapshot of {filename}"
+
+    # Generate a simple diff summary
+    diff_lines = []
+    current_lines = current_content.splitlines(keepends=True)
+    prev_lines = previous_content.splitlines(keepends=True)
+
+    # Simple line-by-line diff (not as sophisticated as real git diff, but fast)
+    import difflib
+    diff = list(difflib.unified_diff(prev_lines, current_lines,
+                                     fromfile=f"a/{filename}", tofile=f"b/{filename}",
+                                     n=3))
+
+    # Build a compact diff string
+    diff_text = "".join(diff[:80])  # cap at 80 lines
+
+    # Template fallback
+    template_msg = _template_message(filepath, diff_text)
+
+    # Try Ollama if available
+    if not _check_ollama():
+        return template_msg
+
+    # Build a prompt for the LLM
+    context_parts = []
+    if previous_message and previous_message != template_msg:
+        context_parts.append(f"Previous change: {previous_message}")
+
+    context = " ".join(context_parts)
+    if context:
+        context = f"Context: {context}"
+
+    ext = os.path.splitext(filename)[1].lower()
+
+    prompt = f"""You are a thoughtful developer's digital diary.
+Given the following code diff and context, write a single sentence that describes WHY the changes were made, in a personal, reflective style. Do NOT list what changed; explain the reason as if you were the developer.
+
+File: {filename} ({ext})
+{context}
+
+Diff:
+```diff
+{diff_text[:2000]}
+```
+
+Write one sentence explaining why you made these changes:"""
+
+    llm_message = _ollama_generate(model, prompt)
+    if llm_message and len(llm_message) > 10:
+        return llm_message[:200]  # cap length
+
+    return template_msg

capsule/store.py

@@ -0,0 +1,119 @@
+"""SQLite timeline index for fast queries across all snapshots.
+
+Stores metadata for every snapshot: filepath, commit hash, message,
+timestamp — bypasses git log for 100x faster queries."""
+
+import os
+import sqlite3
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+CAPSULE_DIR = Path.home() / ".capsule"
+DB_PATH = CAPSULE_DIR / "timeline.db"
+
+
+class TimelineStore:
+    """Thread-safe SQLite store for snapshot metadata."""
+
+    def __init__(self, db_path: str | Path = DB_PATH):
+        self._db_path = str(db_path)
+        self._local = threading.local()
+        self._lock = threading.Lock()
+        self._init_db()
+
+    def _get_conn(self) -> sqlite3.Connection:
+        if not hasattr(self._local, "conn") or self._local.conn is None:
+            self._local.conn = sqlite3.connect(self._db_path)
+            self._local.conn.row_factory = sqlite3.Row
+            self._local.conn.execute("PRAGMA journal_mode=WAL")
+            self._local.conn.execute("PRAGMA synchronous=NORMAL")
+        return self._local.conn
+
+    def _init_db(self):
+        conn = sqlite3.connect(self._db_path)
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("""
+            CREATE TABLE IF NOT EXISTS snapshots (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                filepath TEXT NOT NULL,
+                hexsha TEXT NOT NULL,
+                message TEXT NOT NULL,
+                timestamp REAL NOT NULL,
+                branch TEXT NOT NULL
+            )
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_snapshots_filepath
+            ON snapshots(filepath)
+        """)
+        conn.execute("""
+            CREATE INDEX IF NOT EXISTS idx_snapshots_timestamp
+            ON snapshots(timestamp)
+        """)
+        conn.commit()
+        conn.close()
+
+    def record_snapshot(self, filepath: str, hexsha: str, message: str,
+                        branch: str, timestamp: Optional[float] = None):
+        ts = timestamp or datetime.now(timezone.utc).timestamp()
+        with self._lock:
+            conn = sqlite3.connect(self._db_path)
+            conn.execute(
+                "INSERT INTO snapshots (filepath, hexsha, message, timestamp, branch) "
+                "VALUES (?, ?, ?, ?, ?)",
+                (os.path.normpath(filepath), hexsha, message, ts, branch),
+            )
+            conn.commit()
+            conn.close()
+
+    def get_timeline(self, filepath: str, limit: int = 50) -> list[dict]:
+        """Get all snapshots for a file, newest first."""
+        norm = os.path.normpath(filepath)
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            "SELECT * FROM snapshots WHERE filepath = ? ORDER BY timestamp DESC LIMIT ?",
+            (norm, limit),
+        ).fetchall()
+        conn.close()
+        return [dict(r) for r in rows]
+
+    def get_all_files(self) -> list[dict]:
+        """Get the latest snapshot for each tracked file."""
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute("""
+            SELECT filepath, MAX(timestamp) as last_seen,
+                   (SELECT message FROM snapshots s2
+                    WHERE s2.filepath = snapshots.filepath
+                    ORDER BY timestamp DESC LIMIT 1) as last_message
+            FROM snapshots
+            GROUP BY filepath
+            ORDER BY last_seen DESC
+        """).fetchall()
+        conn.close()
+        return [dict(r) for r in rows]
+
+    def search(self, query: str, limit: int = 20) -> list[dict]:
+        """Search snapshot messages."""
+        conn = sqlite3.connect(self._db_path)
+        conn.row_factory = sqlite3.Row
+        rows = conn.execute(
+            "SELECT * FROM snapshots WHERE message LIKE ? ORDER BY timestamp DESC LIMIT ?",
+            (f"%{query}%", limit),
+        ).fetchall()
+        conn.close()
+        return [dict(r) for r in rows]
+
+    def total_snapshots(self) -> int:
+        conn = sqlite3.connect(self._db_path)
+        count = conn.execute("SELECT COUNT(*) FROM snapshots").fetchone()[0]
+        conn.close()
+        return count
+
+    def close(self):
+        if hasattr(self._local, "conn") and self._local.conn:
+            self._local.conn.close()
+            self._local.conn = None

capsule/tui.py

@@ -0,0 +1,204 @@
+"""Textual TUI for browsing the time capsule timeline.
+
+Shows tracked files, commit history for each file, and diff previews."""
+
+import os
+import time
+from pathlib import Path
+from typing import Optional
+
+from textual import on
+from textual.app import App, ComposeResult
+from textual.containers import Container, Horizontal, Vertical
+from textual.widgets import Header, Footer, ListView, ListItem, Static, RichLog, Label
+
+from . import git_ops
+from .store import TimelineStore
+
+
+class CapsuleBrowser(App):
+    """Textual TUI for browsing timecapsule snapshots."""
+
+    CSS = """
+    Screen {
+        background: #0a0a0a;
+    }
+
+    #layout {
+        layout: grid;
+        grid-size: 3 2;
+        grid-gutter: 1;
+        padding: 1;
+        height: 100%;
+    }
+
+    #file-list-panel {
+        border: solid #00ff88;
+        padding: 0 1;
+        background: #0d1a12;
+    }
+
+    #file-list-panel > Label {
+        text-style: bold;
+        color: #00ff88;
+        height: 1;
+        margin-bottom: 1;
+    }
+
+    #file-list {
+        height: 100%;
+    }
+
+    #timeline-panel {
+        column-span: 2;
+        border: solid #ff8800;
+        padding: 0 1;
+        background: #1a0f05;
+    }
+
+    #timeline-panel > Label {
+        text-style: bold;
+        color: #ff8800;
+        height: 1;
+        margin-bottom: 1;
+    }
+
+    #timeline-list {
+        height: 100%;
+    }
+
+    #diff-panel {
+        column-span: 3;
+        border: solid #444;
+        padding: 0 1;
+        background: #0a0a0a;
+        height: 100%;
+    }
+
+    #diff-panel > Label {
+        color: #888;
+        height: 1;
+        margin-bottom: 1;
+    }
+
+    RichLog {
+        background: #0a0a0a;
+    }
+
+    ListView {
+        background: #0d1a12;
+    }
+
+    ListItem {
+        padding: 0 1;
+    }
+
+    ListItem:nth-child(even) {
+        background: #0f1f15;
+    }
+    """
+
+    BINDINGS = [
+        ("q", "quit", "Quit"),
+        ("r", "refresh", "Refresh"),
+    ]
+
+    def __init__(self):
+        super().__init__()
+        self.store = TimelineStore()
+        self.repo = git_ops.ensure_repo()
+        self._selected_file: Optional[str] = None
+        self._selected_commit: Optional[str] = None
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        with Container(id="layout"):
+            with Vertical(id="file-list-panel"):
+                yield Label("📁 Tracked Files")
+                yield ListView(id="file-list")
+            with Vertical(id="timeline-panel"):
+                yield Label("📜 Timeline")
+                yield ListView(id="timeline-list")
+            with Vertical(id="diff-panel"):
+                yield Label("📄 Diff Preview")
+                yield RichLog(id="diff-view", highlight=True, markup=False)
+        yield Footer()
+
+    def on_mount(self):
+        self._populate_file_list()
+
+    def _populate_file_list(self):
+        files = self.store.get_all_files()
+        lv = self.query_one("#file-list", ListView)
+        lv.clear()
+        for f in files:
+            fp = f["filepath"]
+            last_msg = f.get("last_message", "")[:60]
+            label = f"{os.path.basename(fp)} — {last_msg}"
+            lv.append(ListItem(Label(label)))
+        if files:
+            lv.index = 0
+            self._on_file_selected(files[0]["filepath"])
+
+    def _on_file_selected(self, filepath: str):
+        self._selected_file = filepath
+        self._populate_timeline(filepath)
+
+    def _populate_timeline(self, filepath: str):
+        commits = self.store.get_timeline(filepath)
+        lv = self.query_one("#timeline-list", ListView)
+        lv.clear()
+        for c in commits:
+            dt = time.strftime("%b %d %H:%M", time.localtime(c["timestamp"]))
+            msg = c["message"][:70]
+            label = f"[{dt}] {msg}"
+            lv.append(ListItem(Label(f"  {label}")))
+        if commits:
+            lv.index = 0
+            self._on_commit_selected(commits[0]["hexsha"])
+        else:
+            diff = self.query_one("#diff-view", RichLog)
+            diff.clear()
+            diff.write("(no commits yet for this file)")
+
+    def _on_commit_selected(self, hexsha: str):
+        self._selected_commit = hexsha
+        diff = self.query_one("#diff-view", RichLog)
+        diff.clear()
+
+        if not self._selected_file:
+            diff.write("(no file selected)")
+            return
+
+        # Show the file content at this commit
+        content = git_ops.get_file_at_commit(self._selected_file, hexsha, self.repo)
+        if content:
+            diff.clear()
+            for line in content.splitlines()[:100]:
+                diff.write(line)
+            if len(content.splitlines()) > 100:
+                diff.write("[dim]... (truncated)[/]")
+        else:
+            diff.write("(file content not available)")
+
+    @on(ListView.Selected, "#file-list")
+    def file_selected(self, event: ListView.Selected):
+        files = self.store.get_all_files()
+        if event.list_view.index is not None and event.list_view.index < len(files):
+            self._on_file_selected(files[event.list_view.index]["filepath"])
+
+    @on(ListView.Selected, "#timeline-list")
+    def commit_selected(self, event: ListView.Selected):
+        if not self._selected_file:
+            return
+        commits = self.store.get_timeline(self._selected_file)
+        if event.list_view.index is not None and event.list_view.index < len(commits):
+            self._on_commit_selected(commits[event.list_view.index]["hexsha"])
+
+    def action_refresh(self):
+        self._populate_file_list()
+
+
+def run_browser():
+    app = CapsuleBrowser()
+    app.run()

capsule/watcher.py

@@ -0,0 +1,123 @@
+"""Watchdog-based file watcher with idle debounce.
+
+Tracks per-file modification times. When a file hasn't been touched
+for IDLE_SECONDS, fires a snapshot callback for that file."""
+
+import os
+import time
+import threading
+from pathlib import Path
+from typing import Callable, Set
+
+from watchdog.events import FileSystemEventHandler, FileModifiedEvent, FileCreatedEvent
+from watchdog.observers import Observer
+
+IDLE_SECONDS = 120  # 2 minutes of inactivity triggers a snapshot
+
+
+class IdleTracker:
+    """Per-file idle timer."""
+
+    def __init__(self, idle_seconds: int = IDLE_SECONDS):
+        self._idle_seconds = idle_seconds
+        self._last_event: dict[str, float] = {}
+        self._lock = threading.Lock()
+        self._timer: threading.Timer | None = None
+        self._pending: Set[str] = set()
+        self._callback: Callable[[str], None] | None = None
+
+    def set_callback(self, cb: Callable[[str], None]):
+        self._callback = cb
+
+    def touch(self, path: str):
+        """Record a file modification event."""
+        norm = os.path.normpath(path)
+        with self._lock:
+            self._last_event[norm] = time.monotonic()
+            self._pending.add(norm)
+        self._schedule_check()
+
+    def _schedule_check(self):
+        if self._timer and self._timer.is_alive():
+            self._timer.cancel()
+        self._timer = threading.Timer(self._idle_seconds, self._check_idle)
+        self._timer.daemon = True
+        self._timer.start()
+
+    def _check_idle(self):
+        now = time.monotonic()
+        ready: list[str] = []
+        with self._lock:
+            still_pending: Set[str] = set()
+            for p in list(self._pending):
+                last = self._last_event.get(p, 0)
+                if now - last >= self._idle_seconds:
+                    ready.append(p)
+                else:
+                    still_pending.add(p)
+            self._pending = still_pending
+        if self._callback:
+            for p in ready:
+                try:
+                    self._callback(p)
+                except Exception:
+                    pass
+        # Re-check if anything's still pending
+        with self._lock:
+            if self._pending:
+                self._schedule_check()
+
+
+class CapsuleEventHandler(FileSystemEventHandler):
+    """Dispatches file changes to the idle tracker."""
+
+    def __init__(self, tracker: IdleTracker, watch_extensions: set[str] | None = None):
+        self.tracker = tracker
+        self.watch_ext = watch_extensions or {".py", ".js", ".ts", ".rs", ".go", ".md",
+                                               ".txt", ".json", ".yaml", ".toml", ".css",
+                                               ".html", ".jsx", ".tsx", ".java", ".c", ".cpp",
+                                               ".h", ".sh", ".ps1", ".bat", ".sql", ".rb",
+                                               ".php", ".swift", ".kt", ".scala", ".zig"}
+
+    def _should_watch(self, path: str) -> bool:
+        ext = os.path.splitext(path)[1].lower()
+        return ext in self.watch_ext and not os.path.basename(path).startswith(".")
+
+    def on_modified(self, event: FileModifiedEvent):
+        if not event.is_directory and self._should_watch(event.src_path):
+            self.tracker.touch(event.src_path)
+
+    def on_created(self, event: FileCreatedEvent):
+        if not event.is_directory and self._should_watch(event.src_path):
+            self.tracker.touch(event.src_path)
+
+
+class FileWatcher:
+    """High-level watcher that monitors directories and fires snapshot callbacks."""
+
+    def __init__(self, paths: list[str], snapshot_callback: Callable[[str], None],
+                 idle_seconds: int = IDLE_SECONDS):
+        self.paths = [os.path.abspath(p) for p in paths]
+        self.tracker = IdleTracker(idle_seconds=idle_seconds)
+        self.tracker.set_callback(snapshot_callback)
+        self.handler = CapsuleEventHandler(self.tracker)
+        self.observer = Observer()
+
+    def start(self):
+        for p in self.paths:
+            if os.path.isdir(p):
+                self.observer.schedule(self.handler, p, recursive=True)
+        self.observer.start()
+
+    def stop(self):
+        self.observer.stop()
+        self.observer.join(timeout=5)
+        if self.tracker._timer and self.tracker._timer.is_alive():
+            self.tracker._timer.cancel()
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, *args):
+        self.stop()

capsule_narrative-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: capsule-narrative
+Version: 0.1.0
+Summary: A git-like filesystem that automatically creates narrative commits.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: watchdog>=4.0.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: textual>=0.41.0
+
+<h1 align="center">timecapsule</h1>
+<p align="center">
+  <em>A git-like filesystem that automatically creates narrative commits.</em>
+  <br>
+  <br>
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#how-it-works">How It Works</a> ·
+  <a href="#browsing">Browsing</a> ·
+  <a href="#ollama">LLM Narrator</a>
+  <br>
+  <img src="https://img.shields.io/badge/python-≥3.10-00ff88" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/license-MIT-00ff88" alt="MIT License">
+  <img src="https://img.shields.io/badge/version-0.1.0-00ff88" alt="Version 0.1.0">
+</p>
+
+---
+
+Every file has a story. timecapsule is a background daemon that watches your project folders and creates narrative commit messages from your changes — automatically.
+
+After 2 minutes of inactivity on a file, it snapshots the changes to a local Git repository. The commit message is generated by a small local LLM that summarizes *why* you made the changes, not just what changed.
+
+> *"Renamed parse() to tokenize() after the linter complained about naming — also dropped the unused xml import."*
+
+Over time, you get a searchable, browsable timeline of your work. Each file's history becomes a diary.
+
+## Quick Start
+
+```bash
+pip install capsule-narrative
+timecapsule
+```
+
+This watches the current directory tree. After 2 minutes of inactivity on a file, it snapshots the changes.
+
+```bash
+timecapsule /path/to/project          # Watch a specific directory
+timecapsule --idle 60                 # Faster snapshots (60s idle)
+timecapsule --once                    # One-time snapshot of all files
+timecapsule --browse                  # Open the timeline browser TUI
+timecapsule --status                  # Show capsule stats
+```
+
+## How It Works
+
+**File watcher.** A background daemon monitors file changes using `watchdog`. When a file hasn't been modified for 2 minutes (configurable), it triggers a snapshot — you've finished a thought.
+
+**Git backend.** Each file gets its own orphan branch in a dedicated bare repository at `~/.capsule/timecapsule`. The user's real Git repos are never touched. Branches are named by canonical path, so renaming or moving a file can continue its history.
+
+**Narrative commit messages.** The daemon diffs the current file against its last snapshot and generates a commit message that reads like a diary entry.
+
+## Browsing
+
+```bash
+timecapsule --browse
+```
+
+Opens a Textual TUI that shows:
+- **Tracked files** — all files with snapshots, sorted by most recent
+- **Timeline** — commit history for the selected file with narrative messages
+- **Diff preview** — file content at any selected snapshot
+
+You can scroll through history, search messages, and see exactly what your file looked like at any point.
+
+## Ollama
+
+timecapsule works without Ollama — it generates structural commit messages by default ("Added 3 lines to main.py (Python)"). But with Ollama installed, the messages transform into genuine narrative.
+
+```bash
+ollama pull qwen2.5-coder:1.5b
+```
+
+This ~1GB model runs on any modern laptop and generates commit messages in ~2 seconds. Smaller models like `llama3.2:1b` also work.
+
+The prompt context includes the file diff, the file path, and the previous commit message for continuity. The LLM explains *why* the changes were made, not just *what* changed.
+
+## Architecture
+
+```
+~/.capsule/
+├── timecapsule/          # Bare git repository
+│   └── refs/heads/       # One orphan branch per file
+│       ├── home-user-project-main-py
+│       ├── home-user-project-readme-md
+│       └── ...
+└── timeline.db           # SQLite index for fast queries
+```
+
+Each snapshot:
+1. Hashes the file content into a git blob
+2. Creates a tree object referencing the blob
+3. Commits the tree to the file's orphan branch (with parent if one exists)
+4. Records metadata in SQLite for fast timeline queries
+
+The SQLite store makes `timecapsule --browse` instant — no git log parsing needed.
+
+## FAQ
+
+**Q: Does it affect my existing Git repos?**
+A: No. timecapsule uses a dedicated bare repository at `~/.capsule/timecapsule`. Your `.git` directories are untouched.
+
+**Q: What file types are watched?**
+A: Common source files: `.py`, `.js`, `.ts`, `.rs`, `.go`, `.java`, `.md`, `.json`, `.yaml`, `.css`, `.html`, `.jsx`, `.tsx`, `.c`, `.cpp`, `.h`, `.sh`, `.rb`, `.sql`, and more.
+
+**Q: Can I delete the capsule database?**
+A: Yes — remove `~/.capsule/` to wipe everything. Snapshots are disposable by design.
+
+**Q: Does it work on Windows/Mac/Linux?**
+A: Yes. The watcher uses `watchdog` which works on all three platforms. The git operations are cross-platform.
+
+## License
+
+MIT
+
+---
+
+*Every file has a story.*
+
+<!-- test edit for timecapsule end-to-end -->

capsule_narrative-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+capsule/__init__.py,sha256=eTEFEXNQKdBnDdKtDdFLnrq1LyT_W7xk5a_DOpg7cK0,102
+capsule/daemon.py,sha256=T8uVxf2_MijOTR4bbCyqoZBCZwImJbrrE386bX8g4ik,5284
+capsule/git_ops.py,sha256=vc2f5xyKL-ZJy4G938j_dgwvvF7VqIhbDMXAKQEmmQc,5042
+capsule/narrator.py,sha256=7BKwqn4ilfDZgtloltStEwIVbNfuK8J3wVSBg9kCfOQ,5617
+capsule/store.py,sha256=x0YZgIk2BNMZ9PYh3FcIXg63DVEzc7eUYWkCKL_W0Fs,4364
+capsule/tui.py,sha256=D_HDRLBFD5IKKxE89XxGIR21e6saBepHIHRICD465BE,5579
+capsule/watcher.py,sha256=-7BypooljzCMYRFGwYdV3Egb9UcQHY311Kz2lzOcXRo,4445
+capsule_narrative-0.1.0.dist-info/METADATA,sha256=vjsbFTpoY5kqPygEP-6uPmleuQLTQeQh8pAHfsi6bNg,5154
+capsule_narrative-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+capsule_narrative-0.1.0.dist-info/entry_points.txt,sha256=xqQmBqrJKAFG3OXSf44RAY2olGHD0Os8gjeRr_xJ_Bs,52
+capsule_narrative-0.1.0.dist-info/top_level.txt,sha256=dDtT_YzY-mbydnnwGHTM4h1e3uvEXDJhkI2OqO3az_M,8
+capsule_narrative-0.1.0.dist-info/RECORD,,

capsule_narrative-0.1.0.dist-info/WHEEL

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

capsule_narrative-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+timecapsule = capsule.daemon:main

capsule_narrative-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+capsule