boost-skill-cli 1.0.1__py3-none-any.whl

boost_cli/core/agents.py

@@ -0,0 +1,33 @@
+"""AI agent targets: where installed skills get symlinked."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict
+
+from . import config, paths
+
+DISPLAY = {"claude-code": "Claude Code", "windsurf": "Windsurf", "cursor": "Cursor"}
+
+
+def known_agents() -> Dict[str, dict]:
+    """{name: {"dir": Path, "enabled": bool}} for every configured agent."""
+    out = {}
+    for name, spec in (config.get("agents") or {}).items():
+        out[name] = {
+            "dir": paths.expand(str(spec.get("dir", ""))),
+            "enabled": bool(spec.get("enabled", True)),
+        }
+    return out
+
+
+def enabled_agents() -> Dict[str, Path]:
+    return {n: s["dir"] for n, s in known_agents().items() if s["enabled"]}
+
+
+def display_name(agent: str) -> str:
+    return DISPLAY.get(agent, agent)
+
+
+def ensure_agent_dirs() -> None:
+    for d in enabled_agents().values():
+        d.mkdir(parents=True, exist_ok=True)

boost_cli/core/ai.py

@@ -0,0 +1,115 @@
+"""Optional AI bridge for the Intelligence commands and --smart ranking.
+
+Strategy: prefer the `claude` CLI if on PATH, else the Anthropic API via
+urllib when ANTHROPIC_API_KEY is set, else return None so every caller
+degrades to its non-AI fallback.
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import urllib.error
+import urllib.request
+from typing import Optional
+
+from . import config
+
+API_URL = "https://api.anthropic.com/v1/messages"
+
+
+def enabled() -> bool:
+    return bool(config.get("ai.enabled", True)) and not os.environ.get("BOOST_NO_AI")
+
+
+def available() -> bool:
+    return enabled() and (has_cli() or bool(os.environ.get("ANTHROPIC_API_KEY")))
+
+
+def has_cli() -> bool:
+    return shutil.which("claude") is not None
+
+
+def fallback_note() -> str:
+    return ("AI features need the `claude` CLI on PATH or ANTHROPIC_API_KEY set "
+            "— using the heuristic fallback")
+
+
+def ask(prompt: str, system: Optional[str] = None, model: Optional[str] = None,
+        max_tokens: int = 1500, timeout: int = 120) -> Optional[str]:
+    """Ask Claude. Returns the text reply, or None if AI is unavailable/fails."""
+    if not enabled():
+        return None
+    model = model or str(config.get("ai.model"))
+    if has_cli():
+        text = _ask_cli(prompt, system, model, timeout)
+        if text:
+            return text
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        return _ask_api(prompt, system, model, max_tokens, timeout)
+    return None
+
+
+def ask_author(prompt: str, system: Optional[str] = None,
+               max_tokens: int = 4000) -> Optional[str]:
+    """Authoring-grade call (infer/distill/evolve) using the bigger model."""
+    return ask(prompt, system=system, model=str(config.get("ai.author_model")),
+               max_tokens=max_tokens, timeout=240)
+
+
+def _ask_cli(prompt: str, system: Optional[str], model: str,
+             timeout: int) -> Optional[str]:
+    cmd = ["claude", "-p", "--model", model, "--output-format", "text"]
+    if system:
+        cmd += ["--append-system-prompt", system]
+    try:
+        proc = subprocess.run(cmd, input=prompt, capture_output=True,
+                              text=True, timeout=timeout)
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.strip() or None
+
+
+def _ask_api(prompt: str, system: Optional[str], model: str,
+             max_tokens: int, timeout: int) -> Optional[str]:
+    body = {
+        "model": model,
+        "max_tokens": max_tokens,
+        "messages": [{"role": "user", "content": prompt}],
+    }
+    if system:
+        body["system"] = system
+    req = urllib.request.Request(
+        API_URL,
+        data=json.dumps(body).encode(),
+        headers={
+            "content-type": "application/json",
+            "x-api-key": os.environ["ANTHROPIC_API_KEY"],
+            "anthropic-version": "2023-06-01",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode())
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, OSError):
+        return None
+    parts = [b.get("text", "") for b in data.get("content", [])
+             if b.get("type") == "text"]
+    return "\n".join(parts).strip() or None
+
+
+def extract_markdown(text: str) -> str:
+    """Strip a ```markdown fence if the model wrapped its answer in one."""
+    t = (text or "").strip()
+    if t.startswith("```"):
+        lines = t.splitlines()
+        if lines[0].startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        return "\n".join(lines).strip()
+    return t

