terminalpulse 0.1.0__tar.gz

terminalpulse-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/

terminalpulse-0.1.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: terminalpulse
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: networkx>=3.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Requires-Dist: watchdog>=4.0

terminalpulse-0.1.0/README.md

@@ -0,0 +1,55 @@
+# TerminalPulse ⚡
+
+Short-term memory for AI agents. Captures your coding context in real time — silently.
+
+## The Problem
+Every AI tool today requires you to manually copy-paste your error. That takes 30 seconds and breaks your flow.
+
+## The Solution
+TerminalPulse watches your terminal, editor, and filesystem in the background. When something goes wrong, just type `pulse fix` — no copy-pasting, no explaining.
+
+## Install
+pip install terminalpulse
+
+## Setup
+pulse init
+source ~/.bashrc
+pulse start --watch .
+
+## Commands
+| Command | What it does |
+|---|---|
+| `pulse init` | Auto-injects shell hook into .bashrc |
+| `pulse start` | Starts the background daemon |
+| `pulse state` | Shows current coding context as JSON |
+| `pulse fix` | Sends hottest error to TerminalMind for auto-fix |
+| `pulse init-windows` | Setup instructions for Windows focus tracking |
+
+## How it works
+Three streams feed a time-decaying knowledge graph:
+- **Focus** — which file is open in VS Code
+- **Activity** — which files were just saved
+- **Distress** — which terminal commands just failed
+
+Older events decay automatically so the AI always gets current context.
+
+## Test Results
+| Test | Error Type | Result |
+|---|---|---|
+| Test 1 | ZeroDivisionError | Fixed and verified |
+| Test 2 | ModuleNotFoundError | Captured (fix depends on TerminalMind version) |
+| Test 3 | SyntaxError | Fixed and verified |
+
+## Requirements
+- Python 3.10+
+- WSL Ubuntu (for Linux daemon)
+- terminalmind (for pulse fix command)
+
+## Architecture
+```
+VS Code (Windows) → HTTP:7077 → pulsed daemon → ~/.devpulse_state.json
+Terminal errors → Unix socket → pulsed daemon → ~/.devpulse_state.json
+File saves → watchdog → pulsed daemon → ~/.devpulse_state.json
+                                              ↓
+                                         pulse fix → TerminalMind → Auto-fix
+```

terminalpulse-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "terminalpulse"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "typer>=0.12",
+    "rich>=13.7",
+    "watchdog>=4.0",
+    "networkx>=3.2",
+    "pydantic>=2.6",
+]
+
+[project.scripts]
+pulse = "terminalpulse.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

terminalpulse-0.1.0/terminalpulse/cli.py

