copa-cli 0.2.0__py3-none-any.whl

copa/__init__.py

@@ -0,0 +1,3 @@
+"""Copa — Command Palette."""
+
+__version__ = "0.2.0"

copa/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as python -m copa."""
+
+from copa.cli import cli
+
+cli()

copa/cli.py

@@ -0,0 +1,216 @@
+"""Click CLI for Copa — Command Palette."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from .cli_common import complete_group, complete_shared_set, complete_source, get_db
+from .scoring import rank_commands
+
+# --- Main group ---
+
+
+@click.group()
+@click.version_option(package_name="copa-cli")
+def cli():
+    """Copa — Command Palette. Smart command tracking, ranking, and sharing."""
+    pass
+
+
+# --- add ---
+
+
+@cli.command()
+@click.argument("command")
+@click.option("-d", "--description", default="", help="Description of the command.")
+@click.option("-g", "--group", default=None, help="Group name.", shell_complete=complete_group)
+@click.option("-t", "--tag", multiple=True, help="Tags (can be repeated).")
+@click.option("-p", "--pin", is_flag=True, help="Pin this command.")
+@click.option("-f", "--flag", multiple=True, help="Flag docs as 'flag: description' (repeatable).")
+def add(command: str, description: str, group: str | None, tag: tuple[str, ...], pin: bool, flag: tuple[str, ...]):
+    """Save a command with optional description and group."""
+    db = get_db()
+
+    # Parse --flag options into a dict
+    flags: dict[str, str] = {}
+    for f in flag:
+        parts = f.split(":", 1)
+        flag_name = parts[0].strip()
+        flag_desc = parts[1].strip() if len(parts) > 1 else ""
+        flags[flag_name] = flag_desc
+
+    cmd_id = db.add_command(
+        command=command,
+        description=description,
+        group_name=group,
+        tags=list(tag) if tag else None,
+        flags=flags if flags else None,
+    )
+    if pin:
+        db.pin_command(cmd_id, True)
+    click.echo(f"Added [{cmd_id}]: {command}")
+    if description:
+        click.echo(f"  → {description}")
+    if flags:
+        click.echo(f"  flags: {len(flags)} documented")
+    if group:
+        click.echo(f"  group: {group}")
+
+
+# --- list ---
+
+
+@cli.command("list")
+@click.option("-g", "--group", default=None, help="Filter by group.", shell_complete=complete_group)
+@click.option("-n", "--limit", default=20, help="Number of commands to show.")
+@click.option("-s", "--source", default=None, help="Filter by source.", shell_complete=complete_source)
+@click.option("--set", "shared_set", default=None, help="Filter by shared set.", shell_complete=complete_shared_set)
+@click.option("--needs-desc", is_flag=True, help="Show only commands needing description.")
+def list_cmd(group: str | None, limit: int, source: str | None, shared_set: str | None, needs_desc: bool):
+    """List commands ranked by score."""
+    db = get_db()
+    commands = db.list_commands(
+        group_name=group,
+        limit=limit,
+        source=source,
+        needs_description=True if needs_desc else None,
+        shared_set=shared_set,
+    )
+    ranked = rank_commands(commands)
+    if not ranked:
+        click.echo("No commands found.")
+        return
+
+    for cmd in ranked:
+        badge = ""
+        if cmd.shared_set:
+            badge = click.style(f" [shared:{cmd.shared_set}]", fg="cyan")
+        elif cmd.group_name:
+            badge = click.style(f" [{cmd.group_name}]", fg="magenta")
+        if cmd.is_pinned:
+            badge += click.style(" [pinned]", fg="yellow")
+
+        desc = ""
+        if cmd.description:
+            desc = click.style(f" — {cmd.description}", dim=True)
+
+        freq = click.style(f" ({cmd.frequency}×)", dim=True)
+        score_str = click.style(f" s={cmd.score:.1f}", dim=True)
+
+        click.echo(f"  [{cmd.id:>4}] {cmd.command}{desc}{badge}{freq}{score_str}")
+
+
+# --- search ---
+
+
+@cli.command()
+@click.argument("query")
+@click.option("-g", "--group", default=None, help="Filter by group.", shell_complete=complete_group)
+@click.option("-s", "--source", default=None, help="Filter by source.", shell_complete=complete_source)
+@click.option("--set", "shared_set", default=None, help="Filter by shared set.", shell_complete=complete_shared_set)
+@click.option("-n", "--limit", default=20, help="Max results.")
+def search(query: str, group: str | None, source: str | None, shared_set: str | None, limit: int):
+    """Search commands by keyword (FTS)."""
+    db = get_db()
+    commands = db.search_commands(query, group_name=group, source=source, shared_set=shared_set, limit=limit)
+    ranked = rank_commands(commands)
+    if not ranked:
+        click.echo(f"No commands matching '{query}'.")
+        return
+
+    for cmd in ranked:
+        badge = ""
+        if cmd.group_name:
+            badge = click.style(f" [{cmd.group_name}]", fg="magenta")
+        desc = ""
+        if cmd.description:
+            desc = click.style(f" — {cmd.description}", dim=True)
+        click.echo(f"  [{cmd.id:>4}] {cmd.command}{desc}{badge}")
+
+
+# --- remove ---
+
+
+@cli.command()
+@click.argument("cmd_id", type=int)
+def remove(cmd_id: int):
+    """Remove a command by ID."""
+    db = get_db()
+    cmd = db.get_command(cmd_id)
+    if not cmd:
+        click.echo(f"Command {cmd_id} not found.", err=True)
+        sys.exit(1)
+    db.remove_command(cmd_id)
+    click.echo(f"Removed [{cmd_id}]: {cmd.command}")
+
+
+# --- stats ---
+
+
+@cli.command()
+def stats():
+    """Show usage statistics."""
+    db = get_db()
+    s = db.get_stats()
+    click.echo(f"Commands:     {s['total_commands']}")
+    click.echo(f"Total uses:   {s['total_uses']}")
+    click.echo(f"Groups:       {s['total_groups']}")
+    click.echo(f"Shared sets:  {s['shared_sets']}")
+    click.echo(f"Pinned:       {s['pinned']}")
+    click.echo(f"Need desc:    {s['needs_description']}")
+    if s.get("by_source"):
+        click.echo("By source:")
+        for source, count in s["by_source"].items():
+            click.echo(f"  {source}: {count}")
+
+
+# --- sync ---
+
+
+@cli.command()
+@click.option("--history", type=click.Path(exists=True), default=None, help="Path to zsh history file.")
+def sync(history: str | None):
+    """Backfill from ~/.zsh_history."""
+    from .history import sync_history
+
+    db = get_db()
+    history_path = Path(history) if history else None
+    added = sync_history(db, history_path)
+    click.echo(f"Synced: {added} new commands from history.")
+
+
+# --- scan ---
+
+
+@cli.command()
+@click.option(
+    "--dir",
+    "directory",
+    type=click.Path(exists=True),
+    default=None,
+    help="Directory to scan (default: all $PATH directories).",
+)
+def scan(directory: str | None):
+    """Import script metadata from $PATH (supports #@ Description/Usage headers)."""
+    from .scanner import scan_directory
+
+    db = get_db()
+    dir_path = Path(directory) if directory else None
+    added = scan_directory(db, dir_path)
+    click.echo(f"Scanned: {added} scripts added.")
+
+
+# --- Register extracted command modules ---
+
+from . import cli_internal, cli_llm, cli_share
+
+cli_llm.register(cli)
+cli_share.register(cli)
+cli_internal.register(cli)
+
+
+if __name__ == "__main__":
+    cli()