boost_cli/core/catalog.py

@@ -0,0 +1,144 @@
+"""Skill catalogs: scan tap repos for SKILL.md files -> JSON caches -> search.
+
+A catalog entry (plain dict) has:
+  name, description, version, tap, curated,
+  rel_dir   -- skill directory relative to the tap repo root
+  skill_md  -- path of the SKILL.md relative to the repo root
+  meta      -- full parsed frontmatter
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import List, Optional
+
+from ..errors import BoostError
+from . import frontmatter, gitutil, paths, registry, util
+
+
+def scan_dir(root: Path, tap_name: str = "local", curated: bool = False) -> List[dict]:
+    root = Path(root)
+    entries: List[dict] = []
+    for skill_md in sorted(root.rglob("SKILL.md")):
+        if any(part in util.IGNORED for part in skill_md.parts):
+            continue
+        try:
+            meta, body = frontmatter.parse(
+                skill_md.read_text(encoding="utf-8", errors="replace"))
+        except OSError:
+            continue
+        skill_dir = skill_md.parent
+        name = str(meta.get("name") or "").strip() or (
+            skill_dir.name if skill_dir != root else root.name)
+        desc = str(meta.get("description") or "").strip()
+        if not desc:
+            for line in body.splitlines():
+                line = line.strip()
+                if line and not line.startswith("#"):
+                    desc = line[:160]
+                    break
+        entries.append({
+            "name": util.slugify(name) if " " in name else name,
+            "description": desc,
+            "version": str(meta.get("version") or "0.0.0"),
+            "tap": tap_name,
+            "curated": curated,
+            "rel_dir": str(skill_dir.relative_to(root)) if skill_dir != root else ".",
+            "skill_md": str(skill_md.relative_to(root)),
+            "meta": meta,
+        })
+    return entries
+
+
+def rebuild_tap(tap: "registry.Tap") -> List[dict]:
+    if not tap.is_cloned:
+        raise BoostError("tap %s is not cloned" % tap.name,
+                        hint="run `boost update %s`" % tap.name)
+    entries = scan_dir(tap.path, tap.name, tap.curated)
+    paths.ensure_dirs()
+    tap.cache_file.write_text(json.dumps({
+        "tap": tap.name,
+        "url": tap.url,
+        "generated": util.now_iso(),
+        "commit": gitutil.head_commit(tap.path),
+        "skills": entries,
+    }, indent=1))
+    return entries
+
+
+def load_tap(tap: "registry.Tap", rebuild: bool = False) -> List[dict]:
+    if not rebuild and tap.cache_file.exists():
+        try:
+            return json.loads(tap.cache_file.read_text()).get("skills", [])
+        except (json.JSONDecodeError, OSError):
+            pass
+    if tap.is_cloned:
+        return rebuild_tap(tap)
+    return []
+
+
+def all_entries() -> List[dict]:
+    out: List[dict] = []
+    for tap in registry.list_taps():
+        out.extend(load_tap(tap))
+    return out
+
+
+def find(name: str, tap: Optional[str] = None) -> List[dict]:
+    """Exact-name lookup. Supports 'owner/repo:skill' qualified form."""
+    if ":" in name:
+        tap, name = name.rsplit(":", 1)
+    matches = [e for e in all_entries() if e["name"] == name]
+    if tap:
+        matches = [e for e in matches if e["tap"] == tap or
+                   e["tap"].split("/")[-1] == tap]
+    return matches
+
+
+def resolve_one(name: str) -> dict:
+    """Find exactly one entry or raise with a helpful hint."""
+    matches = find(name)
+    if not matches:
+        scored = search(name)[:3]
+        hint = None
+        if scored:
+            hint = "closest matches: " + ", ".join(e["name"] for e, _ in scored)
+        elif not registry.list_taps():
+            hint = "no taps configured — start with `boost tap --defaults`"
+        raise BoostError("no skill named %r in any tap" % name, hint=hint)
+    if len(matches) > 1:
+        raise BoostError(
+            "%r exists in multiple taps: %s" % (name, ", ".join(e["tap"] for e in matches)),
+            hint="qualify it, e.g. `%s:%s`" % (matches[0]["tap"], name))
+    return matches[0]
+
+
+def search(query: str, entries: Optional[List[dict]] = None):
+    """Rank entries against a query -> [(entry, score)] best-first."""
+    entries = all_entries() if entries is None else entries
+    q = query.lower().strip()
+    tokens = [t for t in re.split(r"[\s,/_-]+", q) if t]
+    scored = []
+    for e in entries:
+        name = e["name"].lower()
+        desc = (e["description"] or "").lower()
+        blob = " ".join([name, desc, json.dumps(e.get("meta", {})).lower()])
+        score = 0
+        if q == name:
+            score += 100
+        elif name.startswith(q):
+            score += 80
+        elif q in name:
+            score += 60
+        if q and q in desc:
+            score += 30
+        score += sum(12 for t in tokens if t in name)
+        score += sum(6 for t in tokens if t in desc)
+        score += sum(2 for t in tokens if t in blob)
+        if score > 0:
+            if e.get("curated"):
+                score += 3  # tiebreak only — never lifts a non-match into results
+            scored.append((e, score))
+    scored.sort(key=lambda x: (-x[1], x[0]["name"]))
+    return scored

boost_cli/core/config.py

@@ -0,0 +1,112 @@
+"""Configuration: ~/.boost/config.json with deep-merged defaults."""
+from __future__ import annotations
+
+import json
+from copy import deepcopy
+from typing import Any
+
+from . import paths
+
+DEFAULTS = {
+    "agents": {
+        "claude-code": {"dir": "~/.claude/skills", "enabled": True},
+        "windsurf": {"dir": "~/.windsurf/skills", "enabled": True},
+        "cursor": {"dir": "~/.cursor/skills", "enabled": True},
+    },
+    "taps": [],  # [{"name": "owner/repo", "url": "...", "curated": bool}]
+    "ai": {
+        "enabled": True,
+        "model": "claude-haiku-4-5-20251001",        # ranking / quick summaries
+        "author_model": "claude-sonnet-5",           # authoring (infer/distill/evolve)
+    },
+    "serve": {"port": 8787},
+    "policy_enforce": True,
+    "telemetry": False,
+}
+
+# Recommended public registries, added via `boost tap --defaults`.
+DEFAULT_TAPS = [
+    {"name": "anthropics/skills", "url": "https://github.com/anthropics/skills",
+     "curated": True,
+     "focus": "Official Anthropic skills — docs, artifacts, MCP, agent workflows"},
+    {"name": "obra/superpowers", "url": "https://github.com/obra/superpowers",
+     "curated": True,
+     "focus": "Community powerhouse — TDD, debugging, planning, subagents"},
+    {"name": "trailofbits/skills", "url": "https://github.com/trailofbits/skills",
+     "curated": True,
+     "focus": "Security auditing from Trail of Bits — CodeQL, Semgrep, vuln hunting"},
+    {"name": "expo/skills", "url": "https://github.com/expo/skills",
+     "curated": True,
+     "focus": "Official Expo team skills — EAS builds, app stores, deployments"},
+    {"name": "K-Dense-AI/claude-scientific-skills",
+     "url": "https://github.com/K-Dense-AI/claude-scientific-skills",
+     "curated": True,
+     "focus": "Scientific computing — research libraries, databases, analysis"},
+]
+
+
+def _merge(base: dict, override: dict) -> dict:
+    out = deepcopy(base)
+    for k, v in (override or {}).items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def load() -> dict:
+    p = paths.config_path()
+    if not p.exists():
+        return deepcopy(DEFAULTS)
+    try:
+        user = json.loads(p.read_text())
+    except (json.JSONDecodeError, OSError):
+        return deepcopy(DEFAULTS)
+    return _merge(DEFAULTS, user)
+
+
+def save(cfg: dict) -> None:
+    paths.ensure_dirs()
+    paths.config_path().write_text(json.dumps(cfg, indent=2, sort_keys=False) + "\n")
+
+
+def get(dotted: str, default=None):
+    node = load()
+    for part in dotted.split("."):
+        if not isinstance(node, dict) or part not in node:
+            return default
+        node = node[part]
+    return node
+
+
+def set_value(dotted: str, raw: str) -> None:
+    """Set a dotted key. Values parse as JSON when possible, else string."""
+    try:
+        value = json.loads(raw)
+    except (json.JSONDecodeError, TypeError):
+        value = raw
+    cfg = load()
+    node: Any = cfg
+    parts = dotted.split(".")
+    for part in parts[:-1]:
+        node = node.setdefault(part, {})
+        if not isinstance(node, dict):
+            raise TypeError("config key %r is not a section" % part)
+    node[parts[-1]] = value
+    save(cfg)
+
+
+def unset(dotted: str) -> bool:
+    cfg = load()
+    node: Any = cfg
+    parts = dotted.split(".")
+    for part in parts[:-1]:
+        node = node.get(part)
+        if not isinstance(node, dict):
+            return False
+    if parts[-1] in node:
+        del node[parts[-1]]
+        save(cfg)
+        return True
+    return False

boost_cli/core/frontmatter.py

@@ -0,0 +1,160 @@
+"""Minimal YAML-frontmatter parser for SKILL.md files (stdlib only).
+
+Supports the subset actually used by skill files:
+  ---
+  name: brainstorming
+  description: Structured ideation &
+    divergent-thinking facilitation      # folded continuation lines
+  version: 1.4.0
+  tags: [ideation, thinking]             # flow lists
+  requires:
+    - other-skill                        # block lists
+  ---
+"""
+from __future__ import annotations
+
+from typing import Tuple
+
+
+def split(text: str) -> Tuple[str, str]:
+    """Return (frontmatter_block, body). Frontmatter block may be ""."""
+    if not text.startswith("---"):
+        return "", text
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return "", text
+    for i in range(1, len(lines)):
+        if lines[i].strip() in ("---", "..."):
+            return "\n".join(lines[1:i]), "\n".join(lines[i + 1:]).lstrip("\n")
+    return "", text
+
+
+def _scalar(raw: str):
+    s = raw.strip()
+    if not s:
+        return ""
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in "'\"":
+        return s[1:-1]
+    low = s.lower()
+    if low in ("true", "yes", "on"):
+        return True
+    if low in ("false", "no", "off"):
+        return False
+    if low in ("null", "~", "none"):
+        return None
+    try:
+        return int(s)
+    except ValueError:
+        pass
+    try:
+        return float(s)
+    except ValueError:
+        pass
+    return s
+
+
+def _flow_list(s: str):
+    inner = s.strip()[1:-1]
+    if not inner.strip():
+        return []
+    return [_scalar(part) for part in _split_commas(inner)]
+
+
+def _split_commas(s: str):
+    parts, buf, quote = [], "", None
+    for ch in s:
+        if quote:
+            buf += ch
+            if ch == quote:
+                quote = None
+        elif ch in "'\"":
+            buf += ch
+            quote = ch
+        elif ch == ",":
+            parts.append(buf)
+            buf = ""
+        else:
+            buf += ch
+    if buf.strip():
+        parts.append(buf)
+    return parts
+
+
+def parse_block(block: str) -> dict:
+    """Parse a frontmatter block into a dict. Best-effort, never raises."""
+    meta: dict = {}
+    key = None
+    in_block = False       # inside a | / > block scalar
+    block_indent = 0       # indent of the key line that opened it
+    for raw in block.splitlines():
+        if not raw.strip():
+            continue
+        indent = len(raw) - len(raw.lstrip())
+        line = raw.strip()
+        # block-scalar content: every deeper-indented line folds in verbatim
+        if in_block:
+            if indent > block_indent:
+                prev = meta.get(key)
+                if isinstance(prev, str):
+                    meta[key] = (prev + " " + line).strip()
+                continue
+            in_block = False
+        if line.startswith("#"):
+            continue
+        # block-list item under the current key
+        if line.startswith("- ") or line == "-":
+            if key is None:
+                continue
+            if not isinstance(meta.get(key), list):
+                meta[key] = [] if meta.get(key) in ("", None) else [meta[key]]
+            meta[key].append(_scalar(line[1:].strip()))
+            continue
+        # folded continuation of the previous plain scalar
+        if indent > 0 and ":" not in line and key is not None:
+            prev = meta.get(key)
+            if isinstance(prev, str):
+                meta[key] = (prev + " " + line).strip()
+            continue
+        if ":" not in line:
+            continue
+        k, _, v = line.partition(":")
+        key = k.strip()
+        v = v.strip()
+        # strip trailing comments on unquoted scalars
+        if v and not v.startswith(("'", '"', "[")) and " #" in v:
+            v = v.split(" #", 1)[0].strip()
+        if v.startswith("[") and v.endswith("]"):
+            meta[key] = _flow_list(v)
+        elif v in ("|", "|-", "|+", ">", ">-", ">+"):
+            meta[key] = ""  # block scalar: folded from the indented lines below
+            in_block, block_indent = True, indent
+        else:
+            meta[key] = _scalar(v)
+    return meta
+
+
+def parse(text: str) -> Tuple[dict, str]:
+    """Parse a SKILL.md's text -> (frontmatter dict, markdown body)."""
+    block, body = split(text)
+    return (parse_block(block) if block else {}), body
+
+
+def dump(meta: dict) -> str:
+    """Serialize a dict back to a frontmatter block (--- fenced)."""
+    lines = ["---"]
+    for k, v in meta.items():
+        if isinstance(v, list):
+            lines.append("%s:" % k)
+            for item in v:
+                lines.append("  - %s" % item)
+        elif isinstance(v, bool):
+            lines.append("%s: %s" % (k, "true" if v else "false"))
+        elif v is None:
+            lines.append("%s:" % k)
+        else:
+            s = str(v)
+            if ":" in s or s != s.strip():
+                s = '"%s"' % s.replace('"', '\\"')
+            lines.append("%s: %s" % (k, s))
+    lines.append("---")
+    return "\n".join(lines)

