gitcast 1.0.0__py3-none-any.whl

core/capture.py

@@ -0,0 +1,258 @@
+import os
+import subprocess
+import time
+from pathlib import Path
+from datetime import datetime
+from config.settings import STORAGE_DIR
+from core.log_stream import stream_log
+from api.analytics import track
+BASE_DIR = STORAGE_DIR.parent.parent
+from .framing import add_programming_frame
+
+
+GIT_DIFF_EXCLUDES = [
+    ":(exclude)config/session_token.txt",
+    ":(exclude)storage/data/**",
+    ":(exclude).playwright-mcp/**",
+    ":(exclude)memory.md",
+    ":(exclude)*gitcast-app*.png",
+]
+
+
+# ── Screenshot capture ────────────────────────────────────────────────────────
+
+def capture_active_window(delay: float = 5.0) -> dict:
+    """
+    Takes a screenshot of the entire screen and saves it to storage/data/screenshots.
+    Returns a dict with the image path and dimensions.
+    """
+    if delay > 0:
+        if delay < 1.0:
+            # Short buffer delay
+            time.sleep(delay)
+        else:
+            # Full countdown delay
+            stream_log("Capture", "INFO", f"starting in {int(delay)}s; switch to target window")
+            for i in range(int(delay), 0, -1):
+                print(f"  {i}...")
+                # Terminal bell (ASCII 7)
+                import sys
+                sys.stdout.write('\a')
+                sys.stdout.flush()
+                time.sleep(1)
+
+    screenshot_dir = STORAGE_DIR / "screenshots"
+    screenshot_dir.mkdir(parents=True, exist_ok=True)
+
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"capture_{timestamp}.png"
+    filepath = screenshot_dir / filename
+
+    try:
+        import mss
+        from PIL import Image
+    except ImportError as exc:
+        return {
+            "success": False,
+            "path": "",
+            "width": 0,
+            "height": 0,
+            "timestamp": timestamp,
+            "error": str(exc),
+            "reason": "missing_dependency",
+        }
+
+    try:
+        with mss.mss() as sct:
+            monitor = sct.monitors[1]  # primary monitor
+            screenshot = sct.grab(monitor)
+            img = Image.frombytes("RGB", screenshot.size, screenshot.bgra, "raw", "BGRX")
+            img.save(str(filepath))
+            width = screenshot.width
+            height = screenshot.height
+    except Exception as exc:
+        try:
+            img = Image.new("RGB", (1920, 1080), color=(30, 30, 30))
+            img.save(str(filepath))
+            stream_log("Capture", "WARN", f"MSS capture failed ({exc}). Created blank fallback screenshot.")
+            width = 1920
+            height = 1080
+        except Exception as fallback_exc:
+            return {
+                "success": False,
+                "path": "",
+                "width": 0,
+                "height": 0,
+                "timestamp": timestamp,
+                "error": f"MSS failed: {exc}, Fallback failed: {fallback_exc}",
+                "reason": "capture_failed",
+            }
+
+    # Return relative path for web/API consistency
+    relative_path = str(filepath.relative_to(BASE_DIR)).replace("\\", "/")
+    stream_log("Capture", "OK", f"screenshot saved: {relative_path}")
+
+    return {
+        "success": True,
+        "path": relative_path,
+        "width": width,
+        "height": height,
+        "timestamp": timestamp,
+        "error": "",
+        "reason": "ok",
+    }
+
+
+# ── Git diff extraction ───────────────────────────────────────────────────────
+
+def get_git_diff(cwd: str = None) -> dict:
+    """
+    Runs git diff HEAD in the given directory.
+    Falls back to the user's home directory if no cwd is given.
+    Returns a dict with the diff text and a status flag.
+    """
+    target_dir = cwd or str(Path.home())
+
+    try:
+        diff_cmd = ["git", "diff", "HEAD", "--", ".", *GIT_DIFF_EXCLUDES]
+        result = subprocess.run(
+            diff_cmd,
+            cwd=target_dir,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+        )
+
+        diff_text = result.stdout.strip()
+
+        if result.returncode != 0:
+            return {
+                "success": False,
+                "diff": "",
+                "error": result.stderr.strip(),
+                "reason": "git_error",
+            }
+
+        if not diff_text:
+            # try staged changes if working tree diff is empty
+            staged = subprocess.run(
+                ["git", "diff", "--cached", "--", ".", *GIT_DIFF_EXCLUDES],
+                cwd=target_dir,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=5,
+            )
+            diff_text = staged.stdout.strip()
+
+        return {
+            "success": True,
+            "diff": diff_text[:3000],  # cap at 3000 chars to stay inside token limits
+            "error": "",
+            "reason": "ok" if diff_text else "no_changes",
+        }
+
+    except FileNotFoundError:
+        return {
+            "success": False,
+            "diff": "",
+            "error": "git not found",
+            "reason": "no_git",
+        }
+    except subprocess.TimeoutExpired:
+        return {
+            "success": False,
+            "diff": "",
+            "error": "git diff timed out",
+            "reason": "timeout",
+        }
+    except Exception as e:
+        return {
+            "success": False,
+            "diff": "",
+            "error": str(e),
+            "reason": "unknown",
+        }
+
+
+# ── Detect working directory ──────────────────────────────────────────────────
+
+def detect_working_directory() -> str:
+    """
+    Attempts to find the most likely git repo the user is working in.
+    Checks the script's own directory first, then walks up from cwd.
+    """
+    candidates = [
+        Path(__file__).resolve().parent.parent,  # project root
+        Path.cwd(),
+        Path(os.environ.get("USERPROFILE", "")) / "Documents" / "context-engine",
+        Path.home(),
+    ]
+
+    for candidate in candidates:
+        try:
+            result = subprocess.run(
+                ["git", "rev-parse", "--show-toplevel"],
+                cwd=str(candidate),
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=3,
+            )
+            if result.returncode == 0:
+                return result.stdout.strip()
+        except Exception:
+            continue
+
+    return str(Path.home())
+
+
+def run_capture(delay: float = 5.0) -> dict:
+    working_dir = detect_working_directory()
+    screenshot = capture_active_window(delay=delay)
+    
+    # Apply programming frame if capture succeeded
+    if screenshot.get("success") and screenshot.get("path"):
+        try:
+            framed_path = add_programming_frame(screenshot["path"])
+            screenshot["framed_path"] = framed_path
+            # By default, use the framed path for downstream preview/publishing
+            screenshot["raw_path"] = screenshot["path"]
+            screenshot["path"] = framed_path
+        except Exception as e:
+            stream_log("Capture", "WARN", f"framing failed: {e}")
+            screenshot["framed_path"] = ""
+
+    git_diff = get_git_diff(working_dir)
+    if screenshot.get("success"):
+        track("capture_completed", {
+            "has_git_diff": bool(git_diff.get("diff")),
+            "ocr_confidence": 0,
+            "ocr_reliable": False,
+        })
+    return {
+        "screenshot": screenshot,
+        "working_dir": working_dir,
+        "git_diff": git_diff,
+        "timestamp": screenshot.get("timestamp", datetime.now().strftime("%Y%m%d_%H%M%S")),
+    }
+
+
+# ── Test ──────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    result = run_capture()
+    print("\n=== CAPTURE RESULT ===")
+    print(f"Screenshot success: {result['screenshot'].get('success')}")
+    print(f"Screenshot: {result['screenshot']['path']}")
+    print(f"Working dir: {result['working_dir']}")
+    print(f"Git diff success: {result['git_diff']['success']}")
+    print(f"Git diff reason: {result['git_diff']['reason']}")
+    if result["screenshot"].get("error"):
+        print(f"Screenshot error: {result['screenshot']['error']}")
+    if result['git_diff']['diff']:
+        print(f"Diff preview:\n{result['git_diff']['diff'][:200]}...")