@@ -0,0 +1,108 @@
+import os, sys, json, subprocess
+from pathlib import Path
+import typer, asyncio
+from rich import print
+from . import daemon as _daemon
+
+app = typer.Typer(help="TerminalPulse — short-term memory for AI agents")
+STATE_FILE = Path.home() / ".devpulse_state.json"
+
+
+@app.command()
+def start(watch: str = typer.Option(".", help="Directory to watch")):
+    """Run the pulse daemon in the foreground."""
+    asyncio.run(_daemon.main(os.path.abspath(watch)))
+
+
+@app.command()
+def state():
+    """Print the current hottest context."""
+    if not STATE_FILE.exists():
+        print("[yellow]No state yet. Is the daemon running?[/]")
+        raise typer.Exit(1)
+    print(json.loads(STATE_FILE.read_text()))
+
+
+@app.command()
+def fix():
+    """Read hottest error and active file, send to TerminalMind to fix."""
+    if not STATE_FILE.exists():
+        print("[yellow]No state yet. Is the daemon running?[/]")
+        raise typer.Exit(1)
+
+    state_data = json.loads(STATE_FILE.read_text())
+    hottest = state_data.get("hottest", [])
+
+    error = next((e for e in hottest if e["type"] == "command_failed"), None)
+    focus = next((e for e in hottest if e["type"] == "focus_changed"), None)
+
+    if not error:
+        print("[yellow]No recent errors found in pulse state.[/]")
+        raise typer.Exit(0)
+
+    cmd = error.get("cmd", "unknown command")
+    exit_code = error.get("exit_code", 1)
+    active_file = focus.get("path", "unknown file") if focus else "unknown file"
+    stderr = error.get("stderr_tail", None)
+
+    if stderr:
+        context = f"Command: `{cmd}` failed with exit code {exit_code}.\nActive file: {active_file}.\nError output:\n{stderr.replace('|', chr(10))}"
+        print(f"[cyan]Sending to TerminalMind with full error context[/]")
+        subprocess.run(["tmind", "ask", context])
+    else:
+        context = f"Command failed: `{cmd}` (exit code {exit_code}). Active file: {active_file}."
+        print(f"[cyan]Sending to TerminalMind:[/] {context}")
+        subprocess.run(["tmind", "heal", cmd], cwd=error.get("cwd", "."))
+
+@app.command()
+def init():
+    """Auto-setup: injects shell hook into .bashrc so pulse works automatically."""
+    bashrc = Path.home() / ".bashrc"
+
+    hook = '''
+# TerminalPulse hook
+_pulse_sock="$HOME/.terminalpulse.sock"
+_pulse_last_cmd=""
+_pulse_preexec() {
+  [[ "$BASH_COMMAND" == _pulse_* ]] && return
+  _pulse_last_cmd="$BASH_COMMAND"
+}
+trap '_pulse_preexec' DEBUG
+_pulse_precmd() {
+  local code=$?
+  if [ $code -ne 0 ] && [ -n "$_pulse_last_cmd" ] && [ -S "$_pulse_sock" ]; then
+    printf \'{"type":"command_failed","cmd":"%s","exit_code":%d,"cwd":"%s"}\\n\' \\
+      "$_pulse_last_cmd" "$code" "$PWD" | nc -U "$_pulse_sock" 2>/dev/null
+  fi
+  _pulse_last_cmd=""
+}
+PROMPT_COMMAND="_pulse_precmd${PROMPT_COMMAND:+;$PROMPT_COMMAND}"
+'''
+
+    content = bashrc.read_text() if bashrc.exists() else ""
+    if "TerminalPulse hook" in content:
+        print("[yellow]TerminalPulse hook already exists in .bashrc — skipping.[/]")
+        return
+
+    with open(bashrc, "a") as f:
+        f.write(hook)
+
+    print("[green]TerminalPulse hook added to ~/.bashrc[/]")
+    print("[cyan]Run: source ~/.bashrc to activate[/]")
+
+
+@app.command()
+def init_windows():
+    """Print instructions to set up the Windows focus tracker."""
+    print("[cyan]Windows Setup Instructions:[/]")
+    print("")
+    print("1. Open Windows PowerShell")
+    print("2. Run this command:")
+    print(f"[green]   python {Path.home() / 'terminalpulse/terminalpulse/windows_tracker.py'}[/]")
+    print("")
+    print("3. Keep PowerShell open while coding.")
+    print("[yellow]Tip: Add it to Windows Task Scheduler to auto-start on login.[/]")
+
+
+if __name__ == "__main__":
+    app()

