one-ctx 0.1.0__py3-none-any.whl

ctx/__init__.py

@@ -0,0 +1 @@
+"""ctx — Combined Context MCP Server."""

ctx/cli.py

@@ -0,0 +1,159 @@
+import sys
+if sys.platform == 'win32':
+    import asyncio
+    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
+import sys
+import anyio
+import click
+from ctx.database import (
+    init_project, get_project, reset_project, list_projects,
+    search_projects, search_logs,
+)
+from ctx.server import mcp_server
+from ctx.git import get_git_summary
+import mcp.server.stdio
+
+@click.group()
+def cli():
+    """ctx -- Combined Context MCP Server."""
+    pass
+
+@cli.command()
+@click.option("--port", default=7337, help="Port to run the server on")
+@click.option("--host", default="0.0.0.0", help="Host to bind to")
+def serve(port, host):
+    """Start the HTTP/SSE server."""
+    import uvicorn
+    print(f"[ctx] server starting on http://{host}:{port}")
+    print(f"   SSE endpoint:     http://localhost:{port}/sse")
+    print(f"   Messages endpoint: http://localhost:{port}/messages/")
+    print(f"   Health check:      http://localhost:{port}/health\n")
+    print("Add to your MCP config:")
+    print(f'   {{"mcpServers": {{"ctx": {{"url": "http://localhost:{port}/sse"}}}}}}\n')
+    
+    uvicorn.run("ctx.server:app", host=host, port=port, log_level="info")
+
+@cli.command()
+def stdio():
+    """Start the stdio server (for direct VS Code / Cline / Codex integration)."""
+    async def run():
+        async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+            await mcp_server.run(
+                read_stream,
+                write_stream,
+                mcp_server.create_initialization_options()
+            )
+    anyio.run(run)
+
+@cli.command()
+@click.argument("project")
+@click.option("--path", default="", help="Path to the project's git repo on disk")
+def init(project, path):
+    """Initialize a new project context."""
+    result = init_project(project, repo_path=path)
+    if "error" in result:
+        print(f"[!] {result['error']}")
+        return
+    print(f"[OK] Project '{project}' initialized.")
+    if path:
+        print(f"   Git repo linked: {path}")
+    print("   Start any AI tool and call ctx_get to load context.")
+
+@cli.command()
+@click.argument("project", required=False)
+def status(project):
+    """View the context for a project, or list all projects."""
+    if not project:
+        projects = list_projects()
+        if not projects:
+            print("No projects found.")
+            return
+        print("=== Tracked Projects ===")
+        for p in projects:
+            print(f"- {p['project']} (last updated: {p['updated_at']})")
+        return
+
+    data = get_project(project)
+    if "error" in data:
+        print(f"Error: {data['error']}")
+        return
+
+    print(f"=== {project} ===")
+    print(f"\n[WHAT]\n{data.get('what', '(empty)') or '(empty)'}")
+    print(f"\n[DONE]\n{data.get('done', '(empty)') or '(empty)'}")
+    print(f"\n[NOW]\n{data.get('now', '(empty)') or '(empty)'}")
+    print(f"\n[MAP]\n{data.get('map', '(empty)') or '(no files mapped)'}")
+
+    # Show git info if repo_path is set
+    repo_path = data.get("repo_path", "")
+    if repo_path:
+        print(f"\n[GIT] repo: {repo_path}")
+        git_info = get_git_summary(repo_path)
+        if git_info:
+            print(f"   Branch: {git_info['branch']}")
+            if git_info.get("recent_commits"):
+                print(f"   Recent commits:")
+                for c in git_info["recent_commits"][:3]:
+                    print(f"     {c['hash']} {c['message']}")
+            changed = git_info.get("changed_files", {})
+            total_changes = len(changed.get("staged", [])) + len(changed.get("unstaged", [])) + len(changed.get("untracked", []))
+            if total_changes:
+                print(f"   Changed files: {total_changes}")
+        else:
+            print("   (git not available or not a repo)")
+
+@cli.command()
+@click.argument("project")
+def reset(project):
+    """Reset a project's context back to empty."""
+    reset_project(project)
+    print(f"[OK] Project '{project}' has been reset to empty.")
+
+@cli.command(name="list")
+def list_cmd():
+    """List all tracked projects."""
+    projects = list_projects()
+    if not projects:
+        print("No projects found.")
+        return
+    print("=== Tracked Projects ===")
+    for p in projects:
+        print(f"- {p['project']} (last updated: {p['updated_at']})")
+
+@cli.command()
+@click.argument("project")
+def delete(project):
+    """Permanently delete a project."""
+    from ctx.database import delete_project
+    result = delete_project(project)
+    if "error" in result:
+        print(f"[!] {result['error']}")
+    else:
+        print(f"[OK] Project '{project}' deleted.")
+
+@cli.command()
+@click.argument("query")
+def search(query):
+    """Search across all projects' context and history."""
+    project_matches = search_projects(query)
+    log_matches = search_logs(query)
+
+    if not project_matches and not log_matches:
+        print(f"No results found for '{query}'.")
+        return
+
+    if project_matches:
+        print(f"=== Projects matching '{query}' ===")
+        for m in project_matches:
+            buckets = ", ".join(m["matched_buckets"])
+            print(f"- {m['project']} (found in: {buckets})")
+
+    if log_matches:
+        print(f"\n=== History matching '{query}' ===")
+        for m in log_matches:
+            print(f"- [{m['project']}] [{m['tool_name']} @ {m['timestamp'][:16]}] {m['summary'][:100]}")
+
+    print(f"\nTotal: {len(project_matches)} projects, {len(log_matches)} history entries")
+
+if __name__ == "__main__":
+    cli()

