copa-cli 0.2.0__py3-none-any.whl

copa/models.py

@@ -0,0 +1,112 @@
+"""Dataclasses for Copa entities."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Command:
+    """A tracked command."""
+
+    id: int = 0
+    command: str = ""
+    description: str = ""
+    frequency: int = 0
+    last_used: float = 0.0
+    first_added: float = 0.0
+    source: str = "manual"  # history|manual|shared|scan|auto
+    group_name: str | None = None
+    shared_set: str | None = None
+    is_pinned: bool = False
+    needs_description: bool = False
+    tags: list[str] = field(default_factory=list)
+    flags: dict[str, str] = field(default_factory=dict)
+    score: float = 0.0  # computed at query time
+
+    @classmethod
+    def from_row(cls, row: dict) -> Command:
+        cmd = cls(
+            id=row["id"],
+            command=row["command"],
+            description=row.get("description", ""),
+            frequency=row.get("frequency", 0),
+            last_used=row.get("last_used", 0.0),
+            first_added=row.get("first_added", 0.0),
+            source=row.get("source", "manual"),
+            group_name=row.get("group_name"),
+            shared_set=row.get("shared_set"),
+            is_pinned=bool(row.get("is_pinned", 0)),
+            needs_description=bool(row.get("needs_description", 0)),
+        )
+        flags_raw = row.get("flags", "")
+        if flags_raw:
+            try:
+                cmd.flags = json.loads(flags_raw)
+            except (json.JSONDecodeError, TypeError):
+                cmd.flags = {}
+        return cmd
+
+    def to_dict(self) -> dict:
+        d = {
+            "command": self.command,
+            "description": self.description,
+            "tags": self.tags,
+        }
+        if self.flags:
+            d["flags"] = self.flags
+        return d
+
+
+@dataclass
+class SharedSet:
+    """A shared command set."""
+
+    name: str = ""
+    description: str = ""
+    source_path: str | None = None
+    loaded_at: float = 0.0
+    version: str = "1.0"
+    author: str = ""
+
+    @classmethod
+    def from_row(cls, row: dict) -> SharedSet:
+        return cls(
+            name=row["name"],
+            description=row.get("description", ""),
+            source_path=row.get("source_path"),
+            loaded_at=row.get("loaded_at", 0.0),
+            version=row.get("version", "1.0"),
+            author=row.get("author", ""),
+        )
+
+
+@dataclass
+class CopaFile:
+    """Represents a .copa export/import file."""
+
+    copa_version: str = "1.0"
+    name: str = ""
+    description: str = ""
+    author: str = ""
+    commands: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "copa_version": self.copa_version,
+            "name": self.name,
+            "description": self.description,
+            "author": self.author,
+            "commands": self.commands,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> CopaFile:
+        return cls(
+            copa_version=data.get("copa_version", "1.0"),
+            name=data.get("name", ""),
+            description=data.get("description", ""),
+            author=data.get("author", ""),
+            commands=data.get("commands", []),
+        )

copa/scanner.py

@@ -0,0 +1,153 @@
+"""Scanner for executable script metadata across $PATH."""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+from .db import Database
+
+# --- Pass 1: #@ Protocol headers (highest priority) ---
+PROTOCOL_DESC = re.compile(r"^#@\s*[Dd]escription:\s*(.+)$")
+PROTOCOL_USAGE = re.compile(r"^#@\s*[Uu]sage:\s*(.+)$")
+PROTOCOL_PURPOSE = re.compile(r"^#@\s*[Pp]urpose:\s*(.+)$")
+PROTOCOL_FLAG = re.compile(r"^#@\s*[Ff]lag:\s*(.+)$")
+
+# --- Pass 2: Legacy fallback patterns ---
+LEGACY_PATTERNS = [
+    re.compile(r"^#\s*[Dd]escription:\s*(.+)$"),
+    re.compile(r"^#\s*[Pp]urpose:\s*(.+)$"),
+    re.compile(r"^#\s*[Uu]sage:\s*(.+)$"),
+    re.compile(r'^"""\s*(.+?)(?:""")?$'),  # Python docstring one-liner
+    re.compile(r"^#\s*(?![@!])(.{10,80})$"),  # Generic comment (skip @ prefix lines)
+]
+
+
+def extract_description(path: Path) -> tuple[str, dict[str, str]]:
+    """Extract a description and flags from a script file's header comments.
+
+    Uses a two-pass approach:
+      Pass 1 — #@ protocol headers (highest priority)
+      Pass 2 — Legacy comment patterns (fallback)
+
+    Returns (description_string, flags_dict).
+    """
+    try:
+        with open(path, "r", errors="replace") as f:
+            lines = []
+            for i, line in enumerate(f):
+                if i >= 50:  # Check first 50 lines for protocol headers
+                    break
+                lines.append(line.rstrip())
+    except OSError:
+        return "", {}
+
+    # --- Pass 1: Protocol headers ---
+    description = ""
+    usage = ""
+    purpose = ""
+    flags: dict[str, str] = {}
+
+    for line in lines:
+        m = PROTOCOL_DESC.match(line)
+        if m:
+            description = m.group(1).strip()
+            continue
+        m = PROTOCOL_USAGE.match(line)
+        if m:
+            usage = m.group(1).strip()
+            continue
+        m = PROTOCOL_PURPOSE.match(line)
+        if m:
+            purpose = m.group(1).strip()
+            continue
+        m = PROTOCOL_FLAG.match(line)
+        if m:
+            flag_text = m.group(1).strip()
+            # "#@ Flag: -w, --wipe: Wipe userdata" → {"-w, --wipe": "Wipe userdata"}
+            parts = flag_text.split(":", 1)
+            flag_name = parts[0].strip()
+            flag_desc = parts[1].strip() if len(parts) > 1 else ""
+            flags[flag_name] = flag_desc
+            continue
+
+    if description:
+        parts = [description]
+        if usage:
+            parts.append(f"Usage: {usage}")
+        if purpose:
+            parts.append(f"Purpose: {purpose}")
+        return " | ".join(parts), flags
+
+    # --- Pass 2: Legacy fallbacks ---
+    for line in lines:
+        for pattern in LEGACY_PATTERNS:
+            m = pattern.match(line)
+            if m:
+                desc = m.group(1).strip()
+                if desc and not desc.startswith("!") and len(desc) > 5:
+                    return desc, flags
+
+    return "", flags
+
+
+def _scan_single_directory(db: Database, directory: Path) -> int:
+    """Scan one directory for executable scripts and add them to Copa.
+
+    Returns number of scripts added.
+    """
+    if not directory.is_dir():
+        return 0
+
+    added = 0
+    try:
+        entries = sorted(directory.iterdir())
+    except PermissionError:
+        return 0
+
+    for entry in entries:
+        try:
+            is_file = entry.is_file()
+            is_exec = os.access(entry, os.X_OK)
+        except (PermissionError, OSError):
+            continue
+
+        if is_file and is_exec:
+            name = entry.name
+            # Skip hidden files and common non-script files
+            if name.startswith(".") or name.endswith((".md", ".txt", ".log")):
+                continue
+
+            description, flags = extract_description(entry)
+            if not db.command_exists(name):
+                db.add_command(
+                    command=name,
+                    description=description,
+                    source="scan",
+                    flags=flags if flags else None,
+                )
+                added += 1
+
+    return added
+
+
+def scan_directory(db: Database, directory: Path | None = None) -> int:
+    """Scan directories for executable scripts and add them to Copa.
+
+    If directory is given, scans only that directory.
+    Otherwise, scans all directories on $PATH.
+
+    Returns number of scripts added.
+    """
+    if directory is not None:
+        return _scan_single_directory(db, directory)
+
+    # Default: scan all $PATH directories
+    path_dirs = os.environ.get("PATH", "").split(os.pathsep)
+    added = 0
+    for dir_str in path_dirs:
+        d = Path(dir_str)
+        if d.is_dir():
+            added += _scan_single_directory(db, d)
+    return added

copa/scoring.py

@@ -0,0 +1,45 @@
+"""Scoring algorithm: frequency + recency hybrid."""
+
+from __future__ import annotations
+
+import math
+import time
+
+from .models import Command
+
+# Tuning constants
+FREQ_WEIGHT = 2.0
+RECENCY_WEIGHT = 8.0
+HALF_LIFE_SECONDS = 3 * 24 * 3600  # 3 days
+PIN_BONUS = 1000.0
+
+
+def compute_score(cmd: Command, now: float | None = None) -> float:
+    """Compute hybrid score: 2.0*log(1+freq) + 8.0*0.5^(age/3days).
+
+    Pinned commands get +1000 bonus.
+    """
+    if now is None:
+        now = time.time()
+
+    freq_score = FREQ_WEIGHT * math.log(1 + cmd.frequency)
+
+    age_seconds = max(0, now - cmd.last_used) if cmd.last_used > 0 else HALF_LIFE_SECONDS * 10
+    recency_score = RECENCY_WEIGHT * (0.5 ** (age_seconds / HALF_LIFE_SECONDS))
+
+    score = freq_score + recency_score
+
+    if cmd.is_pinned:
+        score += PIN_BONUS
+
+    return score
+
+
+def rank_commands(commands: list[Command], now: float | None = None) -> list[Command]:
+    """Score and sort commands by descending score."""
+    if now is None:
+        now = time.time()
+    for cmd in commands:
+        cmd.score = compute_score(cmd, now)
+    commands.sort(key=lambda c: c.score, reverse=True)
+    return commands

copa/sharing.py

@@ -0,0 +1,154 @@
+"""Shared command set management."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import time
+from pathlib import Path
+
+from .db import Database
+from .models import CopaFile, SharedSet
+
+
+def find_fbsource_root() -> Path | None:
+    """Find the fbsource checkout root."""
+    # Check env var first
+    env_root = os.environ.get("FBSOURCE_ROOT")
+    if env_root:
+        p = Path(env_root)
+        if p.is_dir():
+            return p
+
+    # Try hg root from common locations
+    for candidate in [Path.home() / "fbsource", Path("/data/users") / os.getenv("USER", "") / "fbsource"]:
+        if candidate.is_dir():
+            return candidate
+
+    # Try hg root
+    try:
+        result = subprocess.run(
+            ["hg", "root"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            p = Path(result.stdout.strip())
+            if p.is_dir():
+                return p
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+
+    return None
+
+
+def resolve_copa_path(source: str) -> Path | None:
+    """Resolve a .copa source path.
+
+    Accepts:
+    - Absolute/relative file paths
+    - fbsource-relative paths (e.g., arvr/agios/supra/SupraCommands)
+    """
+    # Direct file path
+    p = Path(source).expanduser()
+    if p.exists():
+        return p
+
+    # Add .copa extension if missing
+    if not source.endswith(".copa"):
+        p_ext = Path(source + ".copa").expanduser()
+        if p_ext.exists():
+            return p_ext
+
+    # fbsource-relative
+    root = find_fbsource_root()
+    if root:
+        fbpath = root / source
+        if fbpath.exists():
+            return fbpath
+        if not source.endswith(".copa"):
+            fbpath_ext = root / (source + ".copa")
+            if fbpath_ext.exists():
+                return fbpath_ext
+
+    return None
+
+
+def load_copa_file(path: Path) -> CopaFile:
+    """Load a .copa JSON file."""
+    data = json.loads(path.read_text())
+    return CopaFile.from_dict(data)
+
+
+def export_group(db: Database, group_name: str, author: str = "") -> CopaFile:
+    """Export a group as a CopaFile."""
+    commands = db.list_commands(group_name=group_name, limit=10000)
+    copa_file = CopaFile(
+        name=group_name,
+        description=f"Exported from Copa group '{group_name}'",
+        author=author,
+        commands=[cmd.to_dict() for cmd in commands],
+    )
+    return copa_file
+
+
+def import_shared_set(db: Database, copa_file: CopaFile, source_path: str | None = None) -> int:
+    """Import commands from a CopaFile into the database.
+
+    Returns number of commands imported.
+    """
+    # Register the shared set
+    ss = SharedSet(
+        name=copa_file.name,
+        description=copa_file.description,
+        source_path=source_path,
+        loaded_at=time.time(),
+        version=copa_file.copa_version,
+        author=copa_file.author,
+    )
+    db.upsert_shared_set(ss)
+
+    count = 0
+    for cmd_data in copa_file.commands:
+        command = cmd_data.get("command", "").strip()
+        if not command:
+            continue
+        description = cmd_data.get("description", "")
+        tags = cmd_data.get("tags", [])
+        flags = cmd_data.get("flags")
+
+        db.add_command(
+            command=command,
+            description=description,
+            source="shared",
+            group_name=copa_file.name,
+            shared_set=copa_file.name,
+            tags=tags,
+            flags=flags if flags else None,
+        )
+        count += 1
+
+    return count
+
+
+def sync_directory(db: Database, directory: str) -> dict[str, int]:
+    """Sync all .copa files from a directory tree.
+
+    Returns dict of {filename: commands_imported}.
+    """
+    path = resolve_copa_path(directory)
+    if not path or not path.is_dir():
+        return {}
+
+    results = {}
+    for copa_path in sorted(path.rglob("*.copa")):
+        try:
+            copa_file = load_copa_file(copa_path)
+            count = import_shared_set(db, copa_file, source_path=str(copa_path))
+            results[copa_path.name] = count
+        except (json.JSONDecodeError, KeyError):
+            results[copa_path.name] = -1  # error indicator
+
+    return results