copa/cli_common.py

@@ -0,0 +1,43 @@
+"""Shared utilities for Copa CLI modules."""
+
+from __future__ import annotations
+
+from click.shell_completion import CompletionItem
+
+from .db import Database
+
+
+def get_db() -> Database:
+    db = Database()
+    db.init_db()
+    return db
+
+
+# --- Shell completion helpers ---
+
+
+def complete_group(ctx, param, incomplete):
+    """Complete group names from the database."""
+    try:
+        db = get_db()
+        return [CompletionItem(g) for g in db.get_groups() if g.startswith(incomplete)]
+    except Exception:
+        return []
+
+
+def complete_shared_set(ctx, param, incomplete):
+    """Complete shared set names from the database."""
+    try:
+        db = get_db()
+        return [CompletionItem(s.name) for s in db.get_shared_sets() if s.name.startswith(incomplete)]
+    except Exception:
+        return []
+
+
+def complete_source(ctx, param, incomplete):
+    """Complete source values from the database."""
+    try:
+        db = get_db()
+        return [CompletionItem(s) for s in db.get_sources() if s.startswith(incomplete)]
+    except Exception:
+        return []

copa/cli_internal.py

@@ -0,0 +1,334 @@
+"""Hidden/internal CLI commands for Copa shell integration."""
+
+from __future__ import annotations
+
+import sys
+
+import click
+
+from .cli_common import complete_group, complete_shared_set, get_db
+
+
+def _open_tty():
+    """Open /dev/tty with echo enabled for use inside fzf execute() bindings.
+
+    fzf disables terminal echo before launching execute() subcommands.
+    We re-enable it so users can see what they type.
+
+    Returns (tty_file, original_termios) or (None, None) on failure.
+    """
+    try:
+        tty = open("/dev/tty", "r+")
+    except OSError:
+        return None, None
+
+    old_attrs = None
+    try:
+        import termios
+
+        fd = tty.fileno()
+        old_attrs = termios.tcgetattr(fd)
+        new_attrs = termios.tcgetattr(fd)
+        # Enable echo (ECHO) and canonical mode (ICANON) for line-buffered input
+        new_attrs[3] |= termios.ECHO | termios.ICANON
+        termios.tcsetattr(fd, termios.TCSANOW, new_attrs)
+    except (ImportError, termios.error):
+        pass  # termios not available (non-Unix) — proceed without echo fix
+
+    return tty, old_attrs
+
+
+def _close_tty(tty, old_attrs):
+    """Restore terminal attributes and close the tty file."""
+    if tty is None:
+        return
+    if old_attrs is not None:
+        try:
+            import termios
+
+            termios.tcsetattr(tty.fileno(), termios.TCSANOW, old_attrs)
+        except (ImportError, termios.error):
+            pass
+    tty.close()
+
+
+@click.command("_record", hidden=True)
+@click.argument("command")
+def record(command: str):
+    """Record a command usage (called by precmd hook)."""
+    db = get_db()
+    db.record_usage(command)
+
+
+@click.command("_init", hidden=True)
+def init():
+    """Initialize the Copa database."""
+    get_db()
+    click.echo("Copa database initialized.")
+
+
+@click.command("fzf-list", hidden=True)
+@click.option("--mode", default="all", type=click.Choice(["all", "frequent", "recent", "group", "set"]))
+@click.option("--group", default=None, shell_complete=complete_group)
+@click.option("--set", "shared_set", default=None, help="Filter by shared set.", shell_complete=complete_shared_set)
+def fzf_list_cmd(mode: str, group: str | None, shared_set: str | None):
+    """Output formatted lines for fzf."""
+    from .fzf import fzf_list
+
+    db = get_db()
+    lines = fzf_list(db, mode=mode, group=group, shared_set=shared_set)
+    for line in lines:
+        click.echo(line)
+
+
+@click.command("_preview", hidden=True)
+@click.argument("cmd_id", type=int)
+def preview(cmd_id: int):
+    """Rich preview for fzf preview pane."""
+    from .fzf import format_preview
+
+    db = get_db()
+    cmd = db.get_command(cmd_id)
+    if not cmd:
+        click.echo(f"Command {cmd_id} not found.")
+        return
+    from .scoring import compute_score
+
+    cmd.score = compute_score(cmd)
+    click.echo(format_preview(cmd))
+
+
+@click.command("_set-group", hidden=True)
+@click.argument("cmd_id", type=int)
+def set_group(cmd_id: int):
+    """Assign or change the group for a command (called by fzf execute binding)."""
+    db = get_db()
+    cmd = db.get_command(cmd_id)
+    if not cmd:
+        click.echo(f"Command {cmd_id} not found.", err=True)
+        sys.exit(1)
+
+    tty, old_attrs = _open_tty()
+
+    def tty_write(msg: str):
+        if tty:
+            tty.write(msg + "\n")
+            tty.flush()
+        else:
+            click.echo(msg)
+
+    def tty_read(prompt: str) -> str:
+        if tty:
+            tty.write(prompt)
+            tty.flush()
+            return tty.readline().rstrip("\n")
+        return input(prompt)
+
+    tty_write(f"  Command: {cmd.command}")
+    current = cmd.group_name or "(none)"
+    tty_write(f"  Current group: {current}")
+
+    groups = db.get_groups()
+    if groups:
+        tty_write(f"  Existing groups: {', '.join(groups)}")
+
+    try:
+        name = tty_read("  Group name (empty=clear, q=cancel): ").strip()
+    except (EOFError, KeyboardInterrupt):
+        _close_tty(tty, old_attrs)
+        return
+
+    if name.lower() == "q":
+        _close_tty(tty, old_attrs)
+        return
+
+    group_name = name if name else None
+    ok = db.update_group(cmd.id, group_name)
+    if ok:
+        label = group_name or "(none)"
+        tty_write(click.style(f"  → group set to: {label}", fg="green"))
+    else:
+        tty_write(click.style(f"  ✗ command already exists in group '{group_name}'", fg="red"))
+
+    _close_tty(tty, old_attrs)
+
+
+@click.command("_set-flags", hidden=True)
+@click.argument("cmd_id", type=int)
+def set_flags(cmd_id: int):
+    """Add or edit flags for a command (called by fzf execute binding)."""
+    db = get_db()
+    cmd = db.get_command(cmd_id)
+    if not cmd:
+        click.echo(f"Command {cmd_id} not found.", err=True)
+        sys.exit(1)
+
+    tty, old_attrs = _open_tty()
+
+    def tty_write(msg: str):
+        if tty:
+            tty.write(msg + "\n")
+            tty.flush()
+        else:
+            click.echo(msg)
+
+    def tty_read(prompt: str) -> str:
+        if tty:
+            tty.write(prompt)
+            tty.flush()
+            return tty.readline().rstrip("\n")
+        return input(prompt)
+
+    tty_write(f"  Command: {cmd.command}")
+
+    flags = dict(cmd.flags)  # copy existing flags
+
+    if flags:
+        tty_write("  Current flags:")
+        for flag, desc in flags.items():
+            tty_write(f"    {flag}: {desc}")
+    else:
+        tty_write("  No flags yet.")
+
+    tty_write("  Add flags (empty flag name = done, q = cancel):")
+
+    try:
+        while True:
+            flag_name = tty_read("  Flag name: ").strip()
+            if not flag_name:
+                break
+            if flag_name.lower() == "q":
+                _close_tty(tty, old_attrs)
+                return
+            flag_desc = tty_read("  Description: ").strip()
+            flags[flag_name] = flag_desc
+            tty_write(click.style(f"    + {flag_name}: {flag_desc}", fg="green"))
+    except (EOFError, KeyboardInterrupt):
+        _close_tty(tty, old_attrs)
+        return
+
+    if flags != cmd.flags:
+        db.update_flags(cmd.id, flags)
+        tty_write(click.style(f"  → {len(flags)} flag(s) saved", fg="green"))
+    else:
+        tty_write("  No changes.")
+
+    _close_tty(tty, old_attrs)
+
+
+@click.command("_list-groups", hidden=True)
+def list_groups():
+    """Output group names for fzf group picker."""
+    db = get_db()
+    click.echo("(all)")
+    for g in db.get_groups():
+        click.echo(g)
+
+
+@click.command("_next-group", hidden=True)
+@click.argument("current", default="(all)")
+def next_group(current: str):
+    """Output the next group in the cycle: (all) → g1 → g2 → ... → (all)."""
+    db = get_db()
+    groups = ["(all)"] + db.get_groups()
+    try:
+        idx = groups.index(current)
+    except ValueError:
+        idx = -1
+    next_idx = (idx + 1) % len(groups)
+    click.echo(groups[next_idx])
+
+
+@click.command("_complete-word", hidden=True)
+@click.argument("words", nargs=-1)
+def complete_word(words):
+    """Return tab-completion candidates for a partial command line."""
+    if not words:
+        return
+
+    db = get_db()
+
+    # All words except the last form the prefix; the last word is the incomplete token
+    if len(words) == 1:
+        # Single word: return unique first words from all commands matching the token
+        token = words[0]
+        cur = db.conn.cursor()
+        cur.execute("SELECT command, frequency FROM commands ORDER BY frequency DESC")
+        seen: set[str] = set()
+        for row in cur.fetchall():
+            first_word = row["command"].split()[0] if row["command"].split() else ""
+            if first_word and first_word.startswith(token) and first_word not in seen:
+                seen.add(first_word)
+                click.echo(first_word)
+        return
+
+    prefix_words = list(words[:-1])
+    token = words[-1]
+
+    # Build a LIKE pattern from the prefix words
+    # Escape SQL LIKE wildcards in prefix
+    prefix = " ".join(prefix_words)
+    escaped_prefix = prefix.replace("%", "\\%").replace("_", "\\_")
+    like_pattern = escaped_prefix + " %"
+
+    cur = db.conn.cursor()
+    cur.execute(
+        "SELECT command, frequency FROM commands WHERE command LIKE ? ESCAPE '\\' ORDER BY frequency DESC",
+        (like_pattern,),
+    )
+
+    word_pos = len(prefix_words)
+    seen: set[str] = set()
+    for row in cur.fetchall():
+        parts = row["command"].split()
+        if len(parts) > word_pos:
+            candidate = parts[word_pos]
+            if candidate.startswith(token) and candidate not in seen:
+                seen.add(candidate)
+                click.echo(candidate)
+
+
+@click.command("mcp", hidden=True)
+def mcp_cmd():
+    """Run the MCP server (stdio transport)."""
+    from .mcp_server import main
+
+    main()
+
+
+@click.command(hidden=True)
+@click.argument("shell", type=click.Choice(["zsh", "bash", "fish"]))
+def completion(shell: str):
+    """Output shell completion script."""
+    import os
+    import subprocess
+
+    env = os.environ.copy()
+    env["_COPA_COMPLETE"] = f"{shell}_source"
+    result = subprocess.run(["copa"], env=env, capture_output=True, text=True)
+    click.echo(result.stdout)
+
+
+@click.command("_fzf-config", hidden=True)
+def fzf_config_cmd():
+    """Output zsh keybinding config for fzf."""
+    from .config import emit_zsh_config, load_config
+
+    config = load_config()
+    click.echo(emit_zsh_config(config))
+
+
+def register(cli):
+    """Register internal commands with the CLI group."""
+    cli.add_command(record)
+    cli.add_command(init)
+    cli.add_command(fzf_list_cmd)
+    cli.add_command(preview)
+    cli.add_command(set_group)
+    cli.add_command(set_flags)
+    cli.add_command(list_groups)
+    cli.add_command(next_group)
+    cli.add_command(complete_word)
+    cli.add_command(mcp_cmd)
+    cli.add_command(completion)
+    cli.add_command(fzf_config_cmd)