boost_cli/core/gitutil.py

@@ -0,0 +1,69 @@
+"""Thin git wrapper (stdlib subprocess only)."""
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+from typing import List, Optional
+
+from ..errors import BoostError
+
+
+def has_git() -> bool:
+    return shutil.which("git") is not None
+
+
+def run(args: List[str], cwd: Optional[Path] = None, check: bool = True,
+        timeout: int = 300) -> subprocess.CompletedProcess:
+    if not has_git():
+        raise BoostError("git is required but was not found on PATH",
+                        hint="install git, e.g. `xcode-select --install` or `brew install git`")
+    try:
+        proc = subprocess.run(
+            ["git"] + args, cwd=str(cwd) if cwd else None,
+            capture_output=True, text=True, timeout=timeout,
+        )
+    except subprocess.TimeoutExpired:
+        raise BoostError("git %s timed out after %ds" % (args[0], timeout))
+    if check and proc.returncode != 0:
+        detail = (proc.stderr or proc.stdout or "").strip().splitlines()
+        raise BoostError("git %s failed: %s" % (args[0], detail[-1] if detail else "unknown error"))
+    return proc
+
+
+def clone_shallow(url: str, dest: Path) -> None:
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    run(["clone", "--depth", "1", "--quiet", url, str(dest)], timeout=600)
+
+
+def pull(repo: Path) -> str:
+    """Update a shallow clone. Returns a one-line summary."""
+    before = head_commit(repo)
+    run(["-C", str(repo), "fetch", "--depth", "1", "--quiet", "origin"])
+    run(["-C", str(repo), "reset", "--hard", "--quiet", "origin/HEAD"], check=False)
+    # origin/HEAD may be unset on old git; fall back to the fetched head
+    if head_commit(repo) == before:
+        run(["-C", str(repo), "reset", "--hard", "--quiet", "FETCH_HEAD"])
+    after = head_commit(repo)
+    return "already up to date" if before == after else "%s → %s" % (before[:7], after[:7])
+
+
+def head_commit(repo: Path) -> str:
+    proc = run(["-C", str(repo), "rev-parse", "HEAD"], check=False)
+    return proc.stdout.strip() if proc.returncode == 0 else ""
+
+
+def remote_url(repo: Path) -> str:
+    proc = run(["-C", str(repo), "remote", "get-url", "origin"], check=False)
+    return proc.stdout.strip() if proc.returncode == 0 else ""
+
+
+def log_for_path(repo: Path, rel_path: str = ".", n: int = 20) -> List[str]:
+    """Formatted one-line log entries for a path inside a repo."""
+    proc = run(["-C", str(repo), "log", "--date=short", "-n", str(n),
+                "--pretty=format:%h  %ad  %an  %s", "--", rel_path], check=False)
+    return [ln for ln in proc.stdout.splitlines() if ln.strip()]
+
+
+def is_repo(path: Path) -> bool:
+    return (Path(path) / ".git").exists()