core/codebase_reader.py

@@ -0,0 +1,90 @@
+import os
+from pathlib import Path
+
+# [CodebaseReader] module for summarising repo structure for articles
+
+def read_repo_structure(repo_path: str) -> str:
+    """
+    Walks git repo, returns a string summary of filename -> first 50 lines.
+    Caps total output at 6000 characters.
+    """
+    repo_root = Path(repo_path)
+    if not repo_root.exists():
+        return "Repo path does not exist."
+
+    ignore_dirs = {".git", "node_modules", "venv", "__pycache__", ".npm-global"}
+    summary_parts = []
+    total_chars = 0
+    char_limit = 4000 # Reduced from 6000
+
+    for root, dirs, files in os.walk(repo_root):
+        # In-place modification to skip ignored directories
+        dirs[:] = [d for d in dirs if d not in ignore_dirs]
+        
+        for file in files:
+            if total_chars >= char_limit:
+                break
+                
+            file_path = Path(root) / file
+            
+            # Skip binary or irrelevant files
+            if file.lower().endswith(('.png', '.jpg', '.jpeg', '.gif', '.ico', '.pyc', '.exe', '.bin', '.json', '.txt', '.log')):
+                continue
+
+            try:
+                with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+                    content = f.read(500) # Read less per file
+                    lines = content.splitlines()[:15] # Only first 15 lines
+                    snippet = "\n".join(lines)
+                    
+                    rel_path = file_path.relative_to(repo_root)
+                    entry = f"--- FILE: {rel_path} ---\n{snippet}\n"
+                    
+                    if total_chars + len(entry) > char_limit:
+                        summary_parts.append(f"--- FILE: {rel_path} --- (TRUNCATED)")
+                        total_chars = char_limit
+                        break
+                    
+                    summary_parts.append(entry)
+                    total_chars += len(entry)
+            except Exception as e:
+                print(f"[CodebaseReader] Error reading {file}: {e}")
+
+        if total_chars >= char_limit:
+            break
+
+    return "\n".join(summary_parts)
+
+def get_key_files(repo_path: str) -> str:
+    """Returns content of key files like README or main entry points."""
+    repo_root = Path(repo_path)
+    key_names = {"README.md", "main.py", "app.py", "index.py", "cli.py", "server.py"}
+    summary_parts = []
+    
+    for name in key_names:
+        file_path = repo_root / name
+        if file_path.exists():
+            try:
+                with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+                    content = f.read(2000)
+                    summary_parts.append(f"=== KEY FILE: {name} ===\n{content}\n")
+            except Exception as e:
+                print(f"[CodebaseReader] Error reading key file {name}: {e}")
+                
+    return "\n".join(summary_parts)
+
+def summarise_for_prompt(repo_path: str) -> str:
+    """Combines structure and key files into a single string for AI injection."""
+    print(f"[CodebaseReader] Summarising {repo_path}...")
+    structure = read_repo_structure(repo_path)
+    key_files = get_key_files(repo_path)
+    
+    summary = f"CODEBASE ARCHITECTURE SUMMARY:\n\n{key_files}\n\nFILE STRUCTURE SNIPPETS:\n{structure}"
+    return summary
+
+if __name__ == "__main__":
+    print("=== CODEBASE READER TEST ===")
+    current_dir = os.getcwd()
+    summary = summarise_for_prompt(current_dir)
+    print(summary[:1000] + "...")
+    print(f"\nTotal summary length: {len(summary)} chars")

