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

boost_cli/core/store.py

@@ -0,0 +1,247 @@
+"""The canonical store (~/.agents/skills) and agent symlinks.
+
+install():  copy skill dir from a tap clone -> store, symlink into every
+            enabled agent dir, record in the lock file, log to the journal.
+"""
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from ..errors import BoostError
+from . import agents, journal, lockfile, paths, policy, registry, util
+
+
+@dataclass
+class InstallResult:
+    name: str
+    dest: Path
+    linked: List[str] = field(default_factory=list)
+    conflicts: List[str] = field(default_factory=list)
+    score: int = 0
+    upgraded: bool = False
+
+
+def skill_store_dir(name: str) -> Path:
+    return paths.store_dir() / name
+
+
+def installed() -> dict:
+    return lockfile.installed()
+
+
+def source_dir_for(entry: dict) -> Path:
+    """Absolute path of a catalog entry's skill dir inside its tap clone."""
+    tap = registry.get(entry["tap"])
+    src = tap.path if entry["rel_dir"] == "." else tap.path / entry["rel_dir"]
+    if not (src / "SKILL.md").exists():
+        raise BoostError("source for %s vanished from tap %s" % (entry["name"], tap.name),
+                        hint="run `boost update %s`" % tap.name)
+    return src
+
+
+def link_agents(name: str, only: Optional[List[str]] = None) -> InstallResult:
+    """Symlink store/<name> into each enabled agent dir. Returns result with
+    .linked (agent names) and .conflicts (paths that were real files/dirs)."""
+    res = InstallResult(name=name, dest=skill_store_dir(name))
+    target = skill_store_dir(name)
+    for agent, adir in agents.enabled_agents().items():
+        if only and agent not in only:
+            continue
+        adir.mkdir(parents=True, exist_ok=True)
+        link = adir / name
+        if link.is_symlink():
+            link.unlink()
+        elif link.exists():
+            res.conflicts.append(str(link))
+            continue
+        link.symlink_to(target)
+        res.linked.append(agent)
+    return res
+
+
+def unlink_agents(name: str) -> List[str]:
+    removed = []
+    for agent, adir in agents.enabled_agents().items():
+        link = adir / name
+        if link.is_symlink():
+            link.unlink()
+            removed.append(agent)
+    return removed
+
+
+def _copy_skill(src: Path, dest: Path) -> None:
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(src, dest,
+                    ignore=shutil.ignore_patterns(".git", "__pycache__", ".DS_Store"))
+
+
+def install(entry: dict, force: bool = False,
+            only_agents: Optional[List[str]] = None) -> InstallResult:
+    """Install a catalog entry. Raises BoostError on policy block or conflict."""
+    name = entry["name"]
+    existing = lockfile.get_skill(name)
+    if existing and existing.get("pinned") and not force:
+        raise BoostError("%s is pinned" % name, hint="`boost unpin %s` first" % name)
+    if existing and not force:
+        raise BoostError("%s is already installed (v%s)" % (name, existing.get("version")),
+                        hint="`boost reinstall %s` to force, `boost update` to upgrade" % name)
+
+    violations = policy.check_install(entry, len(lockfile.installed()))
+    if violations:
+        raise BoostError("policy blocks installing %s: %s" % (name, "; ".join(violations)),
+                        hint="inspect with `boost policy list`")
+
+    src = source_dir_for(entry)
+    dest = skill_store_dir(name)
+    paths.ensure_dirs()
+    _copy_skill(src, dest)
+
+    res = link_agents(name, only=only_agents)
+    res.upgraded = existing is not None
+    res.score, _ = util.score_skill(dest)
+
+    tap = registry.get(entry["tap"])
+    from . import gitutil
+    now = util.now_iso()
+    lockfile.set_skill(name, {
+        "version": entry.get("version", "0.0.0"),
+        "tap": entry["tap"],
+        "source_dir": entry.get("rel_dir", "."),
+        "commit": gitutil.head_commit(tap.path),
+        "sha256": util.sha256_dir(dest),
+        "installed_at": (existing or {}).get("installed_at", now),
+        "updated_at": now,
+        "pinned": bool((existing or {}).get("pinned")),
+        "quarantined": False,
+        "agents": res.linked,
+        "tags": (existing or {}).get("tags", []),
+    })
+    journal.log("install", name, tap=entry["tap"], version=entry.get("version"))
+    return res
+
+
+def install_from_path(src_dir: Path, name: Optional[str] = None,
+                      tap_label: str = "local",
+                      only_agents: Optional[List[str]] = None) -> InstallResult:
+    """Install directly from a local directory (used by `boost import`)."""
+    src_dir = Path(src_dir)
+    if not (src_dir / "SKILL.md").exists():
+        raise BoostError("%s has no SKILL.md" % src_dir)
+    from . import frontmatter
+    meta, _ = frontmatter.parse((src_dir / "SKILL.md").read_text(
+        encoding="utf-8", errors="replace"))
+    name = name or str(meta.get("name") or src_dir.name)
+    dest = skill_store_dir(name)
+    paths.ensure_dirs()
+    _copy_skill(src_dir, dest)
+    res = link_agents(name, only=only_agents)
+    res.score, _ = util.score_skill(dest)
+    now = util.now_iso()
+    existing = lockfile.get_skill(name)
+    lockfile.set_skill(name, {
+        "version": str(meta.get("version") or "0.0.0"),
+        "tap": tap_label,
+        "source_dir": str(src_dir),
+        "commit": "",
+        "sha256": util.sha256_dir(dest),
+        "installed_at": (existing or {}).get("installed_at", now),
+        "updated_at": now,
+        "pinned": False,
+        "quarantined": False,
+        "agents": res.linked,
+        "tags": (existing or {}).get("tags", []),
+    })
+    journal.log("import", name, source=str(src_dir))
+    return res
+
+
+def uninstall(name: str) -> dict:
+    entry = lockfile.get_skill(name)
+    if not entry:
+        raise BoostError("%s is not installed" % name,
+                        hint="see what is with `boost list`")
+    removed_links = unlink_agents(name)
+    dest = skill_store_dir(name)
+    if dest.exists():
+        shutil.rmtree(dest)
+    lockfile.remove_skill(name)
+    journal.log("uninstall", name)
+    return {"name": name, "unlinked": removed_links, "entry": entry}
+
+
+def sync_plan() -> Dict[str, list]:
+    """Compare lock file <-> store <-> agent symlinks.
+
+    Returns {missing_store, missing_links, stale_links, orphaned_store}
+      missing_store:  lock entries whose store dir is gone
+      missing_links:  (skill, agent) pairs that should be linked but aren't
+      stale_links:    paths in agent dirs that are broken/unmanaged symlinks
+      orphaned_store: store dirs not present in the lock file
+    """
+    lock = lockfile.installed()
+    plan: dict[str, list] = {"missing_store": [], "missing_links": [],
+            "stale_links": [], "orphaned_store": []}
+    for name, entry in lock.items():
+        sdir = skill_store_dir(name)
+        if not sdir.is_dir():
+            plan["missing_store"].append(name)
+            continue
+        if entry.get("quarantined"):
+            continue
+        for agent, adir in agents.enabled_agents().items():
+            link = adir / name
+            if not link.is_symlink() or not link.exists():
+                plan["missing_links"].append((name, agent))
+    store_root = paths.store_dir()
+    if store_root.is_dir():
+        for child in store_root.iterdir():
+            if child.is_dir() and child.name not in lock:
+                plan["orphaned_store"].append(child.name)
+    for agent, adir in agents.enabled_agents().items():
+        if not adir.is_dir():
+            continue
+        for link in adir.iterdir():
+            if link.is_symlink():
+                points_into_store = str(paths.store_dir()) in str(
+                    link.resolve() if link.exists() else link.readlink())
+                if not link.exists() or (points_into_store and link.name not in lock):
+                    plan["stale_links"].append(str(link))
+    return plan
+
+
+def sync_apply(plan: Dict[str, list]) -> List[str]:
+    """Fix what sync_plan found. Returns human-readable actions taken."""
+    actions = []
+    for name, agent in plan["missing_links"]:
+        res = link_agents(name, only=[agent])
+        if agent in res.linked:
+            actions.append("linked %s → %s" % (name, agent))
+    for path in plan["stale_links"]:
+        p = Path(path)
+        if p.is_symlink():
+            p.unlink()
+            actions.append("removed stale link %s" % path)
+    for name in plan["missing_store"]:
+        entry = lockfile.get_skill(name) or {}
+        tap_name = entry.get("tap")
+        restored = False
+        if tap_name and tap_name != "local":
+            try:
+                from . import catalog
+                matches = [e for e in catalog.find(name) if e["tap"] == tap_name]
+                if matches:
+                    install(matches[0], force=True)
+                    actions.append("reinstalled missing %s from %s" % (name, tap_name))
+                    restored = True
+            except BoostError:
+                pass
+        if not restored:
+            lockfile.remove_skill(name)
+            actions.append("dropped %s from lock (store dir missing, source gone)" % name)
+    if actions:
+        journal.log("sync", "%d fixes" % len(actions))
+    return actions

