boost-skill-cli 1.0.187__tar.gz → 1.0.188__tar.gz

{boost_skill_cli-1.0.187 → boost_skill_cli-1.0.188}/.vale/styles/config/vocabularies/boost/accept.txt

@@ -62,6 +62,8 @@ tracebacks
 unkilled
 unstaged
 untap
+vendored
+vendoring
 venv
 venvs
 Weaviate

{boost_skill_cli-1.0.187 → boost_skill_cli-1.0.188}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boost-skill-cli
-Version: 1.0.187
+Version: 1.0.188
 Summary: boost — Homebrew for AI coding skills
 Author: Jonathan Reyes
 License: GNU GENERAL PUBLIC LICENSE
@@ -826,6 +826,44 @@ GitHub registries  ──boost update──▶  ~/.boost/repos/    (shallow clon
                    ────symlinks───▶  ~/.claude/skills/  ~/.windsurf/skills/  ~/.cursor/skills/
 ```
 
+### User scope vs project scope
+
+That's the default — **user scope**, the skills you want everywhere. The other
+half is the npm `--save` half: skills a *team* agrees on, which belong in the
+repo where they can be reviewed in a PR and arrive with a `git clone`.
+
+```bash
+boost install code-review --local     # into THIS repo (= --scope project)
+boost install code-review             # into your user config (default)
+boost list --local                    # just what this repo carries
+boost uninstall code-review --local
+```
+
+A `--local` install writes **real directories** into the repo's own agent config
+and records them in a committable per-repo lock:
+
+```text
+<repo>/.claude/skills/<name>/     real copies, not symlinks
+<repo>/.cursor/skills/<name>/
+<repo>/.boost/skill-lock.json     commit this — it's what teammates clone
+```
+
+Real copies, deliberately: a symlink into *your* `~/.agents/skills` is a
+dangling pointer on anyone else's machine, so committing one would ship
+something that only works on the author's laptop. The two scopes use separate
+lock files, so vendoring a skill into a repo never fights with the copy you use
+everywhere — and `boost install --local` run from `src/deep/nested` walks up to
+the repo root rather than scattering a `.claude/` three directories down.
+
+After a fresh clone, `boost sync` re-materializes anything the project lock
+records but the checkout is missing — the lock stores repo-relative paths, so it
+works from whatever directory your teammate cloned into. It never deletes a
+skill directory boost didn't write, and it won't overwrite a hand-written
+`.claude/skills/<name>/` unless you pass `--force`.
+
+`boost update` covers user scope only for now; to refresh a vendored skill use
+`boost install <skill> --local --force`.
+
 ## The usual workflow
 
 ```bash

{boost_skill_cli-1.0.187 → boost_skill_cli-1.0.188}/README.md

@@ -110,6 +110,44 @@ GitHub registries  ──boost update──▶  ~/.boost/repos/    (shallow clon
                    ────symlinks───▶  ~/.claude/skills/  ~/.windsurf/skills/  ~/.cursor/skills/
 ```
 
+### User scope vs project scope
+
+That's the default — **user scope**, the skills you want everywhere. The other
+half is the npm `--save` half: skills a *team* agrees on, which belong in the
+repo where they can be reviewed in a PR and arrive with a `git clone`.
+
+```bash
+boost install code-review --local     # into THIS repo (= --scope project)
+boost install code-review             # into your user config (default)
+boost list --local                    # just what this repo carries
+boost uninstall code-review --local
+```
+
+A `--local` install writes **real directories** into the repo's own agent config
+and records them in a committable per-repo lock:
+
+```text
+<repo>/.claude/skills/<name>/     real copies, not symlinks
+<repo>/.cursor/skills/<name>/
+<repo>/.boost/skill-lock.json     commit this — it's what teammates clone
+```
+
+Real copies, deliberately: a symlink into *your* `~/.agents/skills` is a
+dangling pointer on anyone else's machine, so committing one would ship
+something that only works on the author's laptop. The two scopes use separate
+lock files, so vendoring a skill into a repo never fights with the copy you use
+everywhere — and `boost install --local` run from `src/deep/nested` walks up to
+the repo root rather than scattering a `.claude/` three directories down.
+
+After a fresh clone, `boost sync` re-materializes anything the project lock
+records but the checkout is missing — the lock stores repo-relative paths, so it
+works from whatever directory your teammate cloned into. It never deletes a
+skill directory boost didn't write, and it won't overwrite a hand-written
+`.claude/skills/<name>/` unless you pass `--force`.
+
+`boost update` covers user scope only for now; to refresh a vendored skill use
+`boost install <skill> --local --force`.
+
 ## The usual workflow
 
 ```bash

{boost_skill_cli-1.0.187 → boost_skill_cli-1.0.188}/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.187'
-__version_tuple__ = version_tuple = (1, 0, 187)
+__version__ = version = '1.0.188'
+__version_tuple__ = version_tuple = (1, 0, 188)
 
 __commit_id__ = commit_id = None

{boost_skill_cli-1.0.187 → boost_skill_cli-1.0.188}/boost_cli/commands/info.py

@@ -17,7 +17,8 @@ from pathlib import Path
 
 from .. import cliparse
 from ..core import (ai, catalog, frontmatter, gitutil, imperative, journal,
-                    lockfile, logs, paths, registry, store, util)
+                    lockfile, logs, paths, projectlock, registry, scopes, store,
+                    util)
 from ..core import output as out
 from ..errors import BoostError
 
@@ -127,21 +128,30 @@ def cmd_list(argv):
     ap = cliparse.parser(prog="boost list",
                                  description="List installed skills, rules and workflows")
     ap.add_argument("--tag", help="only show skills carrying this tag")
+    ap.add_argument("--local", action="store_true",
+                    help="only the skills installed into this repo")
     ap.add_argument("--json", action="store_true", help="machine-readable output")
     args = ap.parse_args(argv)
     skills = lockfile.installed()
     rules = lockfile.installed_rules()
     workflows = lockfile.installed_workflows()
+    # Project skills live in the repo's own lock, never the user's — read it
+    # separately so a checkout's committed skills show up alongside yours.
+    pbase = scopes.project_root()
+    project = projectlock.installed(pbase) if pbase is not None else {}
+    if args.local:
+        skills, rules, workflows = {}, {}, {}
     if args.tag:
         # Tags are a skill-only concept, so --tag narrows to skills.
         want = args.tag.lstrip("#")
         skills = {n: e for n, e in skills.items() if want in (e.get("tags") or [])}
-        rules, workflows = {}, {}
+        rules, workflows, project = {}, {}, {}
     if args.json:
-        print(json.dumps({"skills": skills, "rules": rules, "workflows": workflows},
+        print(json.dumps({"skills": skills, "rules": rules,
+                          "workflows": workflows, "project": project},
                          indent=2, sort_keys=True))
         return 0
-    if not skills and not rules and not workflows:
+    if not skills and not rules and not workflows and not project:
         print(out.empty_state(
             "no skills installed"
             + (" with tag #%s" % args.tag.lstrip("#") if args.tag else ""),
@@ -165,6 +175,15 @@ def cmd_list(argv):
         out.table(rows, headers=("NAME", "VERSION", "TAP", "AGENTS", "FLAGS"))
         print("  " + out.aurora("%d skill%s installed"
                                 % (len(rows), "" if len(rows) == 1 else "s"), "cyan"))
+    if project:
+        out.heading("project skills (%s)" % paths.tilde(pbase))
+        rows = [(name, e.get("version", "?"), e.get("tap", "?"),
+                 "·".join(a.split("-")[0] for a in e.get("agents") or []))
+                for name, e in sorted(project.items())]
+        out.table(rows, headers=("NAME", "VERSION", "TAP", "AGENTS"))
+        print("  " + out.role("committed with the repo — %s/%s"
+                              % (projectlock.LOCK_DIRNAME,
+                                 projectlock.LOCK_FILENAME), "muted"))
     if rules:
         _kind_table("installed rules", rules)
     if workflows:
@@ -180,6 +199,11 @@ def cmd_info(argv):
     args = ap.parse_args(argv)
     name = args.name
     lock = lockfile.get_skill(name)
+    # A project-scoped skill is installed — just not at user scope. Without this
+    # `boost info` would call it "not installed" while it sits in the repo, and
+    # the install banner's own "next: boost info <name>" would lead nowhere.
+    pbase = scopes.project_root()
+    plock = projectlock.get_skill(pbase, name) if pbase is not None else None
     if lock:
         matches = catalog.find(name)
         same_tap = [e for e in matches if e["tap"] == lock.get("tap")]
@@ -189,6 +213,12 @@ def cmd_info(argv):
 
     sdir = store.skill_store_dir(name)
     skill_dir = sdir if lock and sdir.is_dir() else None
+    if skill_dir is None and plock:
+        for m in plock.get("materializations") or []:
+            cand = scopes.resolve_in_base(pbase, m.get("path"))
+            if cand is not None and cand.is_dir():
+                skill_dir = cand
+                break
     if skill_dir is None and cat:
         try:
             skill_dir = store.source_dir_for(cat)
@@ -207,8 +237,9 @@ def cmd_info(argv):
     if args.json:
         print(json.dumps({
             "name": name, "description": desc,
-            "installed": lock, "latest": (cat or {}).get("version"),
-            "tap": (lock or cat or {}).get("tap"),
+            "installed": lock, "project": plock,
+            "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,
             "quality": score, "size": size, "files": files,
         }, indent=2))
@@ -227,6 +258,8 @@ def cmd_info(argv):
         latest = str((cat or {}).get("version") or "")
         if cat and latest != str(lock.get("version", "?")):
             badges.append(out.badge("update available", "yellow"))
+    elif plock:
+        badges.append(out.badge("installed in this project", "green"))
     else:
         badges.append(out.badge("not installed", "cyan"))
     tapname = (lock or cat or {}).get("tap")

{boost_skill_cli-1.0.187 → boost_skill_cli-1.0.188}/boost_cli/commands/pkg.py

@@ -16,8 +16,9 @@ from typing import Dict, List, Optional
 
 from .. import cliparse
 from ..core import (adapters, agents, catalog, config, frontmatter, gitutil,
-                    injectscan, journal, lockfile, paths, registry,
-                    secretscan, staleness, store, typosquat, updatediff, util)
+                    injectscan, journal, lockfile, paths, projectlock, registry,
+                    scopes, secretscan, staleness, store, typosquat, updatediff,
+                    util)
 from ..core import output as out
 from ..errors import BoostError
 
@@ -118,6 +119,18 @@ def _report_result(res: store.InstallResult) -> None:
         _warn_injection(res)
         _warn_secrets(res)
         return
+    if res.scope == scopes.SCOPE_PROJECT:
+        # No canonical store and no symlinks — a real copy per agent, so the
+        # report says "copied into" for each rather than "copied … then linked".
+        out.ok("copied into this repo → %s"
+               % (" · ".join(res.linked) or "(no enabled agents)"))
+        out.ok("project lock updated (%s/%s)"
+               % (projectlock.LOCK_DIRNAME, projectlock.LOCK_FILENAME))
+        out.dim("  commit %s/ to share these with the team"
+                % projectlock.LOCK_DIRNAME)
+        _warn_injection(res)
+        _warn_secrets(res)
+        return
     out.ok("copied to %s" % _tilde(res.dest))
     if res.linked:
         out.ok("linked → %s" % " · ".join(res.linked))
@@ -161,12 +174,20 @@ def cmd_install(argv: List[str]) -> int:
                     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("--scope", choices=("user", "project"), default="user",
-                    help="rules/workflows: install into your user config (default) "
-                         "or the current repo (project)")
+    scope_g = ap.add_mutually_exclusive_group()
+    scope_g.add_argument("--scope", choices=scopes.SCOPES, default=None,
+                         help="install into your user config (default) or the "
+                              "current repo (project)")
+    scope_g.add_argument("--local", dest="scope", action="store_const",
+                         const=scopes.SCOPE_PROJECT,
+                         help="into this repo, committable (= --scope project)")
+    scope_g.add_argument("--global", dest="scope", action="store_const",
+                         const=scopes.SCOPE_USER,
+                         help="into your user config (= --scope user, default)")
     ap.add_argument("--dry-run", action="store_true",
                     help="show what would happen without changing anything")
     args = ap.parse_args(argv)
+    args.scope = args.scope or scopes.SCOPE_USER
     only = _check_agents(args.agent)
     multi = len(args.names) > 1
     entries, failed = [], 0
@@ -183,7 +204,23 @@ def cmd_install(argv: List[str]) -> int:
 
     if args.dry_run:
         targets = [a for a in agents.enabled_agents() if not only or a in only]
+        pbase = scopes.resolve_base(args.scope)
+        if args.scope == scopes.SCOPE_PROJECT and pbase is None:
+            raise BoostError(
+                "there is no project here to install into",
+                hint="cd into a repo, or drop --local to install for your user")
         for e in entries:
+            if args.scope == scopes.SCOPE_PROJECT and e.get("kind", "skill") == "skill":
+                seen = projectlock.get_skill(pbase, e["name"])
+                out.info("would %s %s v%s from %s into %s"
+                         % ("reinstall" if seen else "install", e["name"],
+                            e["version"], e["tap"], _tilde(pbase)))
+                for agent_name, sdir in agents.enabled_agents().items():
+                    if only and agent_name not in only:
+                        continue
+                    out.info("  copy  → %s"
+                             % _tilde(scopes.skill_target(sdir, e["name"], base=pbase)))
+                continue
             if e.get("kind") in ("rule", "workflow"):
                 k = e["kind"]
                 seen = (lockfile.get_rule if k == "rule"
@@ -253,12 +290,17 @@ def cmd_uninstall(argv: List[str]) -> int:
         prog="boost uninstall",
         description="Remove an installed skill, rule, workflow, or config")
     ap.add_argument("names", nargs="+", metavar="NAME")
+    ap.add_argument("--local", dest="scope", action="store_const",
+                    const=scopes.SCOPE_PROJECT, default=None,
+                    help="remove from this repo rather than your user config")
     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)
+            if args.scope == scopes.SCOPE_PROJECT:
+                info = store.uninstall_project(name)
+            else:
+                info = store.uninstall(name)
         except BoostError as err:
             if len(args.names) == 1:
                 raise
@@ -266,8 +308,15 @@ def cmd_uninstall(argv: List[str]) -> int:
             failed += 1
             continue
         if info["unlinked"]:
-            out.ok("unlinked ← %s" % " · ".join(info["unlinked"]))
-        out.ok("removed %s" % _tilde(dest))
+            verb = "removed from" if info.get("scope") == scopes.SCOPE_PROJECT \
+                else "unlinked ←"
+            out.ok("%s %s" % (verb, " · ".join(info["unlinked"])))
+        # Report where it actually went, not where a user-scope install would
+        # have put it — a project skill never touches the canonical store.
+        if info.get("scope") == scopes.SCOPE_PROJECT:
+            out.ok("removed from %s" % _tilde(info.get("base", "this repo")))
+        else:
+            out.ok("removed %s" % _tilde(store.skill_store_dir(name)))
         removed += 1
     if removed:
         lines = ["Uninstalled %s" % _plural(removed, "skill")]
@@ -299,14 +348,25 @@ def cmd_sync(argv: List[str]) -> int:
     ap.add_argument("--json", action="store_true", help="machine-readable output")
     args = ap.parse_args(argv)
     plan = store.sync_plan()
+    # A checkout can be missing skills its project lock records — that is the
+    # normal state right after `git clone` — so sync repairs the repo too.
+    pplan = store.project_sync_plan()
 
     if args.diff:
         if args.json:
-            print(json.dumps(plan, indent=2))
+            print(json.dumps(dict(plan, project=pplan), indent=2))
             return 0
-        if not any(plan.values()):
+        if not any(plan.values()) and not any(pplan.values()):
             out.ok("everything in sync")
             return 0
+        if pplan["missing"]:
+            out.heading("missing from this project (%d)" % len(pplan["missing"]))
+            for name, agent in pplan["missing"]:
+                out.info("%s → %s" % (name, agent))
+        if pplan["orphaned"]:
+            out.heading("unclaimed project skill dirs (%d)" % len(pplan["orphaned"]))
+            for item in pplan["orphaned"]:
+                out.info(_tilde(item))
         for key, label in _PLAN_LABELS:
             if not plan[key]:
                 continue
@@ -320,7 +380,7 @@ def cmd_sync(argv: List[str]) -> int:
                     out.info(_tilde(item))
         return 0
 
-    actions = store.sync_apply(plan)
+    actions = store.sync_apply(plan) + store.project_sync_apply(pplan)
     orphans = plan["orphaned_store"]
     pruned = []
     if args.prune and orphans:

boost_skill_cli-1.0.188/boost_cli/core/projectlock.py

@@ -0,0 +1,120 @@
+"""The per-project lock file: ``<repo>/.boost/skill-lock.json``.
+
+Project-scoped skills deliberately do **not** share the user lock. Two reasons,
+one practical and one about ownership:
+
+* Practical — roughly forty call sites across the command layer read the user
+  lock and then look the skill up at ``~/.agents/skills/<name>``. A project skill
+  does not live there, so putting it in that lock would hand every one of those
+  a path that does not exist.
+* Ownership — this file is meant to be **committed**. It is the record a teammate
+  gets from ``git clone``, which is the entire point of installing into the repo.
+
+So it is a small, self-contained document with the same shape as the user lock's
+``skills`` section and none of its machinery. In particular there is no history
+directory: the user lock snapshots itself on every write because nothing else
+would remember, whereas this file is versioned by the repo it lives in — git is
+its history, and duplicating that inside ``.boost/`` would just be litter in
+someone's diff.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from . import util
+
+SCHEMA_VERSION = 1
+LOCK_DIRNAME = ".boost"
+LOCK_FILENAME = "skill-lock.json"
+
+
+def lock_path(base) -> Path:
+    """Path of the project lock for the repo at ``base``."""
+    return Path(base) / LOCK_DIRNAME / LOCK_FILENAME
+
+
+def exists(base) -> bool:
+    """True when ``base`` already carries a project lock file."""
+    return lock_path(base).is_file()
+
+
+def _skeleton() -> dict:
+    return {"version": SCHEMA_VERSION, "updated": util.now_iso(), "skills": {}}
+
+
+def read(base) -> dict:
+    """Load the project lock, guaranteeing a ``skills`` key.
+
+    A missing file is simply an empty project. A corrupt one is preserved beside
+    itself as ``skill-lock.json.corrupt`` before falling back to the skeleton,
+    for the same reason the user lock does it: an unparseable file is not an
+    empty one, and the next write would otherwise erase the only record of what
+    the project had installed.
+    """
+    p = lock_path(base)
+    if not p.is_file():
+        return _skeleton()
+    try:
+        lock = json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        _preserve_corrupt(p)
+        return _skeleton()
+    if not isinstance(lock, dict):
+        _preserve_corrupt(p)
+        return _skeleton()
+    lock.setdefault("version", SCHEMA_VERSION)
+    skills = lock.get("skills")
+    lock["skills"] = skills if isinstance(skills, dict) else {}
+    return lock
+
+
+def _preserve_corrupt(p: Path) -> None:
+    """Copy an unparseable lock aside as ``.corrupt``; never raise."""
+    try:
+        import shutil
+        shutil.copy(p, p.with_name(p.name + ".corrupt"))
+    except OSError:
+        pass
+
+
+def write(base, lock: dict) -> None:
+    """Stamp version/updated onto ``lock`` and write it atomically."""
+    p = lock_path(base)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    lock["version"] = SCHEMA_VERSION
+    lock["updated"] = util.now_iso()
+    util.atomic_write_text(p, json.dumps(lock, indent=2, sort_keys=True) + "\n")
+
+
+def installed(base) -> dict:
+    """Return the project's ``{name: entry}`` mapping of installed skills."""
+    return read(base)["skills"]
+
+
+def get_skill(base, name: str) -> Optional[dict]:
+    """Return the project lock entry for ``name``, or None."""
+    return read(base)["skills"].get(name)
+
+
+def set_skill(base, name: str, entry: dict) -> None:
+    """Insert or replace the project lock entry for ``name`` and persist."""
+    lock = read(base)
+    lock["skills"][name] = entry
+    write(base, lock)
+
+
+def remove_skill(base, name: str) -> bool:
+    """Drop ``name`` from the project lock; True if it was present.
+
+    When the last skill goes the file is left in place (empty) rather than
+    deleted — it is a tracked file in someone's repo, and removing it would show
+    up as a spurious deletion in their next ``git status``.
+    """
+    lock = read(base)
+    if name in lock["skills"]:
+        del lock["skills"][name]
+        write(base, lock)
+        return True
+    return False