boost-skill-cli 1.0.206__tar.gz → 1.0.208__tar.gz

{boost_skill_cli-1.0.206 → boost_skill_cli-1.0.208}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -56,6 +56,7 @@ tempdir
 toggleable
 Tokenization
 tokenization
+toolchain
 toolkits
 traceback
 tracebacks

{boost_skill_cli-1.0.206 → boost_skill_cli-1.0.208}/CONTRIBUTING.md

@@ -7,12 +7,31 @@ so contributing is mostly about keeping the quality gates green.
 
 ```bash
 git clone https://github.com/jonnyeclectic/boost && cd boost
-make venv          # pytest, coverage, mutmut, ruff, mypy — runtime stays stdlib-only
+make venv          # every gate tool, hash-pinned — runtime stays stdlib-only
 ```
 
 Every test runs against a throwaway `$HOME`, so nothing touches your real
 agent configs.
 
+### The toolchain is hash-pinned
+
+`make venv` and every CI job install from the generated
+[`requirements/*.txt`](requirements/), which pin an exact version **and every
+artifact's sha256** for the full transitive closure — pip enforces those hashes,
+so a yanked or tampered dependency fails the install instead of silently
+changing a build. Your venv and the CI runner get identical bytes.
+
+To change a tool, edit the `.in` file and regenerate:
+
+```bash
+python3 scripts/lock_toolchain.py            # rewrite the .txt files
+python3 scripts/lock_toolchain.py --upgrade  # re-resolve to newest allowed
+python3 scripts/lock_toolchain.py --check    # what `make lint` runs
+```
+
+Commit both the `.in` and the regenerated `.txt`; a stale lock fails `make lint`.
+Regenerating needs `uv` (installed by `make venv`); *installing* never does.
+
 ### Reproduce the whole gate — `nox`
 
 [`noxfile.py`](noxfile.py) runs the exact gate the CI jobs run, in isolated
@@ -50,7 +69,7 @@ auto-fixes straight back onto the branch.
 |---|---|
 | `make test` | unit + functional suites, **≥80% line coverage** |
 | `make patch-coverage` | changed-line coverage vs `main`, **≥80% of the diff** (PRs) |
-| `bash tests/smoke.sh` | 152 end-to-end checks through the real `./boost` shim |
+| `bash tests/smoke.sh` | 170 end-to-end checks through the real `./boost` shim |
 | `make mutation` | mutmut over `boost_cli/core`, **≥80% mutants killed** |
 | `ruff check boost_cli tests` | lint, zero findings |
 | `mypy` | type check, zero errors |
@@ -58,6 +77,8 @@ auto-fixes straight back onto the branch.
 | `lint-imports` | layering: `core/` imports no `commands/`/`cli`; CLI depends inward |
 | `vulture` | dead-code radar: no unused imports / unreachable code (confidence ≥80) |
 | `xenon` | complexity ratchet: aggregate cyclomatic complexity can't regress (avg ≤B) |
+| `refurb boost_cli` | modernization smells the ruff families miss, zero findings |
+| `scripts/lock_toolchain.py --check` | the hash-pinned toolchain matches its `.in` declarations |
 
 ## Ground rules
 

{boost_skill_cli-1.0.206 → boost_skill_cli-1.0.208}/Makefile

@@ -12,10 +12,18 @@ EVAL_HOME := $(CURDIR)/.eval-home
 
 .PHONY: venv test unit functional smoke coverage patch-coverage mutation lint check demo clean-test eval eval-ai eval-rec eval-stats eval-explain audit dist-check bdd bench bench-cli
 
+# Every tool comes from a hash-pinned requirements/*.txt — the same files CI
+# installs (see scripts/lock_toolchain.py). pip enforces the hashes, so a dev
+# venv and a CI runner resolve to identical bytes. mutation-tools.txt is a
+# superset of test-tools.txt, so installing it alone covers both; the two are
+# never layered because pip enforces hashes across the whole resolution.
 venv:
 	python3 -m venv $(VENV)
