copa-cli 0.2.0__py3-none-any.whl

copa/fzf.py

@@ -0,0 +1,235 @@
+"""fzf integration for Copa."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import sys
+from datetime import datetime
+
+from .db import Database
+from .models import Command
+from .scoring import rank_commands
+
+
+def has_fzf() -> bool:
+    """Check if fzf is installed."""
+    return shutil.which("fzf") is not None
+
+
+# ANSI escape codes
+_DIM = "\033[2m"
+_MAGENTA = "\033[35m"
+_YELLOW = "\033[33m"
+_RESET = "\033[0m"
+
+
+def format_lines(commands: list[Command]) -> list[str]:
+    """Format commands for fzf display with aligned columns.
+
+    Layout: {id} ┃ {command (padded)} ┃ {pin}{group_badge}  {freq} ┃ {search_text}
+    Field 1 (ID) is hidden by fzf --with-nth '2..3'.
+    Field 2 (command) is extracted by cut -d'┃' -f2 in copa.zsh.
+    Field 3 (metadata) is visible but not extracted.
+    Field 4 (description+flags) is hidden but searchable by fzf.
+    """
+    if not commands:
+        return []
+
+    # Compute column widths from the full list
+    max_cmd = min(max(len(c.command) for c in commands), 60)
+    max_grp = max(
+        (len(f"[{c.group_name}]") for c in commands if c.group_name),
+        default=0,
+    )
+
+    lines = []
+    for cmd in commands:
+        # Field 1: hidden ID
+        id_field = f"{cmd.id:>5}"
+
+        # Field 2: command text, padded for column alignment
+        cmd_text = cmd.command
+        if len(cmd_text) > 60:
+            cmd_text = cmd_text[:57] + "..."
+        cmd_field = f" {cmd_text:<{max_cmd}} "
+
+        # Field 3: metadata — pin indicator, group badge, frequency
+        pin = f"{_YELLOW}*{_RESET} " if cmd.is_pinned else "  "
+
+        if cmd.group_name:
+            badge = f"[{cmd.group_name}]"
+            padded_badge = f"{badge:>{max_grp}}"
+            grp = f"{_DIM}{_MAGENTA}{padded_badge}{_RESET}"
+        else:
+            grp = " " * max_grp
+
+        freq_str = f"{cmd.frequency}×"
+        freq = f"{_DIM}{freq_str:>6}{_RESET}"
+
+        meta_field = f" {pin}{grp}  {freq}"
+
+        # Field 4: hidden searchable text (description, usage, purpose, flags)
+        search_text = cmd.description or ""
+        if cmd.flags:
+            search_text += " " + " ".join(f"{k} {v}" for k, v in cmd.flags.items())
+
+        lines.append(f"{id_field} ┃{cmd_field}┃{meta_field}┃ {search_text}")
+
+    return lines
+
+
+def _parse_description(desc: str) -> dict[str, str]:
+    """Parse a structured description string into its components.
+
+    Handles both plain descriptions and structured format:
+      "Description text | Usage: X | Purpose: Y"
+
+    Returns dict with keys: description, usage, purpose.
+    """
+    result = {"description": "", "usage": "", "purpose": ""}
+    if not desc:
+        return result
+
+    # Split on " | " and check for known prefixes
+    parts = [p.strip() for p in desc.split(" | ")]
+    for part in parts:
+        if part.startswith("Usage: "):
+            result["usage"] = part[7:]
+        elif part.startswith("Purpose: "):
+            result["purpose"] = part[9:]
+        elif not result["description"]:
+            result["description"] = part
+
+    return result
+
+
+def format_preview(cmd: Command) -> str:
+    """Format a rich preview for fzf preview pane."""
+    lines = []
+    lines.append(f"Command:     {cmd.command}")
+
+    parsed = _parse_description(cmd.description)
+    lines.append(f"Description: {parsed['description'] or '(none)'}")
+    if parsed["usage"]:
+        lines.append(f"Usage:       {parsed['usage']}")
+    if parsed["purpose"]:
+        lines.append(f"Purpose:     {parsed['purpose']}")
+
+    if cmd.flags:
+        lines.append("")
+        lines.append("Flags:")
+        for flag, desc in cmd.flags.items():
+            lines.append(f"  {flag:20s} {desc}")
+        lines.append("")
+
+    lines.append(f"Score:       {cmd.score:.1f}")
+    lines.append(f"Frequency:   {cmd.frequency}")
+    if cmd.last_used > 0:
+        dt = datetime.fromtimestamp(cmd.last_used)
+        lines.append(f"Last used:   {dt.strftime('%Y-%m-%d %H:%M')}")
+    if cmd.first_added > 0:
+        dt = datetime.fromtimestamp(cmd.first_added)
+        lines.append(f"First added: {dt.strftime('%Y-%m-%d %H:%M')}")
+    lines.append(f"Source:      {cmd.source}")
+    if cmd.group_name:
+        lines.append(f"Group:       {cmd.group_name}")
+    if cmd.shared_set:
+        lines.append(f"Shared set:  {cmd.shared_set}")
+    if cmd.is_pinned:
+        lines.append("Pinned:      yes")
+    if cmd.tags:
+        lines.append(f"Tags:        {', '.join(cmd.tags)}")
+    return "\n".join(lines)
+
+
+def fzf_list(
+    db: Database,
+    mode: str = "all",
+    group: str | None = None,
+    shared_set: str | None = None,
+) -> list[str]:
+    """Generate fzf-compatible output lines.
+
+    Modes: all, frequent, recent, group, set
+    """
+    if mode == "set" and shared_set:
+        commands = db.list_commands(shared_set=shared_set, limit=500)
+    elif mode == "group" and group:
+        commands = db.list_commands(group_name=group, limit=500)
+    elif shared_set:
+        commands = db.list_commands(shared_set=shared_set, limit=500)
+    else:
+        commands = db.get_all_commands()
+
+    ranked = rank_commands(commands)
+
+    if mode == "recent":
+        ranked.sort(key=lambda c: c.last_used, reverse=True)
+    elif mode == "frequent":
+        ranked.sort(key=lambda c: c.frequency, reverse=True)
+
+    return format_lines(ranked)
+
+
+def run_fzf(db: Database, mode: str = "all", group: str | None = None) -> str | None:
+    """Run fzf with Copa commands. Returns selected command text or None."""
+    if not has_fzf():
+        print("Error: fzf is not installed. Install with: brew install fzf", file=sys.stderr)
+        return None
+
+    lines = fzf_list(db, mode=mode, group=group)
+    if not lines:
+        print("No commands found.", file=sys.stderr)
+        return None
+
+    input_text = "\n".join(lines)
+
+    # Find the copa executable for preview
+    copa_bin = shutil.which("copa") or sys.argv[0]
+    preview_cmd = f"{copa_bin} _preview {{1}}"
+
+    try:
+        result = subprocess.run(
+            [
+                "fzf",
+                "--ansi",
+                "--delimiter",
+                "┃",
+                "--with-nth",
+                "2..3",
+                "--preview",
+                preview_cmd,
+                "--preview-window",
+                "right:40%:wrap",
+                "--header",
+                f"Copa [{mode}] — Tab to cycle modes",
+                "--prompt",
+                "copa> ",
+                "--height",
+                "80%",
+                "--layout",
+                "reverse",
+                "--bind",
+                "enter:accept",
+            ],
+            input=input_text,
+            capture_output=True,
+            text=True,
+        )
+    except FileNotFoundError:
+        print("Error: fzf not found", file=sys.stderr)
+        return None
+
+    if result.returncode != 0:
+        return None
+
+    selected = result.stdout.strip()
+    if not selected:
+        return None
+
+    # Extract command text (second field after ┃)
+    parts = selected.split("┃")
+    if len(parts) >= 2:
+        return parts[1].strip()
+    return selected.strip()

copa/history.py

@@ -0,0 +1,132 @@
+"""Zsh history ingestion for Copa."""
+
+from __future__ import annotations
+
+import re
+import time
+from collections import Counter
+from pathlib import Path
+
+from .db import Database
+
+# Default zsh history file
+DEFAULT_HISTORY = Path.home() / ".zsh_history"
+
+# Extended history format: : timestamp:0;command
+EXTENDED_RE = re.compile(r"^:\s*(\d+):\d+;(.+)$")
+
+
+def parse_zsh_history(
+    history_path: Path | None = None,
+) -> list[tuple[str, float]]:
+    """Parse zsh history, returning (command, timestamp) tuples.
+
+    Handles both plain and extended history formats.
+    Multi-line commands (ending with \\) are joined.
+    """
+    if history_path is None:
+        history_path = DEFAULT_HISTORY
+
+    if not history_path.exists():
+        return []
+
+    entries: list[tuple[str, float]] = []
+
+    try:
+        raw = history_path.read_bytes()
+        # Zsh history may use meta-encoding; decode with replacement
+        text = raw.decode("utf-8", errors="replace")
+    except OSError:
+        return []
+
+    lines = text.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+
+        # Extended format
+        m = EXTENDED_RE.match(line)
+        if m:
+            ts = float(m.group(1))
+            cmd = m.group(2)
+            # Handle continuation lines
+            while cmd.endswith("\\") and i + 1 < len(lines):
+                i += 1
+                cmd = cmd[:-1] + "\n" + lines[i]
+            entries.append((cmd.strip(), ts))
+        elif line.strip():
+            # Plain format — no timestamp
+            cmd = line.strip()
+            while cmd.endswith("\\") and i + 1 < len(lines):
+                i += 1
+                cmd = cmd[:-1] + "\n" + lines[i]
+            entries.append((cmd.strip(), 0.0))
+
+        i += 1
+
+    return entries
+
+
+def sync_history(
+    db: Database,
+    history_path: Path | None = None,
+) -> int:
+    """Ingest zsh history into Copa database.
+
+    Returns the number of new commands added.
+    """
+    entries = parse_zsh_history(history_path)
+    if not entries:
+        return 0
+
+    # Count frequencies
+    freq: Counter[str] = Counter()
+    latest_ts: dict[str, float] = {}
+    for cmd, ts in entries:
+        freq[cmd] += 1
+        if ts > latest_ts.get(cmd, 0):
+            latest_ts[cmd] = ts
+
+    added = 0
+    now = time.time()
+    cur = db.conn.cursor()
+
+    for cmd, count in freq.items():
+        # Skip trivially short or empty commands
+        if len(cmd) < 2:
+            continue
+
+        ts = latest_ts.get(cmd, now)
+        existing = cur.execute(
+            "SELECT id, frequency FROM commands WHERE command = ? AND group_name IS NULL",
+            (cmd,),
+        ).fetchone()
+
+        if existing:
+            # Update frequency and last_used if history is newer
+            cur.execute(
+                """UPDATE commands
+                   SET frequency = MAX(frequency, ?),
+                       last_used = MAX(last_used, ?)
+                   WHERE id = ?""",
+                (count, ts, existing["id"]),
+            )
+        else:
+            cur.execute(
+                """INSERT INTO commands
+                   (command, frequency, last_used, first_added, source)
+                   VALUES (?, ?, ?, ?, 'history')""",
+                (cmd, count, ts, ts),
+            )
+            added += 1
+
+    db.conn.commit()
+    return added
+
+
+def get_history_frequencies(
+    history_path: Path | None = None,
+) -> Counter[str]:
+    """Get command frequencies from zsh history."""
+    entries = parse_zsh_history(history_path)
+    return Counter(cmd for cmd, _ in entries)

copa/llm.py

@@ -0,0 +1,128 @@
+"""LLM backend abstraction for Copa description generation."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+PROMPT_TEMPLATE = (
+    "Given this shell command, write a short description (under 15 words) "
+    "of what it does. Output only the description.\n\n"
+    "Command: {command}"
+)
+
+
+def generate_description(command: str, backend: str = "claude", model: str | None = None) -> str | None:
+    """Generate a description for a command using the configured LLM backend.
+
+    Returns the generated description, or None on failure.
+    """
+    prompt = PROMPT_TEMPLATE.format(command=command)
+
+    if backend == "claude":
+        return _generate_claude(prompt)
+    elif backend == "ollama":
+        return _generate_ollama(prompt, model or "llama3.2:3b")
+    else:
+        return None
+
+
+def _generate_claude(prompt: str) -> str | None:
+    """Generate using the claude CLI."""
+    if not shutil.which("claude"):
+        return None
+
+    try:
+        result = subprocess.run(
+            ["claude", "-p", prompt],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return _clean_response(result.stdout.strip())
+    except (subprocess.TimeoutExpired, OSError):
+        pass
+
+    return None
+
+
+def _generate_ollama(prompt: str, model: str) -> str | None:
+    """Generate using ollama HTTP API."""
+    try:
+        import requests
+    except ImportError:
+        return None
+
+    try:
+        resp = requests.post(
+            "http://localhost:11434/api/generate",
+            json={"model": model, "prompt": prompt, "stream": False},
+            timeout=30,
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            response_text = data.get("response", "").strip()
+            if response_text:
+                return _clean_response(response_text)
+    except Exception:
+        pass
+
+    return None
+
+
+def _clean_response(text: str) -> str:
+    """Clean up an LLM response — strip quotes, trailing punctuation, etc."""
+    text = text.strip().strip('"').strip("'")
+    # Remove leading "Description: " if the model echoed the prompt format
+    for prefix in ("Description:", "description:"):
+        if text.lower().startswith(prefix.lower()):
+            text = text[len(prefix) :].strip()
+    # Truncate to first line only
+    text = text.split("\n")[0].strip()
+    return text
+
+
+def check_ollama_available() -> tuple[bool, str]:
+    """Check if ollama is installed and running.
+
+    Returns (is_ready, message).
+    """
+    if not shutil.which("ollama"):
+        return False, "ollama is not installed. Install from https://ollama.com"
+
+    try:
+        import requests
+    except ImportError:
+        return False, "requests package not installed. Run: pip install copa[ollama]"
+
+    try:
+        resp = requests.get("http://localhost:11434/api/tags", timeout=5)
+        if resp.status_code == 200:
+            return True, "ollama is running"
+    except Exception:
+        pass
+
+    return False, "ollama is not running. Start with: ollama serve"
+
+
+def check_ollama_model(model: str) -> tuple[bool, list[str]]:
+    """Check if a specific model is available in ollama.
+
+    Returns (model_available, list_of_available_models).
+    """
+    try:
+        import requests
+    except ImportError:
+        return False, []
+
+    try:
+        resp = requests.get("http://localhost:11434/api/tags", timeout=5)
+        if resp.status_code == 200:
+            data = resp.json()
+            models = [m["name"] for m in data.get("models", [])]
+            return model in models, models
+    except Exception:
+        pass
+
+    return False, []

copa/mcp_server.py

@@ -0,0 +1,159 @@
+"""FastMCP server for Copa — exposes commands to Claude Code."""
+
+from __future__ import annotations
+
+from .db import Database
+from .scoring import rank_commands
+
+
+def create_mcp_server():
+    """Create and configure the FastMCP server."""
+    from mcp.server.fastmcp import FastMCP
+
+    mcp = FastMCP("Copa")
+    db = Database()
+    db.init_db()
+
+    @mcp.tool()
+    def copa_search(query: str, group: str | None = None, limit: int = 20) -> str:
+        """Search Copa commands by keyword. Returns matching commands with descriptions."""
+        commands = db.search_commands(query, group_name=group, limit=limit)
+        ranked = rank_commands(commands)
+        if not ranked:
+            return f"No commands found matching '{query}'."
+        lines = []
+        for cmd in ranked:
+            parts = [f"[{cmd.id}] {cmd.command}"]
+            if cmd.description:
+                parts.append(f"  → {cmd.description}")
+            if cmd.group_name:
+                parts.append(f"  group: {cmd.group_name}")
+            if cmd.tags:
+                parts.append(f"  tags: {', '.join(cmd.tags)}")
+            lines.append("\n".join(parts))
+        return "\n\n".join(lines)
+
+    @mcp.tool()
+    def copa_list_commands(group: str | None = None, limit: int = 20) -> str:
+        """List Copa commands ranked by usage score. Optionally filter by group."""
+        if group:
+            commands = db.list_commands(group_name=group, limit=limit)
+        else:
+            commands = db.list_commands(limit=limit)
+        ranked = rank_commands(commands)
+        if not ranked:
+            return "No commands found."
+        lines = []
+        for cmd in ranked:
+            badge = ""
+            if cmd.shared_set:
+                badge = " [shared]"
+            elif cmd.group_name:
+                badge = f" [{cmd.group_name}]"
+            desc = f" — {cmd.description}" if cmd.description else ""
+            lines.append(f"[{cmd.id}] {cmd.command}{desc}{badge} ({cmd.frequency}×)")
+        return "\n".join(lines)
+
+    @mcp.tool()
+    def copa_list_groups() -> str:
+        """List all Copa command groups."""
+        groups = db.get_groups()
+        if not groups:
+            return "No groups found."
+        return "\n".join(f"- {g}" for g in groups)
+
+    @mcp.tool()
+    def copa_get_stats() -> str:
+        """Get Copa usage statistics."""
+        stats = db.get_stats()
+        lines = [
+            f"Total commands: {stats['total_commands']}",
+            f"Total uses: {stats['total_uses']}",
+            f"Groups: {stats['total_groups']}",
+            f"Shared sets: {stats['shared_sets']}",
+            f"Pinned: {stats['pinned']}",
+            f"Need description: {stats['needs_description']}",
+        ]
+        if stats.get("by_source"):
+            lines.append("By source:")
+            for source, count in stats["by_source"].items():
+                lines.append(f"  {source}: {count}")
+        return "\n".join(lines)
+
+    @mcp.tool()
+    def copa_add_command(
+        command: str,
+        description: str = "",
+        group: str | None = None,
+        tags: list[str] | None = None,
+    ) -> str:
+        """Add a command to Copa with optional description, group, and tags."""
+        cmd_id = db.add_command(
+            command=command,
+            description=description,
+            group_name=group,
+            tags=tags,
+        )
+        return f"Added command [{cmd_id}]: {command}"
+
+    @mcp.tool()
+    def copa_update_description(command_id: int, description: str) -> str:
+        """Update the description of a Copa command."""
+        cmd = db.get_command(command_id)
+        if not cmd:
+            return f"Command {command_id} not found."
+        db.update_description(command_id, description)
+        return f"Updated [{command_id}] {cmd.command}: {description}"
+
+    @mcp.tool()
+    def copa_create_group(name: str, commands: list[dict] | None = None) -> str:
+        """Create a Copa group and optionally add commands to it.
+
+        Each command in the list should have 'command' and optionally 'description' and 'tags'.
+        """
+        count = 0
+        if commands:
+            for cmd_data in commands:
+                cmd_text = cmd_data.get("command", "").strip()
+                if not cmd_text:
+                    continue
+                db.add_command(
+                    command=cmd_text,
+                    description=cmd_data.get("description", ""),
+                    group_name=name,
+                    tags=cmd_data.get("tags"),
+                )
+                count += 1
+        return f"Group '{name}' created with {count} commands."
+
+    @mcp.tool()
+    def copa_bulk_add(commands: list[dict], group: str | None = None) -> str:
+        """Bulk add commands to Copa.
+
+        Each item should have 'command' and optionally 'description' and 'tags'.
+        """
+        count = 0
+        for cmd_data in commands:
+            cmd_text = cmd_data.get("command", "").strip()
+            if not cmd_text:
+                continue
+            db.add_command(
+                command=cmd_text,
+                description=cmd_data.get("description", ""),
+                group_name=group,
+                tags=cmd_data.get("tags"),
+            )
+            count += 1
+        return f"Added {count} commands."
+
+    return mcp
+
+
+def main():
+    """Run the MCP server."""
+    mcp = create_mcp_server()
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()