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

boost_cli/core/journal.py

@@ -0,0 +1,70 @@
+"""The pulse journal: append-only feed of skill-management events.
+
+Powers `boost pulse`, `boost trending`, `boost stats`, and `boost who`.
+"""
+from __future__ import annotations
+
+import getpass
+import json
+from typing import List, Optional
+
+from . import paths, util
+
+ROTATE_AT = 5000
+ROTATE_KEEP = 2500
+
+
+def log(action: str, subject: str = "", **fields) -> None:
+    paths.ensure_dirs()
+    event = {"ts": util.now_iso(), "user": _user(), "action": action,
+             "subject": subject}
+    event.update({k: v for k, v in fields.items() if v is not None})
+    p = paths.pulse_path()
+    with p.open("a") as f:
+        f.write(json.dumps(event) + "\n")
+    _maybe_rotate()
+
+
+def _user() -> str:
+    try:
+        return getpass.getuser()
+    except Exception:
+        return "unknown"
+
+
+def events(n: Optional[int] = None, action: Optional[str] = None,
+           subject: Optional[str] = None) -> List[dict]:
+    """Most-recent-first list of journal events."""
+    p = paths.pulse_path()
+    if not p.exists():
+        return []
+    out = []
+    for line in p.read_text().splitlines():
+        try:
+            e = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        if action and e.get("action") != action:
+            continue
+        if subject and e.get("subject") != subject:
+            continue
+        out.append(e)
+    out.reverse()
+    return out[:n] if n else out
+
+
+def rotation_healthy() -> bool:
+    p = paths.pulse_path()
+    if not p.exists():
+        return True
+    return sum(1 for _ in p.open()) <= ROTATE_AT
+
+
+def _maybe_rotate() -> None:
+    p = paths.pulse_path()
+    try:
+        lines = p.read_text().splitlines()
+    except OSError:
+        return
+    if len(lines) > ROTATE_AT:
+        p.write_text("\n".join(lines[-ROTATE_KEEP:]) + "\n")

boost_cli/core/lockfile.py

@@ -0,0 +1,116 @@
+"""The v3 lock file: ~/.agents/skills/.skill-lock.json
+
+Every write snapshots the previous version into ~/.boost/state/lock-history/
+so `boost replay` can show history and roll back.
+
+Skill entry schema (v3):
+  version, tap, source_dir, commit, sha256,
+  installed_at, updated_at, pinned, quarantined, agents[], tags[]
+"""
+from __future__ import annotations
+
+import json
+import shutil
+from typing import List, Optional
+
+from . import paths, util
+
+SCHEMA_VERSION = 3
+HISTORY_KEEP = 50
+
+
+def _skeleton() -> dict:
+    return {"version": SCHEMA_VERSION, "updated": util.now_iso(), "skills": {}}
+
+
+def read() -> dict:
+    p = paths.lockfile_path()
+    if not p.exists():
+        return _skeleton()
+    try:
+        lock = json.loads(p.read_text())
+    except (json.JSONDecodeError, OSError):
+        return _skeleton()
+    lock.setdefault("version", SCHEMA_VERSION)
+    lock.setdefault("skills", {})
+    return lock
+
+
+def write(lock: dict) -> None:
+    paths.ensure_dirs()
+    p = paths.lockfile_path()
+    if p.exists():
+        stamp = util.now_iso().replace(":", "").replace("-", "")
+        dest = paths.lock_history_dir() / ("lock-%s.json" % stamp)
+        n = 2
+        while dest.exists():  # same-second writes each keep their snapshot
+            dest = paths.lock_history_dir() / ("lock-%s-%d.json" % (stamp, n))
+            n += 1
+        # plain copy: the snapshot's mtime is when it was TAKEN (copy2 would
+        # inherit the lock file's older mtime and mis-sort it as oldest)
+        shutil.copy(p, dest)
+        _prune_history()
+    lock["version"] = SCHEMA_VERSION
+    lock["updated"] = util.now_iso()
+    p.write_text(json.dumps(lock, indent=2, sort_keys=True) + "\n")
+
+
+def _history_files() -> List:
+    """History snapshots oldest→newest (mtime, then name — '-2' suffixed
+    same-second snapshots would sort before their base name otherwise)."""
+    return sorted(paths.lock_history_dir().glob("lock-*.json"),
+                  key=lambda f: (f.stat().st_mtime, f.name))
+
+
+def _prune_history() -> None:
+    for old in _history_files()[:-HISTORY_KEEP]:
+        old.unlink()
+
+
+def get_skill(name: str) -> Optional[dict]:
+    return read()["skills"].get(name)
+
+
+def set_skill(name: str, entry: dict) -> None:
+    lock = read()
+    lock["skills"][name] = entry
+    write(lock)
+
+
+def remove_skill(name: str) -> bool:
+    lock = read()
+    if name in lock["skills"]:
+        del lock["skills"][name]
+        write(lock)
+        return True
+    return False
+
+
+def installed() -> dict:
+    return read()["skills"]
+
+
+def history_list() -> List[dict]:
+    """[{id, path, updated, count}] oldest→newest."""
+    out = []
+    for p in _history_files():
+        try:
+            data = json.loads(p.read_text())
+        except (json.JSONDecodeError, OSError):
+            continue
+        out.append({
+            "id": p.stem.replace("lock-", ""),
+            "path": str(p),
+            "updated": data.get("updated", "?"),
+            "count": len(data.get("skills", {})),
+        })
+    return out
+
+
+def history_read(hist_id: str) -> dict:
+    p = paths.lock_history_dir() / ("lock-%s.json" % hist_id)
+    if not p.exists():
+        from ..errors import BoostError
+        raise BoostError("no lock history entry %s" % hist_id,
+                        hint="list entries with `boost replay`")
+    return json.loads(p.read_text())