-	$(VENV)/bin/pip -q install pytest pytest-cov coverage mutmut hypothesis diff-cover
-	$(VENV)/bin/pip -q install -r requirements/lint-tools.txt   # pinned; CI installs the same set
+	$(VENV)/bin/pip -q install -r requirements/mutation-tools.txt
+	$(VENV)/bin/pip -q install -r requirements/coverage-tools.txt
+	$(VENV)/bin/pip -q install -r requirements/lint-tools.txt
+	$(VENV)/bin/pip -q install -r requirements/release-tools.txt
+	$(VENV)/bin/pip -q install uv     # regenerates the locks; not itself locked
 
 unit:
 	$(PYTEST) tests/unit -q
@@ -57,6 +65,7 @@ lint:
 	$(PY) scripts/build_registries.py --check
 	$(PY) scripts/build_roadmap.py --check
 	$(PY) scripts/build_command_reference.py --check
+	$(PY) scripts/lock_toolchain.py --check
 	$(PY) scripts/import_budget.py
 	$(PY) scripts/perf_gate.py
 	$(PY) scripts/check_anchors.py

{boost_skill_cli-1.0.206/boost_skill_cli.egg-info → boost_skill_cli-1.0.208}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.206
+Version: 1.0.208
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE

{boost_skill_cli-1.0.206 → boost_skill_cli-1.0.208}/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.206'
-__version_tuple__ = version_tuple = (1, 0, 206)
+__version__ = version = '1.0.208'
+__version_tuple__ = version_tuple = (1, 0, 208)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.206 → boost_skill_cli-1.0.208}/boost_cli/commands/info.py

@@ -239,6 +239,7 @@ def cmd_info(argv):
     declared_caps = sorted(capabilities.declared(meta))
     detected_extra = sorted(capabilities.detect(skill_text)
                             - set(declared_caps)) if skill_text else []
+    mcp_servers = store.declared_mcp_servers(skill_dir) if skill_dir else []
     score = size = files = None
     if skill_dir:
         score, _notes = util.score_skill(skill_dir)
@@ -249,6 +250,7 @@ def cmd_info(argv):
             "name": name, "description": desc,
             "installed": lock, "project": plock,
             "capabilities": declared_caps, "detected_capabilities": detected_extra,
+            "mcp_servers": [r["name"] for r in mcp_servers],
             "latest": (cat or {}).get("version"),
             "tap": (lock or plock or cat or {}).get("tap"),
             "store": str(sdir) if lock and sdir.is_dir() else None,
@@ -322,6 +324,10 @@ def cmd_info(argv):
         # under-declaration signal a reviewer wants to see.
         out.kv("detected", out.role(", ".join(detected_extra) + "  (not declared)",
                                     "warn"))
+    if mcp_servers:
+        # A skill that needs an MCP server is useless without it, so this belongs
+        # next to capabilities: both answer "what does this expect of my setup?"
+        out.kv("mcp servers", ", ".join(r["name"] for r in mcp_servers))
     if score is not None:
         out.kv("quality", "%d/100" % score)
         out.kv("size", util.human_size(size))

{boost_skill_cli-1.0.206 → boost_skill_cli-1.0.208}/boost_cli/commands/pkg.py

@@ -109,6 +109,67 @@ def _warn_secrets(res: store.InstallResult) -> None:
         out.warn("  L%d [%s] %s" % (f.line, f.severity, f.description))
 
 
