boost-skill-cli 1.0.449__tar.gz → 1.0.451__tar.gz

{boost_skill_cli-1.0.449 → boost_skill_cli-1.0.451}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -33,6 +33,7 @@ gitignored
 GitOps
 glassmorphic
 Grafana
+gzipped
 hardcode
 Helm
 hotspots
@@ -55,6 +56,7 @@ onboards
 OpenShift
 overclaiming
 Pinecone
+pipx
 PrestaShop
 Pulumi
 pytest
@@ -65,12 +67,12 @@ reindex
 repo
 repo's
 repos
-rerank
 Rerank
+rerank
 reranking
 ruleset
-rulesets
 Rulesets
+rulesets
 sandboxed
 sandboxing
 Shopify
@@ -98,6 +100,7 @@ unlinking
 unregister
 unstaged
 untap
+uv
 Vaadin
 vendored
 vendoring

{boost_skill_cli-1.0.449 → boost_skill_cli-1.0.451}/CLAUDE.md

@@ -233,7 +233,7 @@ for both — edit items, run `build_roadmap.py`, never touch the HTML by hand.
 ## Architecture
 
 **CLI dispatch.** `boost_cli/cli.py` holds `COMMANDS`, the single
-source-of-truth list of `(name, group, module, summary)` for all 78 commands.
+source-of-truth list of `(name, group, module, summary)` for all 79 commands.
 Each command is implemented as `def cmd_<name_with_underscores>(argv) -> int`
 inside `boost_cli/commands/<module>.py`, and `_dispatch` imports that module
 lazily on invocation — so `boost --help` stays instant and command modules are

{boost_skill_cli-1.0.449 → boost_skill_cli-1.0.451}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.449
+Version: 1.0.451
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -854,6 +854,31 @@ boost tap --catalog --category rag            # RAG / vector-search skill packs
 boost tap --catalog --category security       # filter by category
 ```
 
+### Share the catalogue instead of re-tapping it
+
+Tapping is the slowest thing a new install does, and the expensive artifact is
+not the valuable one. On a machine with **458 registries** tapped, the shallow
+clones are **12 GB** — while the catalogue they produce, the JSON boost actually
+searches, is **10.9 MB** gzipped. So hand someone the catalogue:
+
+```bash
+boost catalog --export catalogue.tgz    # 458 taps · 59,972 entries · 10.9 MB
+boost catalog --show catalogue.tgz      # what is in it, without importing
+boost catalog --import catalogue.tgz    # on the other machine
+```
+
+Measured on a fresh `HOME`: import takes **0.3 s**, `boost reindex` a further
+**3.8 s**, and `boost search` then returns real hits over all 59,972 items with
+**zero repositories cloned**. `install` still clones — but only the one registry
+the skill you chose actually lives in, instead of all 458 up front.
+
+Bundles carry catalogue JSON and nothing else. The derived indexes are excluded
+(they are 3.8 GB of a 3.9 GB cache directory and rebuild in seconds), and
+vectors are excluded because they are only valid inside the embedding space that
+made them — `boost reindex --export-shard` is the path for those, with the
+provenance checks a bundle deliberately does not try to carry. Import **merges**,
+so it never silently drops taps the receiving machine already had.
+
 boost indexes three item kinds out of the same registries: `SKILL.md` **skills**,
 `.mdc`/`.cursorrules`/`.windsurfrules` **rules**, and command/agent **workflows**
 (Markdown under `commands/`·`agents/`·`workflows/`, or carrying subagent
@@ -946,7 +971,7 @@ boost doctor               # sanity check: broken links, lock drift, stale taps
 boost bundle dump > Boostfile     # everyone else runs: boost bundle install
 ```
 
-## 78 commands, organized into 8 groups
+## 79 commands, organized into 8 groups
 
 `boost --help` prints the full grouped command list; for a visual tour see
 [`docs/index.html`](docs/index.html), and for every flag of every command see