boost_cli/core/output.py

@@ -0,0 +1,99 @@
+"""Terminal output helpers — colors, symbols, tables.
+
+Conventions used across all commands:
+  ok("copied to ...")    ->  "  ✓ copied to ..."           (green check)
+  warn("...")            ->  "  ! ..."                     (yellow)
+  err("...")             ->  "Error: ..." on stderr        (red)
+  info("...")            ->  plain indented line
+  heading("...")         ->  bold section header
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RED = "\033[31m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+BLUE = "\033[34m"
+MAGENTA = "\033[35m"
+CYAN = "\033[36m"
+
+
+def use_color(stream=None) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("CLICOLOR_FORCE"):
+        return True
+    stream = stream or sys.stdout
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def c(text: str, *styles: str) -> str:
+    if not styles or not use_color():
+        return text
+    return "".join(styles) + text + RESET
+
+
+def ok(msg: str) -> None:
+    print("  " + c("✓", GREEN) + " " + msg)
+
+
+def warn(msg: str) -> None:
+    print("  " + c("!", YELLOW) + " " + c(msg, YELLOW))
+
+
+def err(msg: str, hint: str | None = None) -> None:
+    print(c("Error: ", RED, BOLD) + msg, file=sys.stderr)
+    if hint:
+        print(c("  hint: " + hint, DIM), file=sys.stderr)
+
+
+def info(msg: str = "") -> None:
+    print("  " + msg if msg else "")
+
+
+def dim(msg: str) -> None:
+    print(c(msg, DIM))
+
+
+def heading(msg: str) -> None:
+    print(c("==> ", BLUE, BOLD) + c(msg, BOLD))
+
+
+def kv(key: str, value: str, width: int = 14) -> None:
+    print("  " + c(key.ljust(width), DIM) + str(value))
+
+
+def table(rows, headers=None) -> None:
+    """Print an aligned table. rows: list of tuples of strings."""
+    rows = [[str(x) for x in r] for r in rows]
+    all_rows = ([list(map(str, headers))] if headers else []) + rows
+    if not all_rows:
+        return
+    widths = [max(len(r[i]) for r in all_rows if i < len(r))
+              for i in range(max(len(r) for r in all_rows))]
+    if headers:
+        line = "  ".join(str(h).ljust(widths[i]) for i, h in enumerate(headers))
+        print(c(line, BOLD))
+    for r in rows:
+        print("  ".join(cell.ljust(widths[i]) for i, cell in enumerate(r)).rstrip())
+
+
+def confirm(prompt: str, default: bool = False) -> bool:
+    if os.environ.get("BOOST_ASSUME_YES") or "--yes" in sys.argv or "-y" in sys.argv:
+        return True
+    if not sys.stdin.isatty():
+        return default
+    suffix = " [Y/n] " if default else " [y/N] "
+    try:
+        answer = input(prompt + suffix).strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return False
+    if not answer:
+        return default
+    return answer in ("y", "yes")

boost_cli/core/paths.py

@@ -0,0 +1,111 @@
+"""All filesystem locations boost touches.
+
+Everything derives from $HOME (or explicit env overrides) at call time so
+tests can sandbox the whole tool by exporting HOME=/tmp/somewhere.
+
+Layout:
+  ~/.boost/repos/           shallow git clones of tap registries
+  ~/.boost/cache/           JSON catalogs built from SKILL.md frontmatter
+  ~/.boost/logs/            command logs
+  ~/.boost/state/           pins, tags, policy, profiles, pulse feed, snapshots
+  ~/.boost/config.json      configuration
+  ~/.agents/skills/        canonical store — single source of truth
+  ~/.agents/skills/.skill-lock.json   v3 lock file
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+
+def home() -> Path:
+    return Path(os.environ.get("HOME") or str(Path.home()))
+
+
+def expand(p: str) -> Path:
+    """Expand a leading ~ against home() (which respects the HOME env var)."""
+    if p == "~":
+        return home()
+    if p.startswith("~/"):
+        return home() / p[2:]
+    return Path(p)
+
+
+def boost_home() -> Path:
+    override = os.environ.get("BOOST_HOME")
+    return Path(override) if override else home() / ".boost"
+
+
+def repos_dir() -> Path:
+    return boost_home() / "repos"
+
+
+def cache_dir() -> Path:
+    return boost_home() / "cache"
+
+
+def logs_dir() -> Path:
+    return boost_home() / "logs"
+
+
+def state_dir() -> Path:
+    return boost_home() / "state"
+
+
+def snapshots_dir() -> Path:
+    return state_dir() / "snapshots"
+
+
+def lock_history_dir() -> Path:
+    return state_dir() / "lock-history"
+
+
+def profiles_dir() -> Path:
+    return state_dir() / "profiles"
+
+
+def config_path() -> Path:
+    return boost_home() / "config.json"
+
+
+def store_dir() -> Path:
+    """Canonical store for installed skills."""
+    override = os.environ.get("BOOST_AGENTS_STORE")
+    return Path(override) if override else home() / ".agents" / "skills"
+
+
+def lockfile_path() -> Path:
+    return store_dir() / ".skill-lock.json"
+
+
+def pulse_path() -> Path:
+    return state_dir() / "pulse.jsonl"
+
+
+def policy_path() -> Path:
+    return state_dir() / "policy.json"
+
+
+def repo_root() -> Path:
+    """The boost source checkout this module runs from."""
+    return Path(__file__).resolve().parent.parent.parent
+
+
+def launcher() -> Path:
+    """Absolute path other processes should use to invoke boost.
+
+    A pip/pipx install has no `boost` shim next to the package (repo_root()
+    lands inside site-packages), so prefer the console script on PATH and
+    fall back to the source-checkout shim.
+    """
+    found = shutil.which("boost")
+    return Path(found) if found else repo_root() / "boost"
+
+
+def ensure_dirs() -> None:
+    for d in (
+        boost_home(), repos_dir(), cache_dir(), logs_dir(), state_dir(),
+        snapshots_dir(), lock_history_dir(), profiles_dir(), store_dir(),
+    ):
+        d.mkdir(parents=True, exist_ok=True)