terminalpulse-0.1.0/terminalpulse/daemon.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+import asyncio, json, os, signal
+from pathlib import Path
+from watchdog.observers import Observer
+from watchdog.events import FileSystemEventHandler
+from .events import Event, EventType
+from .graph import PulseGraph
+
+SOCK_PATH = Path.home() / ".terminalpulse.sock"
+WATCH_EXTS = {".py", ".js", ".ts", ".tsx", ".rs", ".go", ".md", ".toml", ".json"}
+
+
+class FsHandler(FileSystemEventHandler):
+    def __init__(self, queue: asyncio.Queue, loop: asyncio.AbstractEventLoop):
+        self.queue = queue
+        self.loop = loop
+
+    def on_modified(self, event):
+        if event.is_directory: return
+        p = Path(event.src_path)
+        if p.suffix not in WATCH_EXTS: return
+        ev = Event(type=EventType.FILE_SAVED, path=str(p), cwd=os.getcwd())
+        self.loop.call_soon_threadsafe(self.queue.put_nowait, ev)
+
+
+async def handle_shell_client(reader, writer, queue: asyncio.Queue):
+    data = await reader.readline()
+    try:
+        payload = json.loads(data)
+        ev = Event(**payload)
+        await queue.put(ev)
+    except Exception as e:
+        print(f"bad payload: {e}")
+    writer.close()
+
+
+async def handle_http_client(reader, writer, queue: asyncio.Queue):
+    data = b""
+    while True:
+        chunk = await reader.read(1024)
+        if not chunk:
+            break
+        data += chunk
+        if b"\r\n\r\n" in data:
+            break
+    try:
+        body = data.split(b"\r\n\r\n", 1)[1]
+        payload = json.loads(body)
+        ev = Event(**payload)
+        await queue.put(ev)
+        writer.write(b"HTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nOK")
+    except Exception as e:
+        print(f"bad http payload: {e}")
+        writer.write(b"HTTP/1.1 400 Bad Request\r\nContent-Length: 2\r\n\r\nER")
+    await writer.drain()
+    writer.close()
+
+
+async def consumer(queue: asyncio.Queue, graph: PulseGraph):
+    while True:
+        ev = await queue.get()
+        graph.ingest(ev)
+        print(f"⚡ {ev.type.value}  {ev.path or ev.cmd or ''}")
+
+
+async def main(watch_dir: str):
+    queue: asyncio.Queue = asyncio.Queue()
+    graph = PulseGraph()
+    loop = asyncio.get_running_loop()
+
+    obs = Observer()
+    obs.schedule(FsHandler(queue, loop), watch_dir, recursive=True)
+    obs.start()
+
+    if SOCK_PATH.exists(): SOCK_PATH.unlink()
+    server = await asyncio.start_unix_server(
+        lambda r, w: handle_shell_client(r, w, queue), path=str(SOCK_PATH)
+    )
+    os.chmod(SOCK_PATH, 0o600)
+
+    http_server = await asyncio.start_server(
+        lambda r, w: handle_http_client(r, w, queue),
+        "0.0.0.0", 7077
+    )
+
+    print(f"🧠 pulsed listening on {SOCK_PATH}, watching {watch_dir}")
+    print(f"🌐 HTTP endpoint on port 7077 for Windows bridge")
+    try:
+        await asyncio.gather(
+            server.serve_forever(),
+            http_server.serve_forever(),
+            consumer(queue, graph)
+        )
+    finally:
+        obs.stop(); obs.join()
+        if SOCK_PATH.exists(): SOCK_PATH.unlink()

terminalpulse-0.1.0/terminalpulse/events.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+import time
+from enum import Enum
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class EventType(str, Enum):
+    FILE_SAVED = "file_saved"
+    COMMAND_FAILED = "command_failed"
+    COMMAND_OK = "command_ok"
+    FOCUS_CHANGED = "focus_changed"
+
+
+class Event(BaseModel):
+    type: EventType
+    ts: float = Field(default_factory=time.time)
+    cwd: Optional[str] = None
+    # type-specific:
+    path: Optional[str] = None          # FILE_SAVED, FOCUS_CHANGED
+    cmd: Optional[str] = None           # COMMAND_*
+    exit_code: Optional[int] = None     # COMMAND_*
+    stderr_tail: Optional[str] = None   # COMMAND_FAILED