core/framing.py

@@ -0,0 +1,86 @@
+import os
+from PIL import Image, ImageDraw, ImageFilter, ImageOps
+
+def add_programming_frame(image_path: str) -> str:
+    """
+    Wraps a screenshot in a macOS-style window frame with traffic lights
+    and a drop shadow. Saves the result as a new file.
+    """
+    if not os.path.exists(image_path):
+        return image_path
+
+    # Load original image
+    img = Image.open(image_path).convert("RGBA")
+    
+    # Constants for the frame
+    CORNER_RADIUS = 12
+    HEADER_HEIGHT = 36
+    PADDING = 60 # Outer padding for shadow and background
+    BG_COLOR = (30, 30, 30, 255) # Dark grey for the "window"
+    SHADOW_COLOR = (0, 0, 0, 100)
+    
+    # Traffic light colors
+    RED = (255, 95, 87, 255)
+    YELLOW = (255, 189, 46, 255)
+    GREEN = (40, 201, 64, 255)
+    LIGHT_SIZE = 12
+    LIGHT_SPACING = 20
+    LIGHT_MARGIN_LEFT = 16
+    LIGHT_MARGIN_TOP = (HEADER_HEIGHT - LIGHT_SIZE) // 2
+
+    # 1. Create the window content (Header + Screenshot)
+    win_width = img.width
+    win_height = img.height + HEADER_HEIGHT
+    
+    # Create window background with rounded corners
+    window = Image.new("RGBA", (win_width, win_height), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(window)
+    
+    # Draw rounded rectangle for the whole window
+    draw.rounded_rectangle(
+        [0, 0, win_width, win_height],
+        radius=CORNER_RADIUS,
+        fill=BG_COLOR
+    )
+    
+    # Paste the original screenshot below the header
+    window.paste(img, (0, HEADER_HEIGHT), img if img.mode == 'RGBA' else None)
+    
+    # Draw traffic lights
+    for i, color in enumerate([RED, YELLOW, GREEN]):
+        x = LIGHT_MARGIN_LEFT + (i * LIGHT_SPACING)
+        y = LIGHT_MARGIN_TOP
+        draw.ellipse([x, y, x + LIGHT_SIZE, y + LIGHT_SIZE], fill=color)
+
+    # 2. Add Drop Shadow
+    # Create a canvas larger than the window to hold the shadow
+    canvas_width = win_width + (PADDING * 2)
+    canvas_height = win_height + (PADDING * 2)
+    canvas = Image.new("RGBA", (canvas_width, canvas_height), (0, 0, 0, 0))
+    
+    # Create shadow mask
+    shadow_mask = Image.new("L", (win_width, win_height), 0)
+    shadow_draw = ImageDraw.Draw(shadow_mask)
+    shadow_draw.rounded_rectangle([0, 0, win_width, win_height], radius=CORNER_RADIUS, fill=180)
+    
+    # Blur the shadow
+    shadow = Image.new("RGBA", (win_width, win_height), (0, 0, 0, 150))
+    shadow.putalpha(shadow_mask)
+    shadow = shadow.filter(ImageFilter.GaussianBlur(radius=25))
+    
+    # Offset shadow slightly
+    canvas.paste(shadow, (PADDING + 5, PADDING + 10))
+    
+    # Paste the window on top
+    canvas.paste(window, (PADDING, PADDING), window)
+
+    # Save framed image
+    base, ext = os.path.splitext(image_path)
+    framed_path = f"{base}_framed.png"
+    canvas.save(framed_path)
+    
+    return framed_path
+
+if __name__ == "__main__":
+    # Test with a dummy image if exists or just print
+    print("Framing module ready. Use add_programming_frame(path) to test.")

core/hotkey.py

@@ -0,0 +1,21 @@
+from pynput import keyboard
+
+_listener = None
+
+def start_hotkey_listener(callback):
+    global _listener
+    def on_activate():
+        callback()
+
+    _listener = keyboard.GlobalHotKeys({
+        '<ctrl>+<alt>+s': on_activate
+    })
+    _listener.start()
+    return _listener
+
+def stop_hotkey_listener():
+    global _listener
+    if _listener:
+        _listener.stop()
+        _listener = None
+        print("[Hotkey] Listener stopped.")

core/log_stream.py

@@ -0,0 +1,50 @@
+from collections import deque
+from datetime import datetime
+from threading import Lock
+
+
+LOG_BUFFER = deque(maxlen=100)
+_LOCK = Lock()
+_NEXT_ID = 0
+_LEVELS = {"OK", "INFO", "WARN", "ERROR", "AI", "ROUTER"}
+
+
+def stream_log(module: str, level: str, message: str) -> dict:
+    global _NEXT_ID
+
+    normalized_level = level.upper().strip()
+    if normalized_level not in _LEVELS:
+        normalized_level = "INFO"
+
+    entry = {
+        "time": datetime.now().strftime("%H:%M:%S"),
+        "level": normalized_level,
+        "module": module.upper().strip(),
+        "message": message.strip(),
+    }
+
+    with _LOCK:
+        _NEXT_ID += 1
+        stored = {"id": _NEXT_ID, **entry}
+        LOG_BUFFER.append(stored)
+
+    print(f"[{entry['module']}] {entry['message']}")
+    return entry
+
+
+def get_recent_logs() -> list:
+    with _LOCK:
+        return [
+            {key: value for key, value in entry.items() if key != "id"}
+            for entry in list(LOG_BUFFER)[-50:]
+        ]
+
+
+def get_logs_after(last_id: int) -> list:
+    with _LOCK:
+        return [entry.copy() for entry in LOG_BUFFER if entry["id"] > last_id]
+
+
+def get_latest_log_id() -> int:
+    with _LOCK:
+        return LOG_BUFFER[-1]["id"] if LOG_BUFFER else 0

core/ocr.py

@@ -0,0 +1,173 @@
+import os
+import pytesseract
+from PIL import Image
+from pathlib import Path
+from config.settings import get_ocr_threshold
+from core.log_stream import stream_log
+
+# ── Tesseract path (Windows) ──────────────────────────────────────────────────
+
+# explicitly set the tesseract path for Windows
+# if installed elsewhere, update this path
+TESSERACT_PATH = r"C:\Program Files\Tesseract-OCR\tesseract.exe"
+
+if Path(TESSERACT_PATH).exists():
+    pytesseract.pytesseract.tesseract_cmd = TESSERACT_PATH
+else:
+    # fallback — rely on PATH
+    stream_log("OCR", "WARN", "Tesseract not found at default path. Relying on PATH.")
+
+
+# ── OCR runner ────────────────────────────────────────────────────────────────
+
+def run_ocr(image_path: str) -> dict:
+    """
+    Runs Tesseract OCR on the given image.
+    Returns extracted text, confidence score, and a flag indicating
+    whether the result is reliable enough to send to the AI.
+
+    If confidence is below threshold, the caller should send the
+    raw screenshot to the Gemini vision endpoint instead.
+    """
+    threshold = get_ocr_threshold()  # default 60, set in config/settings.py
+
+    try:
+        img = Image.open(image_path)
+
+        # get detailed output including confidence scores per word
+        data = pytesseract.image_to_data(
+            img,
+            output_type=pytesseract.Output.DICT,
+            config="--psm 6"  # assume uniform block of text — best for code/IDE
+        )
+
+        # calculate mean confidence from words that were actually detected
+        confidences = [
+            int(c) for c in data["conf"]
+            if str(c).strip() != "-1" and str(c).strip() != ""
+        ]
+
+        if not confidences:
+            stream_log("OCR", "WARN", "confidence low (0%); no text detected")
+            return _low_confidence_result("No text detected in screenshot")
+
+        mean_confidence = sum(confidences) / len(confidences)
+
+        # extract clean text — filter out empty strings
+        raw_text = pytesseract.image_to_string(
+            img,
+            config="--psm 6"
+        )
+        clean_text = _clean_ocr_text(raw_text)
+
+        is_reliable = mean_confidence >= threshold
+
+        level = "OK" if is_reliable else "WARN"
+        message = (
+            f"confidence {mean_confidence:.1f}%"
+            if is_reliable
+            else f"confidence low ({mean_confidence:.1f}%) - vision fallback"
+        )
+        stream_log("OCR", level, message)
+
+        return {
+            "success": True,
+            "text": clean_text if is_reliable else "",
+            "raw_text": clean_text,
+            "confidence": round(mean_confidence, 1),
+            "reliable": is_reliable,
+            "use_vision_fallback": not is_reliable,
+            "error": "",
+        }
+
+    except FileNotFoundError:
+        return _error_result(f"Screenshot file not found: {image_path}")
+    except pytesseract.TesseractNotFoundError:
+        return _error_result(
+            "Tesseract executable not found. "
+            "Install from https://github.com/UB-Mannheim/tesseract/wiki"
+        )
+    except Exception as e:
+        return _error_result(str(e))
+
+
+# ── Text cleaning ─────────────────────────────────────────────────────────────
+
+def _clean_ocr_text(raw: str) -> str:
+    """
+    Cleans raw Tesseract output for use in AI prompts.
+    Removes excessive whitespace and blank lines while
+    preserving code indentation structure.
+    """
+    lines = raw.splitlines()
+
+    # remove completely empty lines that are repeated
+    cleaned = []
+    prev_empty = False
+    for line in lines:
+        is_empty = line.strip() == ""
+        if is_empty and prev_empty:
+            continue  # skip consecutive blank lines
+        cleaned.append(line)
+        prev_empty = is_empty
+
+    result = "\n".join(cleaned).strip()
+
+    # cap at 2000 chars to stay within token budget
+    if len(result) > 2000:
+        result = result[:2000] + "\n... [truncated]"
+
+    return result
+
+
+# ── Result helpers ────────────────────────────────────────────────────────────
+
+def _low_confidence_result(reason: str) -> dict:
+    return {
+        "success": True,
+        "text": "",
+        "raw_text": "",
+        "confidence": 0.0,
+        "reliable": False,
+        "use_vision_fallback": True,
+        "error": reason,
+    }
+
+
+def _error_result(error: str) -> dict:
+    stream_log("OCR", "ERROR", error)
+    return {
+        "success": False,
+        "text": "",
+        "raw_text": "",
+        "confidence": 0.0,
+        "reliable": False,
+        "use_vision_fallback": True,
+        "error": error,
+    }
+
+
+# ── Test ──────────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import sys
+    from core.capture import capture_active_window
+
+    print("[OCR] Taking a fresh screenshot to test on...")
+    screenshot = capture_active_window()
+
+    if not screenshot["path"]:
+        print("[OCR] Screenshot failed — cannot test OCR")
+        sys.exit(1)
+
+    print(f"[OCR] Running OCR on: {screenshot['path']}")
+    result = run_ocr(screenshot["path"])
+
+    print("\n=== OCR RESULT ===")
+    print(f"Success:           {result['success']}")
+    print(f"Confidence:        {result['confidence']}%")
+    print(f"Reliable:          {result['reliable']}")
+    print(f"Use vision fallback: {result['use_vision_fallback']}")
+    print(f"Error:             {result['error'] or 'none'}")
+    print(f"\nExtracted text preview:")
+    print(result['raw_text'][:500] if result['raw_text'] else "(none)")