boost_cli/core/policy.py

@@ -0,0 +1,63 @@
+"""Governance policies: ~/.boost/state/policy.json
+
+Consulted by store.install() (when config policy_enforce is true) and by
+`boost audit` / `boost policy check`.
+"""
+from __future__ import annotations
+
+import json
+from typing import List
+
+from . import config, paths
+
+DEFAULTS = {
+    "blocked_skills": [],      # names never allowed
+    "blocked_taps": [],        # tap names never allowed
+    "allowed_taps": [],        # if non-empty, ONLY these taps allowed
+    "require_description": False,
+    "require_version": False,
+    "min_quality_score": 0,    # enforced by `boost audit`, advisory at install
+    "max_skills": None,        # cap on installed count
+    "pin_only": False,         # block installs/updates entirely (frozen env)
+}
+
+
+def load() -> dict:
+    p = paths.policy_path()
+    base = dict(DEFAULTS)
+    if p.exists():
+        try:
+            base.update(json.loads(p.read_text()))
+        except (json.JSONDecodeError, OSError):
+            pass
+    return base
+
+
+def save(pol: dict) -> None:
+    paths.ensure_dirs()
+    known = {k: pol.get(k, DEFAULTS[k]) for k in DEFAULTS}
+    paths.policy_path().write_text(json.dumps(known, indent=2) + "\n")
+
+
+def check_install(entry: dict, installed_count: int) -> List[str]:
+    """Return a list of violation strings (empty = allowed)."""
+    if not config.get("policy_enforce", True):
+        return []
+    pol = load()
+    v: List[str] = []
+    name, tap = entry.get("name", ""), entry.get("tap", "")
+    if pol["pin_only"]:
+        v.append("environment is pin-only (frozen)")
+    if name in pol["blocked_skills"]:
+        v.append("skill %r is on the blocklist" % name)
+    if tap in pol["blocked_taps"]:
+        v.append("tap %r is blocked" % tap)
+    if pol["allowed_taps"] and tap not in pol["allowed_taps"] and tap != "local":
+        v.append("tap %r is not on the allowlist" % tap)
+    if pol["require_description"] and not entry.get("description"):
+        v.append("skill has no description (required by policy)")
+    if pol["require_version"] and entry.get("version") in (None, "", "0.0.0"):
+        v.append("skill has no version (required by policy)")
+    if pol["max_skills"] is not None and installed_count >= int(pol["max_skills"]):
+        v.append("max_skills limit (%s) reached" % pol["max_skills"])
+    return v