terminalpulse-0.1.0/terminalpulse/graph.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+import json, math, time
+from pathlib import Path
+from typing import Optional
+import networkx as nx
+from .events import Event, EventType
+
+STATE_FILE = Path.home() / ".devpulse_state.json"
+LAMBDA = 0.01          # decay rate (per second). ~0.5 weight after ~70s
+PRUNE_BELOW = 0.01     # drop nodes whose weight falls below this
+SEVERITY = {
+    EventType.COMMAND_FAILED: 1.0,
+    EventType.FILE_SAVED: 0.3,
+    EventType.FOCUS_CHANGED: 0.1,
+    EventType.COMMAND_OK: 0.05,
+}
+
+
+class PulseGraph:
+    def __init__(self) -> None:
+        self.g = nx.DiGraph()
+        self._counter = 0
+        self._focus_node: Optional[str] = None
+
+    def _weight(self, ts: float) -> float:
+        return math.exp(-LAMBDA * (time.time() - ts))
+
+    def ingest(self, ev: Event) -> None:
+        nid = f"{ev.type.value}:{self._counter}"
+        self._counter += 1
+        self.g.add_node(nid, event=ev.model_dump(), severity=SEVERITY[ev.type])
+
+        # link errors to current focus
+        if ev.type == EventType.COMMAND_FAILED and self._focus_node:
+            self.g.add_edge(nid, self._focus_node, kind="occurred_while_editing")
+
+        if ev.type == EventType.FOCUS_CHANGED:
+            self._focus_node = nid
+
+        self._prune()
+        self.export()
+
+    def _prune(self) -> None:
+        dead = [n for n, d in self.g.nodes(data=True)
+                if self._weight(d["event"]["ts"]) < PRUNE_BELOW]
+        self.g.remove_nodes_from(dead)
+        if self._focus_node not in self.g:
+            self._focus_node = None
+
+    def hottest(self, k: int = 5) -> list[dict]:
+        scored = []
+        for n, d in self.g.nodes(data=True):
+            heat = self._weight(d["event"]["ts"]) * d["severity"]
+            scored.append((heat, d["event"]))
+        scored.sort(key=lambda x: -x[0])
+        return [{"heat": round(h, 4), **e} for h, e in scored[:k]]
+
+    def export(self) -> None:
+        state = {
+            "generated_at": time.time(),
+            "hottest": self.hottest(5),
+            "node_count": self.g.number_of_nodes(),
+        }
+        tmp = STATE_FILE.with_suffix(".tmp")
+        tmp.write_text(json.dumps(state, indent=2))
+        tmp.replace(STATE_FILE)   # atomic write

terminalpulse-0.1.0/terminalpulse/windows_tracker.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+import time
+import json
+import urllib.request
+import ctypes
+import ctypes.wintypes
+
+PULSE_PORT = 7077
+POLL_INTERVAL = 3
+EDITORS = {"Visual Studio Code", "Cursor", "VSCodium"}
+
+def get_active_window_title() -> str:
+    hwnd = ctypes.windll.user32.GetForegroundWindow()
+    length = ctypes.windll.user32.GetWindowTextLengthW(hwnd)
+    buf = ctypes.create_unicode_buffer(length + 1)
+    ctypes.windll.user32.GetWindowTextW(hwnd, buf, length + 1)
+    return buf.value
+
+IGNORE = {"Visual Studio Code", "Cursor", "Welcome", "New Tab", "Settings", ""}
+
+def extract_file(title: str) -> str | None:
+    for editor in EDITORS:
+        if editor in title:
+            parts = title.split(" - ")
+            if parts:
+                name = parts[0].strip().lstrip("●").strip()
+                if name and name not in IGNORE:
+                    return name
+    return None
+def send_focus(filename: str, port: int = PULSE_PORT):
+    payload = json.dumps({
+        "type": "focus_changed",
+        "path": filename,
+        "cwd": ""
+    }).encode()
+    try:
+        req = urllib.request.Request(
+            f"http://localhost:{port}",
+            data=payload,
+            headers={"Content-Type": "application/json"}
+        )
+        urllib.request.urlopen(req, timeout=2)
+    except Exception:
+        pass
+
+def run():
+    print(f"TerminalPulse Windows tracker running (port {PULSE_PORT})")
+    last = None
+    while True:
+        title = get_active_window_title()
+        f = extract_file(title)
+        if f and f != last:
+            print(f"Focus: {f}")
+            send_focus(f)
+            last = f
+        time.sleep(POLL_INTERVAL)
+
+if __name__ == "__main__":
+    run()