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

boost_cli/commands/pkg.py

@@ -0,0 +1,828 @@
+"""Package Management commands (12): install, uninstall, sync, update,
+reinstall, bundle, import, migrate, pin, unpin, snapshot, export."""
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import os
+import shutil
+import sys
+import tarfile
+import tempfile
+import zipfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from ..core import (agents, catalog, gitutil, journal, lockfile, paths,
+                    registry, store, util)
+from ..core import output as out
+from ..errors import BoostError
+
+
+def _tilde(p) -> str:
+    """Contract $HOME to ~ for display (also matches the resolved home,
+    so /private/var vs /var symlinks on macOS still contract)."""
+    s = str(p)
+    for h in (str(paths.home()), str(paths.home().resolve())):
+        if s == h or s.startswith(h + os.sep):
+            return "~" + s[len(h):]
+    return s
+
+
+def _plural(n: int, word: str) -> str:
+    return "%d %s%s" % (n, word, "" if n == 1 else "s")
+
+
+def _check_agents(names: Optional[List[str]]) -> Optional[List[str]]:
+    """Validate --agent values against configured agents."""
+    if not names:
+        return None
+    known = agents.known_agents()
+    bad = [n for n in names if n not in known]
+    if bad:
+        raise BoostError("unknown agent%s: %s" % ("s" if len(bad) > 1 else "",
+                                                 ", ".join(bad)),
+                        hint="known agents: %s" % ", ".join(known))
+    return names
+
+
+def _report_result(res: store.InstallResult) -> None:
+    """The canonical three-line install report."""
+    out.ok("copied to %s" % _tilde(res.dest))
+    if res.linked:
+        out.ok("linked → %s" % " · ".join(res.linked))
+    else:
+        out.warn("no agent links created (no enabled agents?)")
+    for path in res.conflicts:
+        out.warn("not linked: %s exists and is not managed by boost" % _tilde(path))
+    out.ok("lock updated (.skill-lock.json)")
+
+
+def _boostfile_text(skills: Dict[str, dict], via: str = "boost bundle dump") -> str:
+    """Render lock entries as a Boostfile (taps first, then sorted skills)."""
+    lines = ["# Boostfile — generated by %s" % via]
+    taps = sorted({e.get("tap") or "" for e in skills.values()} - {"", "local"})
+    for tname in taps:
+        try:
+            url = registry.get(tname).url
+        except BoostError:
+            url = ""
+        lines.append(("tap %s %s" % (tname, url)).rstrip())
+    for name in sorted(skills):
+        e = skills[name]
+        if (e.get("tap") or "local") == "local":
+            lines.append("# local skill (no tap source): %s" % name)
+        else:
+            lines.append("skill %s:%s@%s" % (e["tap"], name,
+                                             e.get("version", "0.0.0")))
+    return "\n".join(lines) + "\n"
+
+
+# ── install ──────────────────────────────────────────────────────────────
+
+def cmd_install(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(prog="boost install",
+                                 description="Install a skill from a tap registry")
+    ap.add_argument("names", nargs="+", metavar="NAME",
+                    help="skill name, optionally qualified as tap:skill")
+    ap.add_argument("--force", action="store_true",
+                    help="reinstall even if already installed or pinned")
+    ap.add_argument("--agent", action="append", metavar="A",
+                    help="link only into this agent (repeatable)")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="show what would happen without changing anything")
+    args = ap.parse_args(argv)
+    only = _check_agents(args.agent)
+    multi = len(args.names) > 1
+    entries, failed = [], 0
+    for n in args.names:
+        try:
+            entries.append(catalog.resolve_one(n))
+        except BoostError as err:
+            if not multi:
+                raise
+            out.warn("%s: %s" % (n, err.message))
+            failed += 1
+
+    if args.dry_run:
+        targets = [a for a in agents.enabled_agents() if not only or a in only]
+        for e in entries:
+            verb = "upgrade" if lockfile.get_skill(e["name"]) else "install"
+            out.info("would %s %s v%s from %s" % (verb, e["name"],
+                                                  e["version"], e["tap"]))
+            out.info("  copy  %s → %s" % (_tilde(store.source_dir_for(e)),
+                                          _tilde(store.skill_store_dir(e["name"]))))
+            out.info("  link  → %s" % (" · ".join(targets) or "(no enabled agents)"))
+        out.info("dry run — nothing was changed")
+        return 1 if failed else 0
+
+    results = []
+    for e in entries:
+        if multi:
+            out.heading("%s v%s (%s)" % (e["name"], e["version"], e["tap"]))
+        try:
+            res = store.install(e, force=args.force, only_agents=only)
+        except BoostError as err:
+            if not multi:
+                raise
+            out.warn("%s: %s" % (e["name"], err.message))
+            failed += 1
+            continue
+        _report_result(res)
+        results.append(res)
+    if results:
+        new = sum(1 for r in results if not r.upgraded)
+        parts = []
+        if new:
+            parts.append("Installed %s" % _plural(new, "new skill"))
+        if len(results) - new:
+            parts.append("Upgraded %s" % _plural(len(results) - new, "skill"))
+        avg = round(sum(r.score for r in results) / len(results))
+        out.info("%s; quality score %d/100" % ("; ".join(parts), avg))
+    return 1 if failed else 0
+
+
+# ── uninstall ────────────────────────────────────────────────────────────
+
+def cmd_uninstall(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(
+        prog="boost uninstall",
+        description="Remove an installed skill, rule, workflow, or config")
+    ap.add_argument("names", nargs="+", metavar="NAME")
+    args = ap.parse_args(argv)
+    removed, failed = 0, 0
+    for name in args.names:
+        dest = store.skill_store_dir(name)
+        try:
+            info = store.uninstall(name)
+        except BoostError as err:
+            if len(args.names) == 1:
+                raise
+            out.warn("%s: %s" % (name, err.message))
+            failed += 1
+            continue
+        if info["unlinked"]:
+            out.ok("unlinked ← %s" % " · ".join(info["unlinked"]))
+        out.ok("removed %s" % _tilde(dest))
+        removed += 1
+    if removed:
+        out.info("Uninstalled %s" % _plural(removed, "skill"))
+    return 1 if failed else 0
+
+
+# ── sync ─────────────────────────────────────────────────────────────────
+
+_PLAN_LABELS = [
+    ("missing_store", "missing from store"),
+    ("missing_links", "missing agent links"),
+    ("stale_links", "stale links"),
+    ("orphaned_store", "orphaned store dirs"),
+]
+
+
+def cmd_sync(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(
+        prog="boost sync",
+        description="Reconcile installed skills & symlinks against the lock file")
+    ap.add_argument("--diff", action="store_true",
+                    help="show the plan without applying it")
+    ap.add_argument("--prune", action="store_true",
+                    help="also delete orphaned store dirs")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    args = ap.parse_args(argv)
+    plan = store.sync_plan()
+
+    if args.diff:
+        if args.json:
+            print(json.dumps(plan, indent=2))
+            return 0
+        if not any(plan.values()):
+            out.ok("everything in sync")
+            return 0
+        for key, label in _PLAN_LABELS:
+            if not plan[key]:
+                continue
+            out.heading("%s (%d)" % (label, len(plan[key])))
+            for item in plan[key]:
+                if key == "missing_links":
+                    out.info("%s → %s" % (item[0], item[1]))
+                else:
+                    out.info(_tilde(item))
+        return 0
+
+    actions = store.sync_apply(plan)
+    orphans = plan["orphaned_store"]
+    pruned = []
+    if args.prune and orphans:
+        go = (bool(os.environ.get("BOOST_ASSUME_YES")) if args.json else
+              out.confirm("Delete %s: %s?" % (_plural(len(orphans), "orphaned store dir"),
+                                              ", ".join(orphans))))
+        if go:
+            for name in orphans:
+                target = store.skill_store_dir(name)
+                if target.is_dir():
+                    shutil.rmtree(target)
+                journal.log("prune", name)
+                pruned.append(name)
+    left = [n for n in orphans if n not in pruned]
+    if args.json:
+        print(json.dumps({"actions": actions, "pruned": pruned,
+                          "orphaned_store": left}))
+        return 0
+    for a in actions:
+        out.ok(a)
+    for name in pruned:
+        out.ok("pruned %s" % _tilde(store.skill_store_dir(name)))
+    if left:
+        out.warn("%s left in place: %s — remove with `boost sync --prune`"
+                 % (_plural(len(left), "orphaned store dir"), ", ".join(left)))
+    if not actions and not pruned and not left:
+        out.ok("everything in sync")
+    return 0
+
+
+# ── update ───────────────────────────────────────────────────────────────
+
+def cmd_update(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(prog="boost update",
+                                 description="Sync taps or update installed skills")
+    ap.add_argument("tap", nargs="?", metavar="TAP", help="refresh only this tap")
+    ap.add_argument("--taps-only", action="store_true",
+                    help="refresh tap clones & catalogs without touching skills")
+    args = ap.parse_args(argv)
+    results = registry.update(args.tap or None)
+    if not results:
+        out.info("no taps configured — start with `boost tap --defaults`")
+        return 0
+    for tname, summary in results.items():
+        catalog.rebuild_tap(registry.get(tname))
+        out.ok("%s: %s" % (tname, summary))
+    journal.log("update", args.tap or "all")
+    if args.taps_only:
+        return 0
+
+    upgraded = 0
+    for name, lk in sorted(lockfile.installed().items()):
+        tapname = lk.get("tap")
+        if (lk.get("pinned") or lk.get("quarantined")
+                or tapname == "local" or tapname not in results):
+            continue
+        matches = [e for e in catalog.find(name) if e["tap"] == tapname]
+        if not matches:
+            out.warn("%s is no longer in tap %s — leaving as-is" % (name, tapname))
+            continue
+        entry = matches[0]
+        old_v = str(lk.get("version", "0.0.0"))
+        new_v = str(entry.get("version", "0.0.0"))
+        reason = "version" if util.semver_gt(new_v, old_v) else None
+        if reason is None:
+            head = gitutil.head_commit(registry.get(tapname).path)
+            if head and head != lk.get("commit"):
+                try:
+                    src = store.source_dir_for(entry)
+                except BoostError:
+                    continue
+                if util.sha256_dir(src) != lk.get("sha256"):
+                    reason = "content"
+        if reason is None:
+            continue
+        try:
+            store.install(entry, force=True)
+        except BoostError as err:
+            out.warn("%s: %s" % (name, err.message))
+            continue
+        if reason == "version":
+            out.ok("upgraded %s v%s → v%s" % (name, old_v, new_v))
+        else:
+            out.ok("refreshed %s v%s (source changed)" % (name, new_v))
+        upgraded += 1
+    if not upgraded:
+        out.ok("everything up to date")
+    return 0
+
+
+# ── reinstall ────────────────────────────────────────────────────────────
+
+def cmd_reinstall(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(prog="boost reinstall",
+                                 description="Reinstall a skill or all skills (force)")
+    ap.add_argument("names", nargs="*", metavar="NAME")
+    ap.add_argument("--all", action="store_true",
+                    help="reinstall every installed skill")
+    args = ap.parse_args(argv)
+    names = sorted(lockfile.installed()) if args.all else args.names
+    if not names:
+        raise BoostError("nothing to reinstall",
+                        hint="no skills installed yet — see `boost list`"
+                        if args.all else "name a skill or pass --all")
+    done, failed = 0, 0
+    for name in names:
+        lk = lockfile.get_skill(name)
+        if not lk:
+            if len(names) == 1:
+                raise BoostError("%s is not installed" % name,
+                                hint="see what is with `boost list`")
+            out.warn("%s is not installed — skipped" % name)
+            failed += 1
+            continue
+        if lk.get("tap") == "local":
+            src = Path(str(lk.get("source_dir") or ""))
+            if src.is_dir() and (src / "SKILL.md").exists():
+                store.install_from_path(src, name=name)
+                out.ok("reinstalled %s (local, from %s)" % (name, _tilde(src)))
+                done += 1
+            else:
+                out.warn("%s: local source %s is gone — skipped" % (name, _tilde(src)))
+                failed += 1
+            continue
+        matches = [e for e in catalog.find(name) if e["tap"] == lk.get("tap")]
+        if not matches:
+            out.warn("%s not found in tap %s — skipped (try `boost update`)"
+                     % (name, lk.get("tap")))
+            failed += 1
+            continue
+        try:
+            store.install(matches[0], force=True)
+        except BoostError as err:
+            out.warn("%s: %s" % (name, err.message))
+            failed += 1
+            continue
+        out.ok("reinstalled %s v%s" % (name, matches[0].get("version", "0.0.0")))
+        done += 1
+    out.info("Reinstalled %s" % _plural(done, "skill"))
+    return 1 if failed else 0
+
+
+# ── bundle ───────────────────────────────────────────────────────────────
+
+def cmd_bundle(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(prog="boost bundle",
+                                 description="Export/install skill sets via a Boostfile")
+    ap.add_argument("action", choices=("dump", "install"))
+    ap.add_argument("file", nargs="?", metavar="FILE",
+                    help="Boostfile (dump: default stdout; "
+                         "install: default ./Boostfile, '-' = stdin)")
+    args = ap.parse_args(argv)
+    if args.action == "dump":
+        return _bundle_dump(args.file)
+    return _bundle_install(args.file)
+
+
+def _bundle_dump(file: Optional[str]) -> int:
+    text = _boostfile_text(lockfile.installed())
+    if not file or file == "-":
+        print(text, end="")
+        return 0
+    dest = paths.expand(file)
+    try:
+        dest.write_text(text)
+    except OSError as e:
+        raise BoostError("cannot write %s: %s" % (_tilde(dest), e.strerror or e),
+                        hint="check the path exists and is writable")
+    n_taps = sum(1 for ln in text.splitlines() if ln.startswith("tap "))
+    n_skills = sum(1 for ln in text.splitlines() if ln.startswith("skill "))
+    out.ok("wrote %s (%s, %s)" % (_tilde(dest), _plural(n_taps, "tap"),
+                                  _plural(n_skills, "skill")))
+    return 0
+
+
+def _bundle_install(file: Optional[str]) -> int:
+    if file == "-":
+        text, label = sys.stdin.read(), "<stdin>"
+    else:
+        path = paths.expand(file or "./Boostfile")
+        if not path.exists():
+            raise BoostError("no Boostfile at %s" % _tilde(path),
+                            hint="create one with `boost bundle dump Boostfile`")
+        if path.is_dir():
+            raise BoostError("%s is a directory, not a Boostfile" % _tilde(path),
+                            hint="point at the Boostfile itself, "
+                                 "or use `boost import` for skill directories")
+        try:
+            text, label = path.read_text(), str(path)
+        except OSError as e:
+            raise BoostError("cannot read %s: %s" % (_tilde(path), e.strerror or e))
+    taps_added = installed_n = present = failed = 0
+    have_taps = {t.name for t in registry.list_taps()}
+    have_skills = set(lockfile.installed())
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        parts = line.split(None, 2)
+        if parts[0] == "tap" and len(parts) >= 2:
+            tname, turl = parts[1], parts[2] if len(parts) > 2 else ""
+            if tname in have_taps:
+                continue
+            try:
+                tap = registry.add(turl or tname)
+                catalog.rebuild_tap(tap)
+            except BoostError as err:
+                out.warn("tap %s failed: %s" % (tname, err.message))
+                failed += 1
+                continue
+            have_taps.add(tap.name)
+            taps_added += 1
+            out.ok("tapped %s" % tap.name)
+        elif parts[0] == "skill" and len(parts) >= 2:
+            tapq, _, rest = parts[1].rpartition(":")
+            sname, _, sver = rest.partition("@")
+            if sname in have_skills:
+                present += 1
+                continue
+            matches = catalog.find(sname, tap=tapq or None)
+            if not matches:
+                out.warn("%s not found%s — skipped"
+                         % (sname, (" in tap %s" % tapq) if tapq else ""))
+                failed += 1
+                continue
+            entry = matches[0]
+            if sver and str(entry.get("version")) != sver:
+                out.warn("%s: Boostfile wants @%s, tap has %s — installing that"
+                         % (sname, sver, entry.get("version")))
+            try:
+                store.install(entry)
+            except BoostError as err:
+                out.warn("%s: %s" % (sname, err.message))
+                failed += 1
+                continue
+            out.ok("installed %s v%s (%s)" % (sname, entry.get("version"),
+                                              entry["tap"]))
+            have_skills.add(sname)
+            installed_n += 1
+        else:
+            out.warn("line %d: unrecognised: %s" % (lineno, line))
+            failed += 1
+    journal.log("bundle-install", label, taps=taps_added, skills=installed_n)
+    summary = "Installed %s" % _plural(installed_n, "skill")
+    if taps_added:
+        summary += ", added %s" % _plural(taps_added, "tap")
+    if present:
+        summary += ", %d already present" % present
+    if failed:
+        summary += ", %d failed" % failed
+    out.info(summary)
+    return 1 if failed else 0
+
+
+# ── import ───────────────────────────────────────────────────────────────
+
+def cmd_import(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(
+        prog="boost import",
+        description="Import skills from a GitHub URL or local path")
+    ap.add_argument("source", metavar="URL_OR_PATH")
+    ap.add_argument("--name", metavar="N",
+                    help="skill to pick when several are found (or a rename)")
+    ap.add_argument("--all", action="store_true", help="import every skill found")
+    ap.add_argument("--agent", action="append", metavar="A",
+                    help="link only into this agent (repeatable)")
+    args = ap.parse_args(argv)
+    only = _check_agents(args.agent)
+    tmp = None
+    try:
+        if args.source.startswith(("http://", "https://", "git@", "ssh://")):
+            tmp = Path(tempfile.mkdtemp(prefix="boost-import-"))
+            root = tmp / "repo"
+            out.info("cloning %s …" % args.source)
+            gitutil.clone_shallow(args.source, root)
+        else:
+            root = paths.expand(args.source)
+            if not root.is_dir():
+                raise BoostError("no such directory: %s" % args.source,
+                                hint="pass a local path or a git URL")
+        return _import_root(root, args.name, args.all, only, args.source)
+    finally:
+        if tmp:
+            shutil.rmtree(tmp, ignore_errors=True)
+
+
+def _import_root(root: Path, name: Optional[str], do_all: bool,
+                 only: Optional[List[str]], display: str) -> int:
+    def one(skill_dir: Path, rename: Optional[str] = None) -> int:
+        res = store.install_from_path(skill_dir, name=rename, only_agents=only)
+        _report_result(res)
+        out.info("Imported %s; quality score %d/100" % (res.name, res.score))
+        return 0
+
+    if (root / "SKILL.md").exists():
+        return one(root, rename=name)
+    entries = catalog.scan_dir(root)
+    if not entries:
+        raise BoostError("no SKILL.md found under %s" % display)
+
+    def dir_of(e: dict) -> Path:
+        return root if e["rel_dir"] == "." else root / e["rel_dir"]
+
+    if len(entries) == 1:
+        return one(dir_of(entries[0]), rename=name)
+    if name and not do_all:
+        picks = [e for e in entries if e["name"] == name]
+        if not picks:
+            raise BoostError("no skill named %r in %s" % (name, display),
+                            hint="available: %s" % ", ".join(e["name"] for e in entries))
+        return one(dir_of(picks[0]))
+    if do_all:
+        for e in entries:
+            res = store.install_from_path(dir_of(e), only_agents=only)
+            out.ok("imported %s v%s (score %d/100)" % (res.name, e["version"],
+                                                       res.score))
+        out.info("Imported %s" % _plural(len(entries), "skill"))
+        return 0
+    out.heading("%d skills in %s" % (len(entries), display))
+    out.table([(e["name"], "v" + e["version"], (e["description"] or "")[:60])
+               for e in entries])
+    raise BoostError("multiple skills found — pick one or import all",
+                    hint="add `--name NAME` or `--all`")
+
+
+# ── migrate ──────────────────────────────────────────────────────────────
+
+def cmd_migrate(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(
+        prog="boost migrate",
+        description="Migrate skills between agents or from Skills CLI")
+    ap.add_argument("--from", dest="src", metavar="AGENT",
+                    help="agent migrating away from")
+    ap.add_argument("--to", dest="dst", metavar="AGENT",
+                    help="agent to link every installed skill into")
+    ap.add_argument("--from-skills-cli", action="store_true",
+                    help="import skills installed by the Skills CLI")
+    ap.add_argument("--path", metavar="DIR",
+                    help="Skills CLI directory (default ~/.skills)")
+    args = ap.parse_args(argv)
+
+    if args.from_skills_cli:
+        root = paths.expand(args.path) if args.path else paths.home() / ".skills"
+        if not root.is_dir():
+            out.info("nothing to migrate — %s does not exist" % _tilde(root))
+            return 0
+        entries = catalog.scan_dir(root)
+        if not entries:
+            out.info("no skills found under %s" % _tilde(root))
+            return 0
+        for e in entries:
+            d = root if e["rel_dir"] == "." else root / e["rel_dir"]
+            res = store.install_from_path(d)
+            out.ok("imported %s v%s" % (res.name, e["version"]))
+        out.info("Migrated %s from %s" % (_plural(len(entries), "skill"),
+                                          _tilde(root)))
+        return 0
+
+    if not (args.src and args.dst):
+        raise BoostError("nothing to do",
+                        hint="use `--from AGENT --to AGENT` or `--from-skills-cli`")
+    known = agents.known_agents()
+    for a in (args.src, args.dst):
+        if a not in known:
+            raise BoostError("unknown agent: %s" % a,
+                            hint="known agents: %s" % ", ".join(known))
+    if args.src == args.dst:
+        raise BoostError("--from and --to are the same agent")
+    if args.dst not in agents.enabled_agents():
+        raise BoostError("agent %s is disabled in config" % args.dst,
+                        hint="`boost config set agents.%s.enabled true`" % args.dst)
+    skills = sorted(lockfile.installed())
+    if not skills:
+        out.info("no skills installed — nothing to migrate")
+        return 0
+    linked = []
+    for name in skills:
+        res = store.link_agents(name, only=[args.dst])
+        if args.dst in res.linked:
+            out.ok("linked %s → %s" % (name, args.dst))
+            linked.append(name)
+        for pth in res.conflicts:
+            out.warn("%s: %s exists and is not managed by boost" % (name, _tilde(pth)))
+    lock = lockfile.read()
+    changed = False
+    for name in linked:
+        ent = lock["skills"].get(name)
+        if ent is not None and args.dst not in ent.get("agents", []):
+            ent["agents"] = sorted(set(ent.get("agents", [])) | {args.dst})
+            changed = True
+    if changed:
+        lockfile.write(lock)
+    journal.log("migrate", "%s→%s" % (args.src, args.dst), skills=len(linked))
+    out.info("Migrated %s to %s" % (_plural(len(linked), "skill"),
+                                    agents.display_name(args.dst)))
+    return 0
+
+
+# ── pin / unpin ──────────────────────────────────────────────────────────
+
+def cmd_pin(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(prog="boost pin",
+                                 description="Pin a skill to its current version")
+    ap.add_argument("name", metavar="NAME")
+    args = ap.parse_args(argv)
+    return _set_pin(args.name, True)
+
+
+def cmd_unpin(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(prog="boost unpin",
+                                 description="Allow a pinned skill to update again")
+    ap.add_argument("name", metavar="NAME")
+    args = ap.parse_args(argv)
+    return _set_pin(args.name, False)
+
+
+def _set_pin(name: str, pinned: bool) -> int:
+    entry = lockfile.get_skill(name)
+    if not entry:
+        raise BoostError("%s is not installed" % name,
+                        hint="see what is with `boost list`")
+    version = entry.get("version", "0.0.0")
+    if bool(entry.get("pinned")) == pinned:
+        out.info("%s is already %s" % (name, "pinned at v%s" % version
+                                       if pinned else "unpinned"))
+        return 0
+    entry["pinned"] = pinned
+    lockfile.set_skill(name, entry)
+    journal.log("pin" if pinned else "unpin", name)
+    if pinned:
+        out.ok("pinned %s at v%s — `boost update` will skip it" % (name, version))
+    else:
+        out.ok("unpinned %s (v%s) — updates apply again" % (name, version))
+    return 0
+
+
+# ── snapshot ─────────────────────────────────────────────────────────────
+
+def cmd_snapshot(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(prog="boost snapshot",
+                                 description="Save & restore whole skill environments")
+    ap.add_argument("action", choices=("save", "list", "restore"))
+    ap.add_argument("arg", nargs="?", metavar="LABEL|ID",
+                    help="label for save, snapshot id for restore")
+    ap.add_argument("--json", action="store_true",
+                    help="machine-readable output (list)")
+    args = ap.parse_args(argv)
+    if args.action == "save":
+        return _snapshot_save(args.arg)
+    if args.action == "list":
+        return _snapshot_list(args.json)
+    if not args.arg:
+        raise BoostError("restore needs a snapshot id",
+                        hint="see `boost snapshot list`")
+    return _snapshot_restore(args.arg)
+
+
+def _snapshot_save(label: Optional[str]) -> int:
+    paths.ensure_dirs()
+    base = "snap-" + datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S")
+    snap_id, serial = base, 1
+    while (paths.snapshots_dir() / (snap_id + ".tar.gz")).exists():
+        serial += 1
+        snap_id = "%s-%d" % (base, serial)
+    tar_path = paths.snapshots_dir() / (snap_id + ".tar.gz")
+    with tarfile.open(str(tar_path), "w:gz") as tf:
+        for child in sorted(paths.store_dir().iterdir()):
+            tf.add(str(child), arcname=child.name)
+    skill_count = len(lockfile.installed())
+    manifest = {"id": snap_id, "label": label or "", "created": util.now_iso(),
+                "skills": skill_count}
+    (paths.snapshots_dir() / (snap_id + ".json")).write_text(
+        json.dumps(manifest, indent=2) + "\n")
+    journal.log("snapshot", snap_id, label=label)
+    out.ok("saved %s (%s, %s)" % (snap_id, _plural(skill_count, "skill"),
+                                  util.human_size(tar_path.stat().st_size)))
+    out.info("restore with `boost snapshot restore %s`" % snap_id)
+    return 0
+
+
+def _snapshot_list(as_json: bool) -> int:
+    paths.ensure_dirs()
+    snaps = []
+    # newest first; file mtime keeps same-second saves (snap-...-2) in order
+    for tar_path in sorted(paths.snapshots_dir().glob("snap-*.tar.gz"),
+                           key=lambda p: (p.stat().st_mtime, p.name),
+                           reverse=True):
+        snap_id = tar_path.name[:-len(".tar.gz")]
+        side = tar_path.parent / (snap_id + ".json")
+        meta = {}
+        if side.exists():
+            try:
+                meta = json.loads(side.read_text())
+            except (json.JSONDecodeError, OSError):
+                meta = {}
+        snaps.append({"id": snap_id, "created": meta.get("created", ""),
+                      "label": meta.get("label", ""),
+                      "skills": meta.get("skills", "?"),
+                      "size": tar_path.stat().st_size})
+    if as_json:
+        print(json.dumps(snaps, indent=2))
+        return 0
+    if not snaps:
+        out.info("no snapshots yet — create one with `boost snapshot save`")
+        return 0
+    out.table([(s["id"], util.rel_time(s["created"]) if s["created"] else "?",
+                s["label"] or "—", s["skills"], util.human_size(s["size"]))
+               for s in snaps],
+              headers=("ID", "WHEN", "LABEL", "SKILLS", "SIZE"))
+    return 0
+
+
+def _snapshot_restore(snap_id: str) -> int:
+    if not snap_id.startswith("snap-"):
+        snap_id = "snap-" + snap_id
+    tar_path = paths.snapshots_dir() / (snap_id + ".tar.gz")
+    if not tar_path.exists():
+        raise BoostError("no snapshot %s" % snap_id,
+                        hint="see `boost snapshot list`")
+    root = paths.store_dir()
+    if not out.confirm("Restore %s? This replaces everything in %s"
+                       % (snap_id, _tilde(root))):
+        out.info("cancelled")
+        return 0
+    paths.ensure_dirs()
+    # Read the whole archive BEFORE touching the store, so a corrupt
+    # snapshot can never leave us with an emptied environment.
+    try:
+        tf = tarfile.open(str(tar_path), "r:gz")
+    except (tarfile.TarError, OSError, EOFError) as e:
+        raise BoostError("snapshot %s is unreadable: %s" % (snap_id, e),
+                        hint="the store was left untouched — "
+                             "see `boost snapshot list` for other snapshots")
+    with tf:
+        try:
+            members = tf.getmembers()
+        except (tarfile.TarError, OSError, EOFError) as e:
+            raise BoostError("snapshot %s is corrupt: %s" % (snap_id, e),
+                            hint="the store was left untouched — "
+                                 "see `boost snapshot list` for other snapshots")
+        for child in root.iterdir():
+            if child.is_dir() and not child.is_symlink():
+                shutil.rmtree(child)
+            else:
+                child.unlink()
+        try:
+            tf.extractall(str(root), members=members, filter="data")
+        except TypeError:  # Python < 3.12
+            tf.extractall(str(root), members=members)
+    for action in store.sync_apply(store.sync_plan()):
+        out.ok(action)
+    journal.log("snapshot-restore", snap_id)
+    out.ok("restored %s (%s)" % (snap_id,
+                                 _plural(len(lockfile.installed()), "skill")))
+    return 0
+
+
+# ── export ───────────────────────────────────────────────────────────────
+
+def cmd_export(argv: List[str]) -> int:
+    ap = argparse.ArgumentParser(
+        prog="boost export",
+        description="Package skills as shareable zip/tar archives")
+    ap.add_argument("names", nargs="*", metavar="NAME",
+                    help="skills to export (default: all installed)")
+    ap.add_argument("-o", "--out", metavar="OUT", help="output archive path")
+    ap.add_argument("--zip", action="store_true",
+                    help="build a .zip instead of .tar.gz")
+    args = ap.parse_args(argv)
+    installed = lockfile.installed()
+    names = args.names or sorted(installed)
+    if not names:
+        raise BoostError("no skills installed to export",
+                        hint="install some with `boost install`")
+    chosen = {}
+    for name in names:
+        if name not in installed:
+            raise BoostError("%s is not installed" % name,
+                            hint="see what is with `boost list`")
+        if not store.skill_store_dir(name).is_dir():
+            raise BoostError("store dir for %s is missing" % name,
+                            hint="repair with `boost sync`")
+        chosen[name] = installed[name]
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%d")
+    ext = ".zip" if args.zip else ".tar.gz"
+    dest = paths.expand(args.out) if args.out else Path(
+        "boost-skills-%s%s" % (stamp, ext))
+    manifest = _boostfile_text(chosen, via="boost export")
+    try:
+        if args.zip:
+            with zipfile.ZipFile(str(dest), "w", zipfile.ZIP_DEFLATED) as zf:
+                zf.writestr("Boostfile", manifest)
+                for name in chosen:
+                    sdir = store.skill_store_dir(name)
+                    for f in sorted(p for p in sdir.rglob("*") if p.is_file()):
+                        zf.write(str(f), arcname="%s/%s" % (name, f.relative_to(sdir)))
+        else:
+            with tarfile.open(str(dest), "w:gz") as tf:
+                data = manifest.encode()
+                ti = tarfile.TarInfo("Boostfile")
+                ti.size = len(data)
+                ti.mtime = int(datetime.now(timezone.utc).timestamp())
+                ti.mode = 0o644
+                tf.addfile(ti, io.BytesIO(data))
+                for name in chosen:
+                    tf.add(str(store.skill_store_dir(name)), arcname=name)
+    except OSError as e:
+        raise BoostError("cannot write %s: %s" % (_tilde(dest), e.strerror or e),
+                        hint="check the output path exists and is writable")
+    out.ok("exported %s → %s (%s)" % (_plural(len(chosen), "skill"),
+                                      _tilde(dest.resolve()),
+                                      util.human_size(dest.stat().st_size)))
+    return 0