capsule-narrative 0.1.0__tar.gz

capsule_narrative-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,118 @@
+<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/capsule/__init__.py

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

capsule_narrative-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_narrative-0.1.0/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()]