+def _offer_mcp(res: store.InstallResult) -> None:
+    """Surface the MCP servers a just-installed skill needs, and offer to wire them.
+
+    A skill that only works paired with an MCP server used to install "cleanly"
+    and then fail in the agent for a reason nothing surfaced. Now the requirement
+    is stated at install time, and boost offers to run the registration for the
+    servers that came with a runnable spec.
+
+    Advisory, never fatal: a declined prompt, a missing ``claude`` CLI or a failed
+    registration all leave the skill installed. Suppressed entirely by
+    ``--no-mcp``, which sets ``BOOST_NO_MCP_OFFER``.
+    """
+    rows = res.mcp_servers
+    if not rows or os.environ.get("BOOST_NO_MCP_OFFER"):
+        return
+    from ..core import mcpdecl
+    out.info("")
+    out.warn("%s needs %s to work:" % (res.name, _plural(len(rows), "MCP server")))
+    for row in rows:
+        how = ("`%s`" % row["spec"]["command"] if row["spec"]
+               and row["spec"].get("command") else "no command declared")
+        out.info("  %s  %s" % (out.c(row["name"], out.BOLD),
+                               out.role(how, "muted")))
+    wirable = mcpdecl.registrable(rows)
+    if not wirable:
+        # Name-only declarations: boost will not invent a command line.
+        out.dim("  install these yourself, then `boost mcp register`")
+        return
+    if not out.confirm("register %s with Claude Code now?"
+                       % _plural(len(wirable), "server"), default=False):
+        out.dim("  skipped — `claude mcp add …` when you're ready")
+        return
+    for row in wirable:
+        _register_mcp_server(row["name"], row["spec"])
+
+
+def _register_mcp_server(name: str, spec: dict) -> None:
+    """Run one `claude mcp add` for a skill-declared server. Never raises."""
+    import subprocess
+    from ..core import mcpdecl
+    argv = mcpdecl.register_argv(name, spec)
+    if not shutil.which("claude"):
+        out.warn("`claude` CLI not found — run this yourself:")
+        out.info("  " + " ".join(argv))
+        return
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, timeout=60)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        out.warn("could not register %s: %s" % (name, e))
+        out.info("  run it yourself: " + " ".join(argv))
+        return
+    if proc.returncode != 0:
+        tail = (proc.stderr or "").strip().splitlines()
+        out.warn("could not register %s: %s"
+                 % (name, tail[-1] if tail else "unknown error"))
+        out.info("  run it yourself: " + " ".join(argv))
+        return
+    out.ok("registered MCP server %s" % name)
+    journal.log("mcp-register", name)
+
+
 def _report_result(res: store.InstallResult) -> None:
     """The canonical three-line install report."""
     if res.kind in ("rule", "workflow"):
@@ -141,6 +202,7 @@ def _report_result(res: store.InstallResult) -> None:
     out.ok("lock updated (.skill-lock.json)")
     _warn_injection(res)
     _warn_secrets(res)
+    _offer_mcp(res)
 
 
 def _boostfile_text(skills: Dict[str, dict], via: str = "boost bundle dump") -> str:
@@ -238,8 +300,15 @@ def cmd_install(argv: List[str]) -> int:
                     help="show what would happen without changing anything")
     ap.add_argument("--no-deps", action="store_true",
                     help="install only the named skills, not their `requires:`")
+    ap.add_argument("--no-mcp", action="store_true",
+                    help="don't offer to register MCP servers a skill declares")
     args = ap.parse_args(argv)
     args.scope = args.scope or scopes.SCOPE_USER
+    if args.no_mcp:
+        # An env flag rather than threading a parameter through _report_result's
+        # eight call sites: the offer is a leaf-level side effect, and this keeps
+        # every other install path (update, reinstall, team, MCP tool) unchanged.
+        os.environ["BOOST_NO_MCP_OFFER"] = "1"
     only = _check_agents(args.agent)
     multi = len(args.names) > 1
     entries, failed = [], 0

{boost_skill_cli-1.0.206 → boost_skill_cli-1.0.208}/boost_cli/commands/quality.py

@@ -848,7 +848,10 @@ def cmd_health(argv):
 _PROVENANCE_STYLE = {
     provenance.VERIFIED: "success",
     provenance.UNTRUSTED: "warn",
-    provenance.INVALID: "err",
+    # "danger", not "err": out.role() looks the name up in output.ROLES, which
+    # has no "err" key — so an invalid tap signature raised KeyError on any
+    # color terminal. The suite never caught it because conftest sets NO_COLOR.
+    provenance.INVALID: "danger",
     provenance.UNSIGNED: "muted",
 }
 