boost_cli/core/registry.py

@@ -0,0 +1,112 @@
+"""Tap registries: GitHub repos (or local paths) full of SKILL.md files."""
+from __future__ import annotations
+
+import difflib
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional
+
+from ..errors import BoostError
+from . import config, gitutil, paths
+
+
+@dataclass
+class Tap:
+    name: str          # "anthropics/skills" or a short alias
+    url: str           # https URL or local path
+    curated: bool = False
+
+    @property
+    def safe_name(self) -> str:
+        return self.name.replace("/", "__")
+
+    @property
+    def path(self) -> Path:
+        return paths.repos_dir() / self.safe_name
+
+    @property
+    def cache_file(self) -> Path:
+        return paths.cache_dir() / (self.safe_name + ".json")
+
+    @property
+    def is_cloned(self) -> bool:
+        return self.path.is_dir()
+
+
+def parse_spec(spec: str):
+    """Resolve a tap spec -> (name, url).
+
+    Accepts: owner/repo | full git URL | existing local path.
+    """
+    spec = spec.strip().rstrip("/")
+    p = Path(spec).expanduser()
+    if p.exists() and p.is_dir():
+        return (p.resolve().name, str(p.resolve()))
+    if spec.startswith(("http://", "https://", "git@", "ssh://")):
+        tail = spec.split(":")[-1] if spec.startswith("git@") else spec
+        parts = [x for x in tail.replace(".git", "").split("/") if x][-2:]
+        return ("/".join(parts), spec)
+    if "/" in spec and " " not in spec:
+        return (spec, "https://github.com/%s" % spec)
+    raise BoostError("cannot parse tap spec %r" % spec,
+                    hint="use owner/repo, a git URL, or a local directory")
+
+
+def list_taps() -> List[Tap]:
+    return [Tap(name=t["name"], url=t.get("url", ""), curated=bool(t.get("curated")))
+            for t in config.get("taps", [])]
+
+
+def get(name: str) -> Tap:
+    taps = list_taps()
+    for t in taps:
+        if t.name == name or t.safe_name == name or t.name.split("/")[-1] == name:
+            return t
+    close = difflib.get_close_matches(name, [t.name for t in taps], n=1)
+    raise BoostError("no such tap: %s" % name,
+                    hint=("did you mean %s?" % close[0]) if close
+                    else "list taps with `boost taps`")
+
+
+def add(spec: str, curated: bool = False) -> Tap:
+    name, url = parse_spec(spec)
+    for existing in list_taps():
+        if existing.name == name:
+            raise BoostError("tap %s is already configured" % name,
+                            hint="`boost update %s` to refresh it" % name)
+    tap = Tap(name=name, url=url, curated=curated)
+    paths.ensure_dirs()
+    if tap.path.exists():
+        shutil.rmtree(tap.path)
+    gitutil.clone_shallow(url, tap.path)
+    cfg = config.load()
+    cfg.setdefault("taps", []).append(
+        {"name": name, "url": url, "curated": curated})
+    config.save(cfg)
+    return tap
+
+
+def remove(name: str) -> Tap:
+    tap = get(name)
+    cfg = config.load()
+    cfg["taps"] = [t for t in cfg.get("taps", []) if t["name"] != tap.name]
+    config.save(cfg)
+    if tap.path.exists():
+        shutil.rmtree(tap.path)
+    if tap.cache_file.exists():
+        tap.cache_file.unlink()
+    return tap
+
+
+def update(name: Optional[str] = None) -> dict:
+    """git-pull one tap (or all). Returns {tap_name: summary}."""
+    targets = [get(name)] if name else list_taps()
+    results = {}
+    for tap in targets:
+        if not tap.is_cloned:
+            gitutil.clone_shallow(tap.url, tap.path)
+            results[tap.name] = "cloned"
+        else:
+            results[tap.name] = gitutil.pull(tap.path)
+    return results