boost_cli/core/util.py

@@ -0,0 +1,139 @@
+"""Small shared utilities: time, hashing, versions, skill quality scoring."""
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import List, Tuple
+
+IGNORED = {".git", "__pycache__", ".DS_Store"}
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def rel_time(iso: str) -> str:
+    """'2026-07-16T01:00:00Z' -> '3h ago' (best effort)."""
+    try:
+        then = datetime.strptime(iso, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=timezone.utc)
+    except (ValueError, TypeError):
+        return iso or "?"
+    secs = (datetime.now(timezone.utc) - then).total_seconds()
+    for limit, size, unit in ((60, 1, "s"), (3600, 60, "m"),
+                              (86400, 3600, "h"), (604800, 86400, "d")):
+        if secs < limit:
+            return "%d%s ago" % (max(1, secs // size), unit)
+    if secs < 604800 * 8:
+        return "%dw ago" % (secs // 604800)
+    return then.strftime("%Y-%m-%d")
+
+
+def human_size(n: int) -> str:
+    size = float(n)
+    for unit in ("B", "KB", "MB", "GB"):
+        if size < 1024 or unit == "GB":
+            return ("%d%s" if unit == "B" else "%.1f%s") % (size, unit)
+        size /= 1024.0
+    return str(size)
+
+
+def slugify(name: str) -> str:
+    return re.sub(r"[^a-z0-9-]+", "-", name.strip().lower()).strip("-") or "skill"
+
+
+def sha256_dir(path: Path) -> str:
+    """Deterministic content hash of a directory tree (paths + bytes)."""
+    h = hashlib.sha256()
+    root = Path(path)
+    files = sorted(
+        p for p in root.rglob("*")
+        if p.is_file() and not any(part in IGNORED for part in p.parts)
+    )
+    for f in files:
+        h.update(str(f.relative_to(root)).encode())
+        h.update(b"\0")
+        h.update(f.read_bytes())
+        h.update(b"\0")
+    return h.hexdigest()
+
+
+def dir_size(path: Path) -> int:
+    return sum(p.stat().st_size for p in Path(path).rglob("*") if p.is_file())
+
+
+def semver_tuple(v: str):
+    parts = re.findall(r"\d+", str(v or "0"))[:3]
+    return tuple(int(p) for p in parts) + (0,) * (3 - len(parts))
+
+
+def semver_gt(a: str, b: str) -> bool:
+    return semver_tuple(a) > semver_tuple(b)
+
+
+def score_skill(skill_dir: Path) -> Tuple[int, List[str]]:
+    """Heuristic quality score 0-100 for a skill directory, with notes.
+
+    Shared by `boost install` (display), `boost lint`, and `boost test`.
+    """
+    from . import frontmatter
+
+    skill_md = Path(skill_dir) / "SKILL.md"
+    notes: List[str] = []
+    if not skill_md.exists():
+        return 0, ["missing SKILL.md"]
+    try:
+        text = skill_md.read_text(encoding="utf-8", errors="replace")
+    except OSError as e:
+        return 0, ["unreadable SKILL.md: %s" % e]
+    meta, body = frontmatter.parse(text)
+    score = 20  # exists and parses
+
+    if meta.get("name"):
+        score += 10
+    else:
+        notes.append("frontmatter missing `name`")
+    desc = str(meta.get("description") or "")
+    if desc:
+        score += 10
+        if len(desc) >= 40:
+            score += 5
+        else:
+            notes.append("description is thin (<40 chars)")
+    else:
+        notes.append("frontmatter missing `description`")
+    if meta.get("version"):
+        score += 10
+        if not re.match(r"^\d+\.\d+(\.\d+)?", str(meta["version"])):
+            score -= 5
+            notes.append("version is not semver-ish")
+    else:
+        notes.append("frontmatter missing `version`")
+
+    if len(body.strip()) >= 200:
+        score += 15
+    else:
+        notes.append("body is short (<200 chars)")
+    if re.search(r"^#{1,3} ", body, re.M):
+        score += 10
+    else:
+        notes.append("no markdown headings in body")
+    if "```" in body or re.search(r"^\d+\. ", body, re.M) or re.search(r"^- ", body, re.M):
+        score += 10  # concrete steps or examples
+    else:
+        notes.append("no examples, steps, or code blocks")
+    if not re.search(r"\bTODO\b|\bFIXME\b", body):
+        score += 5
+    else:
+        notes.append("contains TODO/FIXME")
+    if meta.get("license") or (Path(skill_dir) / "LICENSE").exists():
+        score += 5
+    extras = [p for p in Path(skill_dir).iterdir()
+              if p.name not in IGNORED and p.name != "SKILL.md"]
+    if extras:
+        score += 5  # ships supporting references/scripts
+    if len(text) > 48_000:
+        score -= 10
+        notes.append("very large SKILL.md (>48KB) — consider splitting")
+    return max(0, min(100, score)), notes

boost_cli/errors.py

@@ -0,0 +1,11 @@
+"""User-facing errors."""
+from __future__ import annotations
+
+
+class BoostError(Exception):
+    """An expected, user-facing failure. Printed without a traceback."""
+
+    def __init__(self, message: str, hint: str | None = None):
+        super().__init__(message)
+        self.message = message
+        self.hint = hint