ctx/database.py

@@ -0,0 +1,292 @@
+"""SQLite storage layer for ctx.
+
+Stores project context in four buckets: WHAT, DONE, NOW, MAP.
+Everything is local — one .db file per installation.
+"""
+
+import sqlite3
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+
+# Default DB location: ~/.ctx/ctx.db
+DEFAULT_DB_DIR = Path.home() / ".ctx"
+DEFAULT_DB_PATH = DEFAULT_DB_DIR / "ctx.db"
+
+
+def _get_db_path() -> Path:
+    """Get the database path, respecting CTX_DB_PATH env var."""
+    custom = os.environ.get("CTX_DB_PATH")
+    if custom:
+        return Path(custom)
+    return DEFAULT_DB_PATH
+
+
+def get_connection() -> sqlite3.Connection:
+    """Get a SQLite connection, creating the DB and tables if needed."""
+    db_path = _get_db_path()
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+
+    conn = sqlite3.connect(str(db_path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS projects (
+            name        TEXT PRIMARY KEY,
+            what        TEXT NOT NULL DEFAULT '',
+            done        TEXT NOT NULL DEFAULT '',
+            now         TEXT NOT NULL DEFAULT '',
+            map         TEXT NOT NULL DEFAULT '',
+            repo_path   TEXT NOT NULL DEFAULT '',
+            created_at  TEXT NOT NULL,
+            updated_at  TEXT NOT NULL
+        )
+    """)
+
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS update_log (
+            id          INTEGER PRIMARY KEY AUTOINCREMENT,
+            project     TEXT NOT NULL,
+            tool_name   TEXT NOT NULL DEFAULT 'unknown',
+            summary     TEXT NOT NULL,
+            timestamp   TEXT NOT NULL,
+            FOREIGN KEY (project) REFERENCES projects(name) ON DELETE CASCADE
+        )
+    """)
+
+    # --- Migration: add columns for existing databases ---
+    try:
+        conn.execute("SELECT map FROM projects LIMIT 1")
+    except sqlite3.OperationalError:
+        conn.execute("ALTER TABLE projects ADD COLUMN map TEXT NOT NULL DEFAULT ''")
+
+    try:
+        conn.execute("SELECT repo_path FROM projects LIMIT 1")
+    except sqlite3.OperationalError:
+        conn.execute("ALTER TABLE projects ADD COLUMN repo_path TEXT NOT NULL DEFAULT ''")
+
+    conn.commit()
+    return conn
+
+
+def init_project(name: str, repo_path: str = "") -> dict:
+    """Create a new project entry. Returns the project dict."""
+    conn = get_connection()
+    now = datetime.now(timezone.utc).isoformat()
+    try:
+        conn.execute(
+            "INSERT INTO projects (name, repo_path, created_at, updated_at) VALUES (?, ?, ?, ?)",
+            (name, repo_path, now, now),
+        )
+        conn.commit()
+    except sqlite3.IntegrityError:
+        # If project exists and repo_path is being set, update it
+        if repo_path:
+            conn.execute(
+                "UPDATE projects SET repo_path = ?, updated_at = ? WHERE name = ?",
+                (repo_path, now, name),
+            )
+            conn.commit()
+        else:
+            conn.close()
+            return {"error": f"Project '{name}' already exists."}
+    result = get_project(name, conn)
+    conn.close()
+    return result
+
+
+def get_project(name: str, conn: Optional[sqlite3.Connection] = None) -> dict:
+    """Get the full context snapshot for a project."""
+    should_close = conn is None
+    if conn is None:
+        conn = get_connection()
+
+    row = conn.execute(
+        "SELECT * FROM projects WHERE name = ?", (name,)
+    ).fetchone()
+
+    if should_close:
+        conn.close()
+
+    if row is None:
+        return {"error": f"Project '{name}' not found."}
+
+    return {
+        "project": row["name"],
+        "what": row["what"],
+        "done": row["done"],
+        "now": row["now"],
+        "map": row["map"],
+        "repo_path": row["repo_path"],
+        "created_at": row["created_at"],
+        "updated_at": row["updated_at"],
+    }
+
+
+def update_project(
+    name: str, what: str, done: str, now: str, map_: str,
+    tool_name: str, summary: str, repo_path: Optional[str] = None,
+) -> dict:
+    """Update a project's context buckets after merge."""
+    conn = get_connection()
+    ts = datetime.now(timezone.utc).isoformat()
+
+    if repo_path is not None:
+        cursor = conn.execute(
+            """UPDATE projects
+               SET what = ?, done = ?, now = ?, map = ?, repo_path = ?, updated_at = ?
+               WHERE name = ?""",
+            (what, done, now, map_, repo_path, ts, name),
+        )
+    else:
+        cursor = conn.execute(
+            """UPDATE projects
+               SET what = ?, done = ?, now = ?, map = ?, updated_at = ?
+               WHERE name = ?""",
+            (what, done, now, map_, ts, name),
+        )
+
+    if cursor.rowcount == 0:
+        conn.close()
+        return {"error": f"Project '{name}' not found. Run `ctx init {name}` first."}
+
+    # Log the raw update for audit
+    conn.execute(
+        "INSERT INTO update_log (project, tool_name, summary, timestamp) VALUES (?, ?, ?, ?)",
+        (name, tool_name, summary, ts),
+    )
+
+    conn.commit()
+    result = get_project(name, conn)
+    conn.close()
+    return result
+
+
+def update_project_map(name: str, map_content: str) -> dict:
+    """Update only the MAP bucket for a project (for ctx_map tool)."""
+    conn = get_connection()
+    ts = datetime.now(timezone.utc).isoformat()
+
+    cursor = conn.execute(
+        "UPDATE projects SET map = ?, updated_at = ? WHERE name = ?",
+        (map_content, ts, name),
+    )
+
+    if cursor.rowcount == 0:
+        conn.close()
+        return {"error": f"Project '{name}' not found."}
+
+    conn.commit()
+    result = get_project(name, conn)
+    conn.close()
+    return result
+
+
+def reset_project(name: str) -> dict:
+    """Wipe a project's context back to empty."""
+    conn = get_connection()
+    ts = datetime.now(timezone.utc).isoformat()
+
+    cursor = conn.execute(
+        "UPDATE projects SET what = '', done = '', now = '', map = '', updated_at = ? WHERE name = ?",
+        (ts, name),
+    )
+
+    if cursor.rowcount == 0:
+        conn.close()
+        return {"error": f"Project '{name}' not found."}
+
+    # Also clear the log
+    conn.execute("DELETE FROM update_log WHERE project = ?", (name,))
+    conn.commit()
+    conn.close()
+    return {"status": "reset", "project": name}
+
+
+def list_projects() -> list[dict]:
+    """List all known projects with basic info."""
+    conn = get_connection()
+    rows = conn.execute(
+        "SELECT name, updated_at FROM projects ORDER BY updated_at DESC"
+    ).fetchall()
+    conn.close()
+    return [{"project": r["name"], "updated_at": r["updated_at"]} for r in rows]
+
+
+def delete_project(name: str) -> dict:
+    """Permanently delete a project and its logs."""
+    conn = get_connection()
+    cursor = conn.execute("DELETE FROM projects WHERE name = ?", (name,))
+    if cursor.rowcount == 0:
+        conn.close()
+        return {"error": f"Project '{name}' not found."}
+    conn.commit()
+    conn.close()
+    return {"status": "deleted", "project": name}
+
+
+# ---------------------------------------------------------------------------
+# Cross-project search
+# ---------------------------------------------------------------------------
+
+def search_projects(query: str) -> list[dict]:
+    """Search across all projects' context buckets (what/done/now/map)."""
+    conn = get_connection()
+    pattern = f"%{query}%"
+    rows = conn.execute(
+        """SELECT name, what, done, now, map, updated_at FROM projects
+           WHERE what LIKE ? OR done LIKE ? OR now LIKE ? OR map LIKE ?
+           ORDER BY updated_at DESC""",
+        (pattern, pattern, pattern, pattern),
+    ).fetchall()
+    conn.close()
+
+    results = []
+    for r in rows:
+        # Build a list of which buckets matched
+        matches = []
+        q_lower = query.lower()
+        if q_lower in r["what"].lower():
+            matches.append("what")
+        if q_lower in r["done"].lower():
+            matches.append("done")
+        if q_lower in r["now"].lower():
+            matches.append("now")
+        if q_lower in r["map"].lower():
+            matches.append("map")
+
+        results.append({
+            "project": r["name"],
+            "matched_buckets": matches,
+            "updated_at": r["updated_at"],
+        })
+
+    return results
+
+
+def search_logs(query: str) -> list[dict]:
+    """Search across all projects' update history."""
+    conn = get_connection()
+    pattern = f"%{query}%"
+    rows = conn.execute(
+        """SELECT project, tool_name, summary, timestamp FROM update_log
+           WHERE summary LIKE ?
+           ORDER BY timestamp DESC
+           LIMIT 20""",
+        (pattern,),
+    ).fetchall()
+    conn.close()
+
+    return [
+        {
+            "project": r["project"],
+            "tool_name": r["tool_name"],
+            "summary": r["summary"],
+            "timestamp": r["timestamp"],
+        }
+        for r in rows
+    ]

ctx/git.py

@@ -0,0 +1,106 @@
+"""Git integration for ctx — Combined Context.
+
+Detects branch, recent commits, and changed files for a project's repo.
+All functions return None gracefully if git is unavailable or the path
+is not a git repository. Zero dependencies — uses subprocess only.
+"""
+
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+
+def _run_git(repo_path: str, *args: str, timeout: int = 5) -> Optional[str]:
+    """Run a git command in the given repo, return stdout or None on failure."""
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+        return None
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return None
+
+
+def is_git_repo(repo_path: str) -> bool:
+    """Check if the given path is inside a git repository."""
+    return _run_git(repo_path, "rev-parse", "--git-dir") is not None
+
+
+def get_branch(repo_path: str) -> Optional[str]:
+    """Get the current branch name (e.g. 'main', 'feature-auth')."""
+    return _run_git(repo_path, "rev-parse", "--abbrev-ref", "HEAD")
+
+
+def get_recent_commits(repo_path: str, n: int = 5) -> Optional[list[dict]]:
+    """Get the last N commit messages with hash and author.
+
+    Returns a list of dicts: [{"hash": "abc123", "author": "name", "message": "..."}]
+    """
+    output = _run_git(
+        repo_path, "log", f"-{n}",
+        "--format=%h|%an|%s",
+        "--no-merges",
+    )
+    if output is None:
+        return None
+
+    commits = []
+    for line in output.splitlines():
+        parts = line.split("|", 2)
+        if len(parts) == 3:
+            commits.append({
+                "hash": parts[0],
+                "author": parts[1],
+                "message": parts[2],
+            })
+    return commits
+
+
+def get_changed_files(repo_path: str) -> Optional[dict]:
+    """Get uncommitted changes (staged + unstaged + untracked).
+
+    Returns: {"staged": [...], "unstaged": [...], "untracked": [...]}
+    """
+    staged = _run_git(repo_path, "diff", "--cached", "--name-only")
+    unstaged = _run_git(repo_path, "diff", "--name-only")
+    untracked = _run_git(repo_path, "ls-files", "--others", "--exclude-standard")
+
+    if staged is None and unstaged is None and untracked is None:
+        return None
+
+    return {
+        "staged": [f for f in (staged or "").splitlines() if f],
+        "unstaged": [f for f in (unstaged or "").splitlines() if f],
+        "untracked": [f for f in (untracked or "").splitlines() if f],
+    }
+
+
+def get_git_summary(repo_path: str) -> Optional[dict]:
+    """Get a complete git status summary for a repo.
+
+    Returns None if the path is not a git repo.
+    Otherwise returns: {
+        "branch": "main",
+        "recent_commits": [...],
+        "changed_files": {...},
+    }
+    """
+    if not repo_path or not Path(repo_path).exists():
+        return None
+
+    if not is_git_repo(repo_path):
+        return None
+
+    return {
+        "branch": get_branch(repo_path) or "unknown",
+        "recent_commits": get_recent_commits(repo_path, n=5) or [],
+        "changed_files": get_changed_files(repo_path) or {
+            "staged": [], "unstaged": [], "untracked": []
+        },
+    }