autocheckpoint 0.1.0__tar.gz

autocheckpoint-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: autocheckpoint
+Version: 0.1.0
+Summary: Never lose your code or your project context again. AI Development Continuity tool.
+Home-page: https://github.com/epicadidash/talvo-demo
+Author: AutoCheckpoint Maintainers
+Author-email: maintainers@autocheckpoint.dev
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: watchfiles>=0.21.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: pathspec>=0.12.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# AutoCheckpoint
+
+> Never lose your code or your project context again.
+
+AutoCheckpoint delivers **AI Development Continuity** for developers. It bridges the gap between VM losses and AI agent memory resets.
+
+```text
+Claude Session #1
+      ↓
+AutoCheckpoint
+      ↓
+Claude Session #2
+      ↓
+Cursor
+      ↓
+VS Code
+```
+
+## The Continuity Formula
+```
+Code Recovery + Context Recovery + AI Session Handoff
+```
+
+Unlike basic backup tools, AutoCheckpoint preserves both your code **and your project's portable brain** (decisions, intent, constraints, and current tasks). When your cloud VM dies, you restore your workspace and instantly hand off the context to the next AI session.
+
+---
+
+## 1. Hero Feature: AI Session Handoff
+
+Every AI developer knows this pain:
+```
+New Claude/Gemini session...
+"Okay... what were we doing again?"
+```
+
+With AutoCheckpoint, you never start from zero.
+
+### `handoff`
+```bash
+autocheckpoint handoff
+```
+Generates a clean project state summary containing your Goal, Current Focus, Decisions, Constraints, and Tasks. It saves this as a `.autocheckpoint/handoff.md` file (which is bundled automatically into your snapshots).
+
+### `handoff --markdown`
+```bash
+autocheckpoint handoff --markdown
+```
+Or use the shortcut `-m` to output the raw markdown directly to your terminal. Copy and paste it instantly into Claude Code, Cursor, Gemini, ChatGPT, or VS Code agents so your AI is instantly up to speed.
+
+---
+
+## 2. Recovery After a VM Loss
+
+When a cloud VM disappears, you don't just lose files; you lose momentum. 
+
+AutoCheckpoint lets you:
+> **Restore your code, project context, decisions, tasks, and session handoff after a VM loss.**
+
+*(Note: AutoCheckpoint restores your codebase, decisions, and handoff files, but not running processes, docker containers, or browser tabs.)*
+
+### `restore`
+Run this command on your fresh VM:
+```bash
+autocheckpoint restore
+```
+It will:
+1. Prompt for your backup location (e.g. Google Drive, OneDrive, network mount).
+2. Scan your backup directory and list your projects.
+3. Restore files and the complete `context.yaml` state.
+4. Auto-detect the saved handoff so you can immediately resume coding.
+
+---
+
+## 3. Installation
+
+```bash
+pip install -e .
+```
+
+---
+
+## 4. Quick Start
+
+```bash
+autocheckpoint init
+```
+1. Asks where to store backups (outside the project directory).
+2. Automatically starts the background watcher.
+3. Scans your project to automatically detect context (README, git history, codebase) and initializes your project's context.
+
+From then on, a snapshot is created automatically whenever you save file changes.
+
+---
+
+## 5. CLI Command Reference
+
+### Watcher Controls
+* `autocheckpoint start` — Start the watcher in the foreground.
+* `autocheckpoint start --background` — Run the watcher as a background daemon.
+* `autocheckpoint stop` — Stop the background watcher.
+* `autocheckpoint status` — Check the watcher's current state, snapshot count, and active context.
+
+### Context Management
+AutoCheckpoint maintains `.autocheckpoint/context.yaml` as the portable project brain.
+
+* `autocheckpoint context show` — View the current context summary.
+* `autocheckpoint context refresh` — Scan the codebase and git history with AI to auto-update context.
+* `autocheckpoint context set-intent "<goal>"` — Define the main goal of the project.
+* `autocheckpoint context set-focus "<focus>"` — Update your current active task.
+* `autocheckpoint context add-decision "<decision>"` — Record an architectural/design decision.
+* `autocheckpoint context add-constraint "<constraint>"` — Record environment or workspace limitations.
+* `autocheckpoint context add-task "<task>"` — Add a task to the todo list.
+* `autocheckpoint context done-task` — Interactively select and mark a task as completed.
+* `autocheckpoint context add-session "<summary>"` — Summarize the current session.
+* `autocheckpoint context summarize` — Run the interactive wizard to update all context fields at once.
+
+---
+
+## Ignore Patterns
+
+Create a `.autocheckpointignore` file in your project root to exclude directories:
+```ignore
+.git/
+node_modules/
+venv/
+__pycache__/
+```
+*(Note: `.autocheckpoint/context.yaml` is always captured in snapshots even if `.autocheckpoint/` is ignored.)*