@@ -1160,8 +1185,8 @@ Four layers, all enforced (`make check` runs the full set; CI runs the same thin
 
 | Layer | What it does | Gate |
 |---|---|---|
-| `make test` | pytest across `tests/unit/` (every core module) and `tests/functional/` (drives all 78 commands in-process against sandboxed homes) | **≥80% line coverage** of `boost_cli` (`fail_under` in pyproject.toml) |
-| `make smoke` | `tests/smoke.sh` — 174 checks run through the actual `./boost` shim (`--online` also hits real registries) | all pass |
+| `make test` | pytest across `tests/unit/` (every core module) and `tests/functional/` (drives all 79 commands in-process against sandboxed homes) | **≥80% line coverage** of `boost_cli` (`fail_under` in pyproject.toml) |
+| `make smoke` | `tests/smoke.sh` — 175 checks run through the actual `./boost` shim (`--online` also hits real registries) | all pass |
 | `make mutation` | [mutmut] mutates `boost_cli/core` (~9,900 mutants) and reruns the unit suite against each one | **≥80% killed** (`scripts/mutation_gate.py`) |
 | `make evals` | scores the search ranker on a graded golden set — recall@5/@10, MRR, nDCG@5/@10 | **metric floors + no statistically significant regression** (`scripts/eval_gate.py`) |
 

{boost_skill_cli-1.0.449 → boost_skill_cli-1.0.451}/README.md

@@ -136,6 +136,31 @@ boost tap --catalog --category rag            # RAG / vector-search skill packs
 boost tap --catalog --category security       # filter by category
 ```
 
+### Share the catalogue instead of re-tapping it
+
+Tapping is the slowest thing a new install does, and the expensive artifact is
+not the valuable one. On a machine with **458 registries** tapped, the shallow
+clones are **12 GB** — while the catalogue they produce, the JSON boost actually
+searches, is **10.9 MB** gzipped. So hand someone the catalogue:
+
+```bash
+boost catalog --export catalogue.tgz    # 458 taps · 59,972 entries · 10.9 MB
+boost catalog --show catalogue.tgz      # what is in it, without importing
+boost catalog --import catalogue.tgz    # on the other machine
+```
+
+Measured on a fresh `HOME`: import takes **0.3 s**, `boost reindex` a further
+**3.8 s**, and `boost search` then returns real hits over all 59,972 items with
+**zero repositories cloned**. `install` still clones — but only the one registry
+the skill you chose actually lives in, instead of all 458 up front.
+
+Bundles carry catalogue JSON and nothing else. The derived indexes are excluded
+(they are 3.8 GB of a 3.9 GB cache directory and rebuild in seconds), and
+vectors are excluded because they are only valid inside the embedding space that
+made them — `boost reindex --export-shard` is the path for those, with the
+provenance checks a bundle deliberately does not try to carry. Import **merges**,
+so it never silently drops taps the receiving machine already had.
+
 boost indexes three item kinds out of the same registries: `SKILL.md` **skills**,
 `.mdc`/`.cursorrules`/`.windsurfrules` **rules**, and command/agent **workflows**
 (Markdown under `commands/`·`agents/`·`workflows/`, or carrying subagent
@@ -228,7 +253,7 @@ boost doctor               # sanity check: broken links, lock drift, stale taps
 boost bundle dump > Boostfile     # everyone else runs: boost bundle install
 ```
 
-## 78 commands, organized into 8 groups
+## 79 commands, organized into 8 groups
 
 `boost --help` prints the full grouped command list; for a visual tour see
 [`docs/index.html`](docs/index.html), and for every flag of every command see
@@ -442,8 +467,8 @@ Four layers, all enforced (`make check` runs the full set; CI runs the same thin
 
 | Layer | What it does | Gate |
 |---|---|---|
-| `make test` | pytest across `tests/unit/` (every core module) and `tests/functional/` (drives all 78 commands in-process against sandboxed homes) | **≥80% line coverage** of `boost_cli` (`fail_under` in pyproject.toml) |
-| `make smoke` | `tests/smoke.sh` — 174 checks run through the actual `./boost` shim (`--online` also hits real registries) | all pass |
+| `make test` | pytest across `tests/unit/` (every core module) and `tests/functional/` (drives all 79 commands in-process against sandboxed homes) | **≥80% line coverage** of `boost_cli` (`fail_under` in pyproject.toml) |
+| `make smoke` | `tests/smoke.sh` — 175 checks run through the actual `./boost` shim (`--online` also hits real registries) | all pass |
 | `make mutation` | [mutmut] mutates `boost_cli/core` (~9,900 mutants) and reruns the unit suite against each one | **≥80% killed** (`scripts/mutation_gate.py`) |
 | `make evals` | scores the search ranker on a graded golden set — recall@5/@10, MRR, nDCG@5/@10 | **metric floors + no statistically significant regression** (`scripts/eval_gate.py`) |
 

{boost_skill_cli-1.0.449 → boost_skill_cli-1.0.451}/boost_cli/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.449'
-__version_tuple__ = version_tuple = (1, 0, 449)
+__version__ = version = '1.0.451'
+__version_tuple__ = version_tuple = (1, 0, 451)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.449 → boost_skill_cli-1.0.451}/boost_cli/cli.py

@@ -87,6 +87,7 @@ COMMANDS = [
     ("untap",       "tap", "taps", "Remove a registry tap"),
     ("taps",        "tap", "taps", "List all configured registry taps"),
     ("outdated",    "tap", "taps", "Show skills with available updates"),
+    ("catalog",     "tap", "taps", "Share the tapped catalogue so others skip the clone"),
     # Intelligence (8)
     ("chat",        "ai", "intelligence", "Ask about skills in plain language (RAG-grounded)"),
     ("distill",     "ai", "intelligence", "Merge multiple skills into one deduplicated skill"),

{boost_skill_cli-1.0.449 → boost_skill_cli-1.0.451}/boost_cli/commands/configuration.py

@@ -1498,12 +1498,40 @@ def _self_update_package(method: str, dry_run: bool) -> int:
     journal.log("self-update", new or old, previous=old, method=method)
     if new and new != old:
         out.ok("boost v%s → v%s" % (old, new))
-    elif new:
-        out.ok("already up to date (v%s)" % new)
-    else:
+        return 0
+    if not new:
         # The upgrade succeeded but we never saw a version — say exactly that
         # rather than claim one.
         out.ok("upgraded via %s; run `boost --version` to confirm" % method)
+        return 0
+    return _report_no_op(method, new)
+
+
+def _report_no_op(method: str, here: str) -> int:
+    """Explain a manager that exited 0 without moving the version.
+
+    "The version did not change" is not "you are on the latest release", and
+    boost used to print the second on evidence for only the first. When the
+    index pip resolved against was stale, that told a user who was a release
+    behind that they were current — so ask PyPI which it is, and let the three
+    possible answers say three different things.
+    """
+    latest = selfupdate.latest_version()
+    if latest is None:
+        # Offline. Report only what was observed; claiming "up to date" here is
+        # the same unearned claim with a different cause.
+        out.ok("boost is unchanged (v%s); could not reach PyPI to confirm it is "
+               "the latest" % here)
+        return 0
+    if selfupdate.is_behind(here, latest):
+        raise BoostError(
+            "%s exited 0 but boost is still v%s — PyPI has v%s"
+            % (method, here, latest),
+            hint="no newer candidate was offered: either the index it resolved "
+                 "against was stale, or this environment's python is too old "
+                 "for the new wheel. Pin it with `%s`"
+                 % " ".join(selfupdate.force_command(method, latest)))
+    out.ok("already up to date (v%s)" % here)
     return 0
 
 

{boost_skill_cli-1.0.449 → boost_skill_cli-1.0.451}/boost_cli/commands/taps.py

@@ -5,6 +5,7 @@ import argparse
 import hashlib
 import json
 from contextlib import suppress
+from pathlib import Path
 
 from .. import cliparse, spin
 from ..core import (
@@ -317,3 +318,66 @@ def cmd_outdated(argv) -> int:
     out.dim("%d outdated · `boost update` upgrades (pinned items stay put)"
             % len(results))
     return 0
+
+
+def cmd_catalog(argv) -> int:
+    """boost catalog --export FILE | --import FILE [--json]"""
+    p = cliparse.parser(
+        prog="boost catalog",
+        description="Share the tapped catalogue so others skip the clone")
+    mode = p.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--export", metavar="FILE",
+                      help="write every tapped registry's catalogue to FILE")
+    mode.add_argument("--import", metavar="FILE", dest="import_",
+                      help="merge a catalogue bundle into this machine")
+    mode.add_argument("--show", metavar="FILE",
+                      help="describe a bundle without importing it")
+    p.add_argument("--json", action="store_true", dest="as_json",
+                   help="machine-readable output")
+    args = p.parse_args(argv)
+
+    from ..core import catalogbundle
+
+    if args.show:
+        manifest = catalogbundle.read_manifest(Path(args.show))
+        if args.as_json:
+            print(json.dumps(manifest, indent=2))
+            return 0
+        out.heading("catalogue bundle %s" % args.show)
+        out.info("built %s · %d taps · %s entries"
+                 % (manifest.get("generated", "?"),
+                    len(manifest.get("taps") or []),
+                    "{:,}".format(int(manifest.get("entries") or 0))))
+        rows = [(t.get("name", "?"), str(t.get("entries", "?")),
+                 (t.get("commit") or "")[:7])
+                for t in (manifest.get("taps") or [])[:20]]
+        if rows:
+            out.table(rows, headers=("TAP", "ENTRIES", "COMMIT"))
+        return 0
+
+    if args.export:
+        stats = catalogbundle.export_bundle(Path(args.export))
+        if args.as_json:
+            print(json.dumps(stats, indent=2))
+            return 0
+        out.ok("packed %d taps · %s entries · %.1f MB → %s"
+               % (stats["taps"], "{:,}".format(stats["entries"]),
+                  stats["bytes"] / 1e6, stats["path"]))
+        if stats["skipped"]:
+            # Configured but not yet built. Named rather than counted: the
+            # reader needs to know WHICH registry the receiver will not get.
+            out.warn("skipped %d tap(s) with no built catalogue: %s"
+                     % (len(stats["skipped"]), ", ".join(stats["skipped"][:5])))
+        out.dim("the receiver runs `boost catalog --import <file>` — no clone, "
+                "no re-tap")
+        return 0
+
+    stats = catalogbundle.import_bundle(Path(args.import_))
+    if args.as_json:
+        print(json.dumps(stats, indent=2))
+        return 0
+    out.ok("imported %d catalogue file(s) · %s entries · %d new tap(s)"
+           % (stats["files"], "{:,}".format(stats["entries"]), stats["added"]))
+    out.dim("`boost search` works now; `boost install` clones just the one "
+            "registry it needs")
+    return 0

boost_skill_cli-1.0.451/boost_cli/core/catalogbundle.py

@@ -0,0 +1,265 @@
+"""A portable catalogue bundle: everything `boost tap` produces, minus the clone.
+
+WHY THIS EXISTS. `boost tap --defaults` is the slowest thing a new install does,
+and almost none of the cost is the part anyone needs. Measured on a real
+machine with **459 registries tapped**: the shallow clones are **12 GB**, while
+the catalogue they produce — the JSON boost actually searches — is **101.1 MB**,
+and **11.1 MB** gzipped. Search works from that catalogue with no clone present
+at all.
+
+So the expensive artifact is not the valuable one, and the valuable one fits in
+an email. This module packs it.
+
+WHAT IS DELIBERATELY NOT IN IT.
+
+* The **derived indexes**. `rag_index.json`, `rag_postings.sqlite` and
+  `rag_vectors.sqlite` are 3.8 GB of that machine's 3.9 GB cache directory, and
+  they rebuild from the catalogue in seconds. Vectors additionally are only
+  meaningful inside the embedding space that produced them, which is why
+  `dense.export_shard` carries provider/model/dim/commit and `import_shard`
+  refuses a mismatch. This format carries none of that and must not pretend to:
+  shards are the reviewed path for vectors.
+* The **repositories**. A bundle makes a catalogue searchable, not installable —
+  `install` copies files out of a clone. Every tap's URL rides in the manifest
+  precisely so the receiving machine can clone the one repo it ends up wanting,
+  instead of all 459 up front.
+
+The archive is a gzipped tar of `manifest.json` plus `catalog/<safe_name>.json`,
+one per tap, byte-identical to what `catalog.build_cache` wrote.
+
+SECURITY. A bundle is a file people send each other, which makes it untrusted
+input in the most ordinary way there is, and tar member names are the classic
+path-traversal vector. Extraction here never lets the archive choose a
+destination: member names are validated, then the bytes are written to a path
+this module builds from the basename. See `_safe_members`.
+"""
+from __future__ import annotations
+
+import json
+import tarfile
+import time
+from pathlib import Path
+
+from ..errors import BoostError
+from . import config, paths, registry
+
+#: Bump when the layout changes incompatibly. An importer that cannot say what
+#: it is looking at cannot refuse anything.
+BUNDLE_FORMAT = 1
+
+MANIFEST_NAME = "manifest.json"
+#: Every catalogue file lives under this prefix; anything else is refused.
+CATALOG_PREFIX = "catalog/"
+
+#: Caps, so a hostile archive cannot exhaust the disk. Both are generous
+#: against real data — the 459-tap export is 460 members and its largest
+#: catalogue file is 14 MB — and both are monkeypatched low in the tests,
+#: because a limit nothing ever reaches is a limit nothing has tested.
+MAX_MEMBERS = 5000
+MAX_MEMBER_BYTES = 256 * 1024 * 1024
+
+def export_bundle(dest: Path) -> dict:
+    """Pack every tapped registry's catalogue into ``dest``. Returns stats.
+
+    Driven by the **tap list**, not by a scan of the cache directory, and that
+    is what keeps the derived indexes out rather than any filename filter: a
+    file only becomes a candidate by being named ``<safe_name>.json`` for a
+    configured tap, so ``rag_vectors.sqlite`` is never considered in the first
+    place. It also means a stale catalogue left behind by an untapped registry
+    is not exported. An earlier revision carried an ``_is_catalogue_file``
+    predicate for this and never called it — dead code that made the
+    accompanying test pass for a reason that had nothing to do with the filter.
+
+    A configured tap with no cache file yet is **skipped, not fatal**: taps are
+    built one at a time, and refusing to export the other 458 because one is
+    mid-build would make this unusable exactly when it is most wanted. The
+    skipped names come back in the stats so the caller can say so.
+
+    Exporting nothing raises instead, because an empty bundle is
+    indistinguishable from a working one until someone imports it.
+    """
+    dest = Path(dest)
+    taps = registry.list_taps()
+    packed: list[dict] = []
+    skipped: list[str] = []
+    entries = 0
+
+    for tap in taps:
+        cache_file = paths.cache_dir() / ("%s.json" % tap.safe_name)
+        if not cache_file.is_file():
+            skipped.append(tap.name)
+            continue
+        try:
+            data = json.loads(cache_file.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            skipped.append(tap.name)
+            continue
+        count = len(data.get("skills") or [])
+        entries += count
+        packed.append({"name": tap.name, "url": tap.url,
+                       "curated": tap.curated,
+                       "commit": str(data.get("commit") or ""),
+                       "entries": count,
+                       "file": "%s.json" % tap.safe_name})
+
+    if not packed:
+        raise BoostError(
+            "nothing to export — no tapped registry has a built catalogue",
+            hint="tap a registry first, e.g. `boost tap --defaults`")
+
+    manifest = {
+        "format": BUNDLE_FORMAT,
+        "generated": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "taps": packed,
+        "entries": entries,
+    }
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with tarfile.open(dest, "w:gz") as tar:
+            _add_bytes(tar, MANIFEST_NAME,
+                       json.dumps(manifest, indent=1).encode("utf-8"))
+            for row in packed:
+                src = paths.cache_dir() / row["file"]
+                tar.add(str(src), arcname=CATALOG_PREFIX + row["file"])
+    except OSError as exc:
+        raise BoostError("cannot write bundle %s: %s" % (dest, exc)) from exc
+
+    return {"path": str(dest), "taps": len(packed), "entries": entries,
+            "skipped": skipped, "bytes": dest.stat().st_size}
+
+
+def _add_bytes(tar: tarfile.TarFile, name: str, data: bytes) -> None:
+    """Add an in-memory file to ``tar`` (used for the manifest)."""
+    import io
+    info = tarfile.TarInfo(name)
+    info.size = len(data)
+    info.mtime = 0          # reproducible: same catalogue, same bytes
+    tar.addfile(info, io.BytesIO(data))
+
+
+def read_manifest(src: Path) -> dict:
+    """The manifest of ``src``, without extracting anything else."""
+    src = Path(src)
+    if not src.is_file():
+        raise BoostError("no such bundle: %s" % src)
+    try:
+        with tarfile.open(src, "r:gz") as tar:
+            member = tar.getmember(MANIFEST_NAME)
+            if not member.isfile():
+                raise BoostError("bundle manifest is not a file: %s" % src)
+            handle = tar.extractfile(member)
+            if handle is None:
+                raise BoostError("bundle manifest is unreadable: %s" % src)
+            return json.loads(handle.read().decode("utf-8"))
+    except KeyError as exc:
+        raise BoostError(
+            "%s is not a boost catalogue bundle (no %s)" % (src, MANIFEST_NAME),
+            hint="create one with `boost catalog --export <file>`") from exc
+    except (tarfile.TarError, OSError) as exc:
+        raise BoostError("cannot read bundle %s: %s" % (src, exc)) from exc
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise BoostError("bundle manifest is malformed: %s" % exc) from exc
+
+
+def _safe_members(tar: tarfile.TarFile) -> list[tarfile.TarInfo]:
+    """The catalogue members of ``tar``, or raise naming what was rejected.
+
+    The archive never chooses a destination. A member is accepted only when it
+    is a regular file directly under ``catalog/`` whose name is a plain
+    basename — no separators, no ``..``, no leading ``/``, no symlink or device
+    entry — and the caller then writes it to a path built from that basename.
+    Validating the name and *also* discarding it is deliberate: a check that
+    feeds its input forward is one refactor away from being decorative.
+    """
+    members = tar.getmembers()
+    if len(members) > MAX_MEMBERS:
+        raise BoostError(
+            "bundle has %d members, over the %d cap"
+            % (len(members), MAX_MEMBERS),
+            hint="this is not a catalogue export — check where it came from")
+
+    picked: list[tarfile.TarInfo] = []
+    for member in members:
+        if member.name == MANIFEST_NAME:
+            continue
+        if not member.isfile():
+            # Symlinks and hardlinks are how an archive writes outside its own
+            # tree without any name containing "..".
+            raise BoostError(
+                "bundle contains a non-regular entry: %s" % member.name,
+                hint="a catalogue bundle holds only JSON files")
+        if not member.name.startswith(CATALOG_PREFIX):
+            raise BoostError(
+                "bundle contains an entry outside %s: %s"
+                % (CATALOG_PREFIX, member.name))
+        leaf = member.name[len(CATALOG_PREFIX):]
+        if (not leaf or leaf != Path(leaf).name or leaf.startswith(".")
+                or "/" in leaf or "\\" in leaf or not leaf.endswith(".json")):
+            raise BoostError(
+                "bundle contains an unsafe member name: %s" % member.name)
+        if member.size > MAX_MEMBER_BYTES:
+            raise BoostError(
+                "bundle member %s is %d bytes, over the %d cap"
+                % (member.name, member.size, MAX_MEMBER_BYTES))
+        picked.append(member)
+    return picked
+
+
+def import_bundle(src: Path) -> dict:
+    """Restore a catalogue bundle into this machine. Returns stats.
+
+    **Merges, never replaces.** The receiving machine may already have taps of
+    its own, and silently dropping them would be a worse outcome than the slow
+    tap this feature exists to avoid. A tap already configured keeps its
+    existing entry; its catalogue file is overwritten, which is the point.
+    """
+    src = Path(src)
+    manifest = read_manifest(src)
+
+    fmt = manifest.get("format")
+    if fmt != BUNDLE_FORMAT:
+        raise BoostError(
+            "bundle format %r is not supported (this boost reads %d)"
+            % (fmt, BUNDLE_FORMAT),
+            hint="upgrade boost, or re-export the bundle with this version")
+
+    paths.ensure_dirs()
+    written = 0
+    try:
+        with tarfile.open(src, "r:gz") as tar:
+            members = _safe_members(tar)
+            for member in members:
+                handle = tar.extractfile(member)
+                if handle is None:
+                    continue
+                leaf = Path(member.name).name
+                # The destination is built here, from the basename, so the
+                # archive cannot influence it even if a check above is wrong.
+                target = paths.cache_dir() / leaf
+                target.write_bytes(handle.read(MAX_MEMBER_BYTES + 1))
+                written += 1
+    except (tarfile.TarError, OSError) as exc:
+        raise BoostError("cannot read bundle %s: %s" % (src, exc)) from exc
+
+    cfg = config.load()
+    existing = cfg.get("taps") or []
+    if not isinstance(existing, list):
+        existing = []
+    known = {t.get("name") for t in existing if isinstance(t, dict)}
+    added = 0
+    for row in manifest.get("taps") or []:
+        name = row.get("name")
+        if not name or name in known:
+            continue
+        existing.append({"name": name, "url": row.get("url", ""),
+                         "curated": bool(row.get("curated"))})
+        known.add(name)
+        added += 1
+    cfg["taps"] = existing
+    config.save(cfg)
+
+    return {"path": str(src), "taps": len(manifest.get("taps") or []),
+            "added": added, "files": written,
+            "entries": int(manifest.get("entries") or 0),
+            "generated": manifest.get("generated", "")}