{boost_skill_cli-1.0.206 → boost_skill_cli-1.0.208}/boost_cli/commands/safety.py

@@ -10,11 +10,13 @@ from __future__ import annotations
 
 import json
 import re
+import time
+from contextlib import suppress
 
 from .. import cliparse
-from ..core import integrity, journal, lockfile
+from ..core import catalog, frontmatter, gitutil, integrity, journal, lockfile
 from ..core import output as out
-from ..core import policy, store, util
+from ..core import policy, provenance, registry, staleness, store, trustaudit, util
 from ..errors import BoostError
 from ._common import _iter_installed, _s
 
@@ -42,8 +44,14 @@ def cmd_audit(argv):
         prog="boost audit",
         description="Check installed skills against a safety blocklist")
     ap.add_argument("--json", action="store_true")
+    ap.add_argument("--skills", action="store_true",
+                    help="trust/staleness report for installed skills instead "
+                         "of the content scan")
     args = ap.parse_args(argv)
 
+    if args.skills:
+        return _trust_audit(args.json)
+
     pol = policy.load()
     installed = _iter_installed()
     findings: dict = {}
@@ -110,6 +118,154 @@ def cmd_audit(argv):
     return 1 if counts["HIGH"] or counts["MED"] else 0
 
 
+# --- audit --skills: trust & staleness across the whole installed set ------
+#
+# The signals already existed, one per command: `trust` reports tap signing,
+# `outdated` reports drift vs the tap, `deps` shows the conflicts: graph. This
+# gathers all three over the installed set and hands the decision to
+# core/trustaudit.py, which is where every branch of it is unit-tested.
+
+_TRUST_ROLE = {trustaudit.HIGH: "danger", trustaudit.MED: "warn",
+               trustaudit.LOW: "muted"}
+
+
+def _tap_age_days(tap):
+    """Days since a tap clone's last commit, or ``None`` when unknowable."""
+    try:
+        proc = gitutil.run(["-C", str(tap.path), "log", "-1", "--format=%ct"],
+                           check=False)
+    except BoostError:
+        return None
+    if proc.returncode != 0 or not proc.stdout.strip():
+        return None
+    try:
+        committed = int(proc.stdout.strip())
+    except ValueError:
+        return None
+    return max(0, int((time.time() - committed) // 86400))
+
+
+def _tap_signals(tap_name, cache):
+    """``(provenance status, age in days, HEAD commit)`` for a tap, memoized.
+
+    A tap boost cannot read — unknown name, never cloned — yields
+    ``(None, None, "")``, which ``trustaudit`` renders as "signature cannot be
+    checked" rather than silently passing.
+    """
+    if tap_name not in cache:
+        try:
+            tap = registry.get(tap_name)
+        except BoostError:
+            cache[tap_name] = (None, None, "")
+        else:
+            cache[tap_name] = ((provenance.verify_dir(tap.path).status,
+                                _tap_age_days(tap), gitutil.head_commit(tap.path))
+                               if tap.is_cloned else (None, None, ""))
+    return cache[tap_name]
+
+
+def _upstream_reason(name, lk, tap_name, head):
+    """``staleness.upstream_reason`` for one installed skill, or ``None``.
+
+    Same signal-gathering order as ``cmd_outdated`` so the two commands can
+    never disagree about whether a skill is behind its tap.
+    """
+    matches = [e for e in catalog.find(name) if e["tap"] == tap_name]
+    if not matches:
+        return None
+    entry = matches[0]
+    latest = str(entry.get("version") or "0.0.0")
+    installed_v = str(lk.get("version") or "0.0.0")
+    src_sha = None
+    if not util.semver_gt(latest, installed_v) and head and head != lk.get("commit"):
+        try:
+            src_sha = util.sha256_dir(store.source_dir_for(entry))
+        except BoostError:
+            return None  # source checkout is gone; `verify` owns that finding
+    return staleness.upstream_reason(installed_v, latest, lk.get("commit", ""),
+                                     head, lk.get("sha256", ""), src_sha)
+
+
+def _installed_conflicts(names):
+    """A ``conflicts_of`` callable reading each installed skill's own copy.
+
+    Reads the store copy rather than the catalog on purpose: the audit is about
+    what is *installed*, which can be an older revision than the tap now
+    advertises.
+    """
+    cache: dict = {}
+
+    def conflicts_of(name):
+        if name not in cache:
+            meta: dict = {}
+            # unreadable store copy: `verify` owns that finding, not this
+            with suppress(OSError, BoostError):
+                text = (store.skill_store_dir(name) / "SKILL.md").read_text(
+                    encoding="utf-8", errors="replace")
+                meta, _body = frontmatter.parse(text)
+            cache[name] = trustaudit.relation_list(meta, "conflicts")
+        return cache[name]
+
+    return conflicts_of
+
+
+def _trust_audit(as_json: bool) -> int:
+    """`boost audit --skills` — one trust-health answer for the installed set."""
+    installed = dict(_iter_installed())
+    peers: dict = {}
+    for name, peer in trustaudit.conflict_pairs(list(installed),
+                                                _installed_conflicts(installed)):
+        peers.setdefault(name, []).append(peer)
+
+    taps: dict = {}
+    findings: dict = {}
+    for name, lk in sorted(installed.items()):
+        tap_name = str(lk.get("tap") or "local")
+        is_local = tap_name == "local"
+        status, age, head = ((None, None, "") if is_local
+                             else _tap_signals(tap_name, taps))
+        rows = trustaudit.skill_findings(
+            is_local=is_local, provenance_status=status, tap_age_days=age,
+            upstream_reason=(None if is_local
+                             else _upstream_reason(name, lk, tap_name, head)),
+            conflicts_with=peers.get(name, ()))
+        if rows:
+            findings[name] = rows
+
+    counts = trustaudit.count_severities(findings)
+    rc = trustaudit.exit_code(counts)
+    if as_json:
+        print(json.dumps({"skills_scanned": len(installed),
+                          "findings": findings, "counts": counts}, indent=2))
+        return rc
+    return _render_trust_audit(installed, findings, counts, rc)
+
+
+def _render_trust_audit(installed, findings, counts, rc: int) -> int:
+    """Human rendering for `boost audit --skills`."""
+    total = len(installed)
+    out.heading("trust audit — %d skill%s" % (total, _s(total)))
+    if not total:
+        out.info("nothing installed yet — `boost install <skill>` to start")
+        return rc
+    if not findings:
+        out.ok("all %d installed skill%s signed, current and conflict-free"
+               % (total, _s(total)))
+        return rc
+    for name in sorted(findings):
+        print("  " + out.c(name, out.BOLD))
+        for f in findings[name]:
+            print("    %s %s  %s"
+                  % (out.role(f["severity"].ljust(4), _TRUST_ROLE[f["severity"]]),
+                     f["label"], out.role(f["detail"], "muted")))
+    print()
+    out.verdict(trustaudit.is_healthy(counts),
+                "%d high · %d medium · %d low across %d of %d skill%s"
+                % (counts[trustaudit.HIGH], counts[trustaudit.MED],
+                   counts[trustaudit.LOW], len(findings), total, _s(total)))
+    return rc
+
+
 def cmd_verify(argv):
     ap = cliparse.parser(
         prog="boost verify",

boost_skill_cli-1.0.208/boost_cli/core/mcpdecl.py

@@ -0,0 +1,193 @@
+"""What MCP servers does a skill need, and how do we wire them?
+
+Mining boost's catalog surfaces a recurring shape: skills that only work paired
+with a Model Context Protocol server (``manage-mcp-servers``, ``mcp-builder``,
+``mcp-integration`` and dozens more). boost already *is* an MCP server and
+registers itself with ``boost mcp register`` — but a skill had no way to say
+"I need server Y," so installing one left the user to discover that by hand.
+
+Two declaration forms, both deliberately **flat**:
+
+* ``mcp: github, playwright`` in SKILL.md frontmatter (a comma string or a YAML
+  block list) — just the names, reusing the exact contract ``requires:`` and
+  ``conflicts:`` already use.
+* a bundled ``.mcp.json`` in the skill directory — the standard MCP shape
+  (``{"mcpServers": {name: {command, args, env}}}``), carrying full specs.
+
+Why flat, and not the nested ``mcp:`` mapping the roadmap card sketched:
+:mod:`boost_cli.core.frontmatter` is a stdlib-only YAML *subset* with no nested
+mapping support, and it does not fail loudly on one — it hoists the inner keys to
+top level and clobbers their siblings. A nested block parses to
+``{'mcp': '', 'servers': [...], 'command': 'npx'}``, silently corrupting the
+entry's metadata. Teaching the parser nested mappings would change the shape of
+every catalog entry's ``meta`` (and every consumer of it), so the declaration
+meets the parser where it already works and the full specs live in the standard
+sidecar file that needs no parser at all.
+
+Everything here is pure and I/O-free, like :mod:`boost_cli.core.resolve` and
+:mod:`boost_cli.core.staleness`: callers read the files and pass text in, so
+every branch of the *decision* is unit-testable and reachable by the mutation
+gate.
+"""
+from __future__ import annotations
+
+import json
+from typing import Dict, List, Optional, Tuple
+
+# The frontmatter key a skill uses to name the servers it needs.
+DECL_KEY = "mcp"
+
+# The sidecar file a skill bundles to carry full server specs. Standard MCP
+# filename and shape, so an author can lift the file straight from a server's
+# own README.
+SIDECAR = ".mcp.json"
+
+# Top-level key inside .mcp.json, per the MCP config convention.
+SERVERS_KEY = "mcpServers"
+
+# Ownership tag written alongside a server boost registered, mirroring
+# claude_settings.MARKER. Without it an uninstall could not tell a
+# boost-registered server from one the user configured by hand, so it would
+# either strip the user's config or leak boost's.
+MARKER_KEY = "x-boost-skill"
+
+
+def declared_names(meta: Optional[dict]) -> List[str]:
+    """Server names a skill's frontmatter declares, de-duped, order preserved.
+
+    Accepts a YAML list or a comma-separated string and drops blanks — the same
+    contract ``requires:``/``conflicts:`` use, so an author who knows one knows
+    this one. A missing/empty/``False`` value means "declares nothing".
+    """
+    val = (meta or {}).get(DECL_KEY)
+    if val in (None, "", False):
+        return []
+    raw = ([str(x) for x in val] if isinstance(val, list)
+           else str(val).split(","))
+    out: List[str] = []
+    for item in raw:
+        name = item.strip()
+        if name and name not in out:
+            out.append(name)
+    return out
+
+
+def parse_sidecar(text: Optional[str]) -> Dict[str, dict]:
+    """``{name: spec}`` from a bundled ``.mcp.json``'s text.
+
+    Tolerant by design: unreadable JSON, a non-object document, a missing or
+    non-object ``mcpServers`` key, and non-object individual specs all read as
+    "no specs". A malformed sidecar must never make an otherwise-fine install
+    fail — the skill still works, the user just does not get the wiring offer.
+    """
+    if not text:
+        return {}
+    try:
+        doc = json.loads(text)
+    except (ValueError, TypeError):
+        return {}
+    if not isinstance(doc, dict):
+        return {}
+    servers = doc.get(SERVERS_KEY)
+    if not isinstance(servers, dict):
+        return {}
+    return {str(k): v for k, v in servers.items()
+            if k and isinstance(v, dict)}
+
+
+def servers_for(meta: Optional[dict], sidecar_text: Optional[str] = None,
+                ) -> List[dict]:
+    """Every MCP server a skill needs, as ``{"name", "spec", "source"}`` rows.
+
+    Merges the two declaration forms. A name in *both* uses the sidecar's spec —
+    the frontmatter only names a server, so a bundled spec is strictly more
+    information. ``spec`` is ``None`` for a name-only declaration, which the
+    caller renders as "you need this, here is no command to run it" rather than
+    offering a registration it cannot perform.
+
+    ``source`` is ``"sidecar"`` or ``"frontmatter"``, so output can tell the user
+    where a requirement came from when the two disagree. Rows are sorted by name
+    for deterministic output.
+    """
+    specs = parse_sidecar(sidecar_text)
+    rows: Dict[str, dict] = {
+        name: {"name": name, "spec": spec, "source": "sidecar"}
+        for name, spec in specs.items()}
+    for name in declared_names(meta):
+        if name not in rows:
+            rows[name] = {"name": name, "spec": None, "source": "frontmatter"}
+    return [rows[k] for k in sorted(rows)]
+
+
+def registrable(rows) -> List[dict]:
+    """The rows boost can actually wire up — those carrying a runnable spec.
+
+    A spec is runnable when it names a ``command``. Anything else (a name-only
+    frontmatter declaration, or a sidecar entry describing a remote/URL server
+    boost has no launcher for) is reported to the user but never auto-registered:
+    boost will not invent a command line on an author's behalf.
+    """
+    return [r for r in rows
+            if isinstance(r.get("spec"), dict)
+            and str(r["spec"].get("command") or "").strip()]
+
+
+def register_argv(name: str, spec: dict, *, scope: str = "user") -> List[str]:
+    """The ``claude mcp add`` argv that registers one declared server.
+
+    Mirrors ``cmd_mcp``'s invariant exactly: the server **name** precedes every
+    ``-e`` flag, and a bare ``--`` separates boost's flags from the server's own
+    command and arguments. Getting that order wrong makes the CLI read the
+    command as another flag value, which is why it is pinned by a test.
+    """
+    argv = ["claude", "mcp", "add", name, "--scope", scope]
+    env = spec.get("env")
+    if isinstance(env, dict):
+        for key in sorted(env):
+            argv += ["-e", "%s=%s" % (key, env[key])]
+    argv.extend(("--", str(spec["command"])))
+    args = spec.get("args")
+    if isinstance(args, list):
+        argv += [str(a) for a in args]
+    return argv
+
+
+def merge_into(existing: Optional[dict], rows, skill: str) -> Tuple[dict, List[str]]:
+    """Add ``rows``' specs to an ``.mcp.json`` document -> ``(doc, added)``.
+
+    Returns a **new** document rather than mutating the caller's, and never
+    overwrites a server the user already configured: a name already present is
+    left exactly as-is and omitted from ``added``. Each entry boost does add
+    carries a :data:`MARKER_KEY` naming the skill that asked for it, so a later
+    uninstall can remove precisely what boost wrote and nothing else.
+    """
+    doc = dict(existing) if isinstance(existing, dict) else {}
+    servers = dict(doc.get(SERVERS_KEY) or {})
+    added: List[str] = []
+    for row in registrable(rows):
+        name = row["name"]
+        if name in servers:
+            continue
+        entry = dict(row["spec"])
+        entry[MARKER_KEY] = skill
+        servers[name] = entry
+        added.append(name)
+    doc[SERVERS_KEY] = servers
+    return doc, added
+
+
+def strip_owned(existing: Optional[dict], skill: str) -> Tuple[dict, List[str]]:
+    """Remove the servers boost registered for ``skill`` -> ``(doc, removed)``.
+
+    Only entries whose :data:`MARKER_KEY` names this skill are removed, so a
+    server the user configured by hand — or one another skill still needs —
+    survives an uninstall untouched.
+    """
+    doc = dict(existing) if isinstance(existing, dict) else {}
+    servers = dict(doc.get(SERVERS_KEY) or {})
+    removed = [name for name, spec in servers.items()
+               if isinstance(spec, dict) and spec.get(MARKER_KEY) == skill]
+    for name in removed:
+        del servers[name]
+    doc[SERVERS_KEY] = servers
+    return doc, sorted(removed)