autocheckpoint-0.1.0/README.md

@@ -0,0 +1,128 @@
+# AutoCheckpoint
+
+> Never lose your code or your project context again.
+
+AutoCheckpoint delivers **AI Development Continuity** for developers. It bridges the gap between VM losses and AI agent memory resets.
+
+```text
+Claude Session #1
+      ↓
+AutoCheckpoint
+      ↓
+Claude Session #2
+      ↓
+Cursor
+      ↓
+VS Code
+```
+
+## The Continuity Formula
+```
+Code Recovery + Context Recovery + AI Session Handoff
+```
+
+Unlike basic backup tools, AutoCheckpoint preserves both your code **and your project's portable brain** (decisions, intent, constraints, and current tasks). When your cloud VM dies, you restore your workspace and instantly hand off the context to the next AI session.
+
+---
+
+## 1. Hero Feature: AI Session Handoff
+
+Every AI developer knows this pain:
+```
+New Claude/Gemini session...
+"Okay... what were we doing again?"
+```
+
+With AutoCheckpoint, you never start from zero.
+
+### `handoff`
+```bash
+autocheckpoint handoff
+```
+Generates a clean project state summary containing your Goal, Current Focus, Decisions, Constraints, and Tasks. It saves this as a `.autocheckpoint/handoff.md` file (which is bundled automatically into your snapshots).
+
+### `handoff --markdown`
+```bash
+autocheckpoint handoff --markdown
+```
+Or use the shortcut `-m` to output the raw markdown directly to your terminal. Copy and paste it instantly into Claude Code, Cursor, Gemini, ChatGPT, or VS Code agents so your AI is instantly up to speed.
+
+---
+
+## 2. Recovery After a VM Loss
+
+When a cloud VM disappears, you don't just lose files; you lose momentum. 
+
+AutoCheckpoint lets you:
+> **Restore your code, project context, decisions, tasks, and session handoff after a VM loss.**
+
+*(Note: AutoCheckpoint restores your codebase, decisions, and handoff files, but not running processes, docker containers, or browser tabs.)*
+
+### `restore`
+Run this command on your fresh VM:
+```bash
+autocheckpoint restore
+```
+It will:
+1. Prompt for your backup location (e.g. Google Drive, OneDrive, network mount).
+2. Scan your backup directory and list your projects.
+3. Restore files and the complete `context.yaml` state.
+4. Auto-detect the saved handoff so you can immediately resume coding.
+
+---
+
+## 3. Installation
+
+```bash
+pip install -e .
+```
+
+---
+
+## 4. Quick Start
+
+```bash
+autocheckpoint init
+```
+1. Asks where to store backups (outside the project directory).
+2. Automatically starts the background watcher.
+3. Scans your project to automatically detect context (README, git history, codebase) and initializes your project's context.
+
+From then on, a snapshot is created automatically whenever you save file changes.
+
+---
+
+## 5. CLI Command Reference
+
+### Watcher Controls
+* `autocheckpoint start` — Start the watcher in the foreground.
+* `autocheckpoint start --background` — Run the watcher as a background daemon.
+* `autocheckpoint stop` — Stop the background watcher.
+* `autocheckpoint status` — Check the watcher's current state, snapshot count, and active context.
+
+### Context Management
+AutoCheckpoint maintains `.autocheckpoint/context.yaml` as the portable project brain.
+
+* `autocheckpoint context show` — View the current context summary.
+* `autocheckpoint context refresh` — Scan the codebase and git history with AI to auto-update context.
+* `autocheckpoint context set-intent "<goal>"` — Define the main goal of the project.
+* `autocheckpoint context set-focus "<focus>"` — Update your current active task.
+* `autocheckpoint context add-decision "<decision>"` — Record an architectural/design decision.
+* `autocheckpoint context add-constraint "<constraint>"` — Record environment or workspace limitations.
+* `autocheckpoint context add-task "<task>"` — Add a task to the todo list.
+* `autocheckpoint context done-task` — Interactively select and mark a task as completed.
+* `autocheckpoint context add-session "<summary>"` — Summarize the current session.
+* `autocheckpoint context summarize` — Run the interactive wizard to update all context fields at once.
+
+---
+
+## Ignore Patterns
+
+Create a `.autocheckpointignore` file in your project root to exclude directories:
+```ignore
+.git/
+node_modules/
+venv/
+__pycache__/
+```
+*(Note: `.autocheckpoint/context.yaml` is always captured in snapshots even if `.autocheckpoint/` is ignored.)*

autocheckpoint-0.1.0/autocheckpoint/__init__.py

@@ -0,0 +1,3 @@
+# AutoCheckpoint package
+# Triggering watcher snapshot on update
+__version__ = "0.1.0"

autocheckpoint-0.1.0/autocheckpoint/ai_context.py

@@ -0,0 +1,142 @@
+"""
+ai_context.py — Uses Gemini API to synthesize project context from raw signals.
+
+Requires GEMINI_API_KEY environment variable.
+Falls back to heuristic extraction if no API key is set.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Optional
+
+from autocheckpoint.scanner import gather_all_signals, build_prompt
+
+
+GEMINI_API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent"
+
+
+def _get_api_key() -> Optional[str]:
+    return os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")
+
+
+def _call_gemini(prompt: str, api_key: str) -> Optional[str]:
+    """Call Gemini REST API and return the text response."""
+    try:
+        import urllib.request
+        import urllib.error
+
+        payload = json.dumps({
+            "contents": [{"parts": [{"text": prompt}]}],
+            "generationConfig": {
+                "temperature": 0.2,
+                "maxOutputTokens": 1024,
+            }
+        }).encode("utf-8")
+
+        url = f"{GEMINI_API_URL}?key={api_key}"
+        req = urllib.request.Request(
+            url,
+            data=payload,
+            headers={"Content-Type": "application/json"},
+            method="POST"
+        )
+
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+            candidates = data.get("candidates", [])
+            if candidates:
+                parts = candidates[0].get("content", {}).get("parts", [])
+                if parts:
+                    return parts[0].get("text", "")
+    except Exception as e:
+        return None
+    return None
+
+
+def _parse_json_response(text: str) -> Optional[dict]:
+    """Extract JSON from the model response (strip markdown fences if present)."""
+    if not text:
+        return None
+    # Strip ```json ... ``` or ``` ... ```
+    text = re.sub(r"```(?:json)?", "", text).strip().rstrip("`").strip()
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        # Try to find a JSON object inside the text
+        match = re.search(r"\{.*\}", text, re.DOTALL)
+        if match:
+            try:
+                return json.loads(match.group())
+            except Exception:
+                pass
+    return None
+
+
+def _heuristic_fallback(signals: dict, project_name: str) -> dict:
+    """
+    If no API key is available, do simple heuristic extraction.
+    Tries README first, then git log.
+    """
+    intent = ""
+    readme = signals.get("readme", "")
+    if readme:
+        # Take first non-empty, non-heading line as intent
+        for line in readme.splitlines():
+            clean = line.strip().lstrip("#").strip()
+            if clean and len(clean) > 10:
+                intent = clean[:120]
+                break
+
+    if not intent:
+        manifest = signals.get("package_manifest", "")
+        desc_match = re.search(r"description[=:]\s*['\"]?([^'\"\n]+)", manifest, re.IGNORECASE)
+        if desc_match:
+            intent = desc_match.group(1).strip()[:120]
+
+    # Tasks from TODO comments
+    tasks = []
+    for line in signals.get("todo_comments", "").splitlines():
+        match = re.search(r"(?:TODO|FIXME)[:\s]+(.+)", line, re.IGNORECASE)
+        if match:
+            tasks.append(match.group(1).strip()[:80])
+        if len(tasks) >= 5:
+            break
+
+    return {
+        "intent": intent or f"{project_name} project",
+        "current_focus": "",
+        "decisions": [],
+        "known_constraints": [],
+        "tasks": tasks,
+    }
+
+
+def auto_detect_context(project_path: Path) -> dict:
+    """
+    Main entry point: gather signals, call Gemini, return structured context dict.
+    
+    Returns a dict with keys: intent, current_focus, decisions, tasks
+    """
+    signals = gather_all_signals(project_path)
+    api_key = _get_api_key()
+
+    if api_key:
+        prompt = build_prompt(project_path, signals)
+        raw_response = _call_gemini(prompt, api_key)
+        parsed = _parse_json_response(raw_response)
+        if parsed:
+            # Normalize: ensure expected keys exist
+            return {
+                "intent":            str(parsed.get("intent", "")).strip(),
+                "current_focus":     str(parsed.get("current_focus", "")).strip(),
+                "decisions":         [str(d).strip() for d in parsed.get("decisions", []) if str(d).strip()],
+                "known_constraints": [str(c).strip() for c in parsed.get("known_constraints", []) if str(c).strip()],
+                "tasks":             [str(t).strip() for t in parsed.get("tasks", []) if str(t).strip()],
+            }
+
+    # Fallback: heuristic extraction (no API key or API call failed)
+    return _heuristic_fallback(signals, project_path.name)