dataspring-cli 0.3.0__py3-none-any.whl

cli/skills_commands.py

@@ -0,0 +1,247 @@
+"""``dataspring skills``: list, get, install and diff the published skills.
+
+Mirrors ``tk skills`` (the ticks CLI). The skills are fetched from the server
+the CLI is configured for (``GET /api/skills``, ``GET /api/skills/{name}``),
+so what an agent installs is what that deployment serves: the parameter
+tables in a skill are generated from the server's own dispatch registry.
+``--offline`` reads the copy bundled in the wheel instead (the same trees,
+as of the CLI's build).
+
+``install`` writes a skill tree into the agent's skills directory
+(``~/.claude/skills/<name>/`` by default) with a ``.dataspring-skill`` stamp
+recording the version and where it came from. It refuses a non-empty
+directory without a stamp unless ``--force`` (it may be hand-edited or
+belong to something else) and replaces a stamped one in place, which is the
+upgrade path. ``diff`` compares an installed directory with the served tree.
+
+Exit codes follow tk's: 0 ok, 1 drift or a failed target, 2 usage (an
+unmanaged directory without --force), 4 no such skill.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Optional
+
+import httpx
+import typer
+
+from cli import skilltree
+from cli.output import console, print_error, print_warning
+
+EXIT_GENERIC = 1
+EXIT_USAGE = 2
+EXIT_NOT_FOUND = 4
+
+#: Tests set ``transport`` here to answer with a fake server.
+CLIENT_OPTIONS: dict = {}
+
+skills_app = typer.Typer(
+    help="Published skills: list, get, install into the agent's skills directory, diff",
+    no_args_is_help=True,
+)
+
+
+def default_skills_dir() -> Path:
+    return Path.home() / ".claude" / "skills"
+
+
+# ---------------------------------------------------------------------------
+# Where the trees come from
+# ---------------------------------------------------------------------------
+
+
+def _api_base() -> str:
+    from settings import get_settings
+
+    return get_settings().mcp_server_base_url.removesuffix("/api")
+
+
+def _get_json(path: str) -> dict:
+    url = f"{_api_base()}{path}"
+    with httpx.Client(timeout=30.0, **CLIENT_OPTIONS) as client:
+        response = client.get(url)
+    if response.status_code == 404:
+        detail = response.json().get("detail", "not found") if response.headers.get("content-type", "").startswith(
+            "application/json"
+        ) else response.text
+        raise skilltree.SkillNotFound(detail)
+    response.raise_for_status()
+    return response.json()
+
+
+class SkillSource:
+    """The server or the bundle: the same two questions either way."""
+
+    def __init__(self, offline: bool):
+        self.offline = offline
+        self.label = "bundled" if offline else _api_base()
+
+    def index(self) -> list[dict]:
+        if self.offline:
+            return [t.summary() for t in skilltree.bundled_library()]
+        return _get_json("/api/skills")["skills"]
+
+    def tree(self, name: str) -> skilltree.SkillTree:
+        if self.offline:
+            return skilltree.find_tree(name, skilltree.bundled_library())
+        return skilltree.SkillTree.from_dict(_get_json(f"/api/skills/{name}"))
+
+    def names(self) -> list[str]:
+        return [s["name"] for s in self.index()]
+
+
+def _source(offline: bool) -> SkillSource:
+    src = SkillSource(offline)
+    if offline and skilltree.bundled_root() is None:
+        print_error("This install carries no bundled skills; drop --offline to fetch them from the server")
+        raise typer.Exit(EXIT_GENERIC)
+    return src
+
+
+def _fail_network(exc: Exception) -> None:
+    print_error(f"Could not reach the DataSpring server for skills: {exc}", hint="Try --offline for the bundled copy")
+    raise typer.Exit(EXIT_GENERIC)
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+
+OfflineOpt = Annotated[bool, typer.Option("--offline", help="Use the skills bundled in this CLI, not the server's")]
+DirOpt = Annotated[
+    Optional[Path],
+    typer.Option("--dir", help="The skills directory (each skill goes in <dir>/<name>/); default ~/.claude/skills"),
+]
+
+
+@skills_app.command("list")
+def skills_list(offline: OfflineOpt = False, as_json: Annotated[bool, typer.Option("--json")] = False):
+    """List the skills the server (or the bundle) serves, with their versions."""
+    src = _source(offline)
+    try:
+        rows = src.index()
+    except httpx.HTTPError as e:
+        _fail_network(e)
+    if as_json:
+        typer.echo(json.dumps({"source": src.label, "skills": rows}, indent=2))
+        return
+    for row in rows:
+        typer.echo(f"{row['name']}\t{row['version']}\t{row['description']}")
+    if not rows:
+        print_warning("No skills served")
+
+
+@skills_app.command("get")
+def skills_get(
+    name: Annotated[str, typer.Argument(help="Skill name (dataspring-consume, or just consume)")],
+    offline: OfflineOpt = False,
+    full: Annotated[bool, typer.Option("--full", help="Print every file in the tree, not only SKILL.md")] = False,
+):
+    """Print a skill's SKILL.md (or the whole tree with --full)."""
+    src = _source(offline)
+    tree = _tree_or_exit(src, name)
+    files = list(tree.files) if full else [f for f in tree.files if f.path == "SKILL.md"]
+    for i, f in enumerate(files):
+        if i:
+            typer.echo(f"\n--- {f.path} ---\n")
+        typer.echo(f.content, nl=not f.content.endswith("\n"))
+
+
+def _tree_or_exit(src: SkillSource, name: str) -> skilltree.SkillTree:
+    try:
+        return src.tree(name)
+    except skilltree.SkillNotFound as e:
+        print_error(str(e))
+        raise typer.Exit(EXIT_NOT_FOUND)
+    except httpx.HTTPError as e:
+        _fail_network(e)
+        raise AssertionError("unreachable")
+
+
+def _selected(src: SkillSource, name: str | None, all_: bool) -> list[str]:
+    if bool(name) == all_:
+        print_error("Name one skill, or pass --all")
+        raise typer.Exit(EXIT_USAGE)
+    if all_:
+        try:
+            return src.names()
+        except httpx.HTTPError as e:
+            _fail_network(e)
+    return [name]  # type: ignore[list-item]
+
+
+@skills_app.command("install")
+def skills_install(
+    name: Annotated[Optional[str], typer.Argument(help="Skill name; or --all")] = None,
+    all_: Annotated[bool, typer.Option("--all", help="Install every served skill")] = False,
+    dir: DirOpt = None,
+    force: Annotated[bool, typer.Option("--force", help="Replace a directory that has no DataSpring stamp")] = False,
+    offline: OfflineOpt = False,
+):
+    """Install a skill tree into the agent's skills directory, stamped.
+
+    Re-running over a stamped directory upgrades it in place.
+    """
+    src = _source(offline)
+    root = dir or default_skills_dir()
+    failed = 0
+    code = 0
+    for skill_name in _selected(src, name, all_):
+        tree = _tree_or_exit(src, skill_name)
+        target = root / tree.name
+        try:
+            stamp = skilltree.install_tree(tree, target, source=src.label, force=force)
+        except skilltree.UnmanagedDirectory as e:
+            failed += 1
+            code = code or EXIT_USAGE
+            typer.echo(f"refused {target}: {e} (pass --force to replace it)")
+            continue
+        except OSError as e:
+            failed += 1
+            code = EXIT_GENERIC
+            typer.echo(f"failed {target}: {e}")
+            continue
+        typer.echo(f"installed {tree.name} {stamp.version} to {target}")
+    if failed:
+        print_error(f"{failed} skill install target(s) failed")
+        raise typer.Exit(code)
+
+
+@skills_app.command("diff")
+def skills_diff(
+    name: Annotated[Optional[str], typer.Argument(help="Skill name; default: every installed skill")] = None,
+    dir: DirOpt = None,
+    offline: OfflineOpt = False,
+):
+    """Show drift between the installed skills and the served ones.
+
+    Exit 1 on any drift: a changed, added or removed file, or a stamp whose
+    version is not the served one.
+    """
+    src = _source(offline)
+    root = dir or default_skills_dir()
+    if name:
+        trees = [_tree_or_exit(src, name)]
+    else:
+        installed = sorted(p.name for p in root.iterdir() if skilltree.read_stamp(p)) if root.is_dir() else []
+        if not installed:
+            print_warning(f"No DataSpring-stamped skills under {root}")
+            raise typer.Exit(EXIT_GENERIC)
+        trees = [_tree_or_exit(src, n) for n in installed]
+    drift = False
+    for tree in trees:
+        target = root / tree.name
+        try:
+            diff = skilltree.diff_tree(tree, target)
+        except FileNotFoundError:
+            typer.echo(f"{tree.name}: not installed at {target}")
+            drift = True
+            continue
+        typer.echo(diff.render())
+        drift = drift or not diff.ok()
+    if drift:
+        console.print("[yellow]drift detected; `dataspring skills install --all` brings the copies up to date[/]")
+        raise typer.Exit(EXIT_GENERIC)

cli/skilltree.py

@@ -0,0 +1,350 @@
+"""A skill as a tree of files, the same on every surface.
+
+The one description of what a skill *is* once it leaves ``backend/skills/``:
+its name and description (the SKILL.md frontmatter), every file under its
+directory, and a ``version`` that is a hash of that content. The server's
+``GET /api/skills[/{name}]`` and the ``dataspring://skills/{name}`` resource
+serialize this shape; ``dataspring skills install`` writes it to disk with a
+stamp, ``dataspring skills diff`` compares the two. Because both ends hash
+the same bytes the same way, an installed tree and a served one agree on
+their version without either trusting the other's clock.
+
+This module ships in the CLI wheel, so it imports nothing from the server
+(tests/test_cli_thin_client.py); the server imports it, the way the D19
+note describes the shared contract package: code that is only data.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+#: The marker ``skills install`` writes at the root of every tree it installs.
+#: Its presence is what makes a directory DataSpring-managed: install refuses
+#: to replace a non-empty directory without it unless forced.
+STAMP_FILE = ".dataspring-skill"
+
+#: Vendor prefix of every published skill (``dataspring-consume``).
+NAME_PREFIX = "dataspring-"
+
+#: The bundled copy the wheel ships (written by ``backend/hatch_build.py`` at
+#: build time from ``backend/skills/``), relative to this package.
+_BUNDLED_SUBDIR = "_skills"
+
+
+@dataclass(frozen=True)
+class SkillFile:
+    path: str  # slash-separated, relative to the skill root: "SKILL.md"
+    content: str
+
+
+@dataclass(frozen=True)
+class SkillTree:
+    name: str
+    description: str
+    version: str
+    files: tuple[SkillFile, ...]
+
+    @property
+    def skill_md(self) -> str:
+        return next(f.content for f in self.files if f.path == "SKILL.md")
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "description": self.description,
+            "version": self.version,
+            "files": [{"path": f.path, "content": f.content} for f in self.files],
+        }
+
+    def summary(self) -> dict:
+        """The index row: everything but the file contents."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "version": self.version,
+            "files": [f.path for f in self.files],
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "SkillTree":
+        files = tuple(
+            sorted(
+                (SkillFile(path=f["path"], content=f["content"]) for f in data["files"]),
+                key=lambda f: f.path,
+            )
+        )
+        return cls(
+            name=data["name"],
+            description=data.get("description", ""),
+            version=data.get("version") or tree_version(files),
+            files=files,
+        )
+
+
+class SkillNotFound(LookupError):
+    """No skill of that name in the library at hand."""
+
+
+class UnmanagedDirectory(Exception):
+    """The install target exists, is not empty, and carries no stamp."""
+
+
+# ---------------------------------------------------------------------------
+# Reading a library from disk
+# ---------------------------------------------------------------------------
+
+
+def parse_frontmatter(text: str) -> tuple[str, str]:
+    """``(name, description)`` from a SKILL.md's ``---`` block."""
+    lines = text.split("\n")
+    if not lines or lines[0].strip() != "---":
+        raise ValueError("SKILL.md is missing its leading frontmatter delimiter")
+    closing = next((i for i in range(1, len(lines)) if lines[i].strip() == "---"), None)
+    if closing is None:
+        raise ValueError("SKILL.md is missing its closing frontmatter delimiter")
+    fm = yaml.safe_load("\n".join(lines[1:closing])) or {}
+    name = fm.get("name")
+    if not name:
+        raise ValueError("SKILL.md frontmatter has no 'name'")
+    return str(name), str(fm.get("description") or "")
+
+
+def tree_version(files: tuple[SkillFile, ...] | list[SkillFile]) -> str:
+    """SHA-256 over every file's path and content, in path order; 16 hex chars.
+
+    The stamp file is never part of it (it records the version, so it
+    cannot be an input to it).
+    """
+    digest = hashlib.sha256()
+    for f in sorted(files, key=lambda f: f.path):
+        digest.update(f.path.encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(f.content.encode("utf-8"))
+        digest.update(b"\0")
+    return digest.hexdigest()[:16]
+
+
+def _tree_files(directory: Path) -> tuple[SkillFile, ...]:
+    files: list[SkillFile] = []
+    for path in sorted(directory.rglob("*")):
+        if not path.is_file():
+            continue
+        rel = path.relative_to(directory).as_posix()
+        if rel == STAMP_FILE or any(part.startswith(".") for part in rel.split("/")):
+            continue
+        files.append(SkillFile(path=rel, content=path.read_text(encoding="utf-8")))
+    return tuple(files)
+
+
+def read_tree(directory: Path) -> SkillTree:
+    """The skill at ``directory`` (which must hold a SKILL.md)."""
+    directory = Path(directory)
+    skill_md = directory / "SKILL.md"
+    if not skill_md.is_file():
+        raise SkillNotFound(f"{directory} has no SKILL.md")
+    files = _tree_files(directory)
+    name, description = parse_frontmatter(skill_md.read_text(encoding="utf-8"))
+    return SkillTree(name=name, description=description, version=tree_version(files), files=files)
+
+
+def read_library(root: Path) -> list[SkillTree]:
+    """Every ``<root>/<name>/SKILL.md`` skill, sorted by name."""
+    root = Path(root)
+    if not root.is_dir():
+        return []
+    trees = [read_tree(child) for child in sorted(root.iterdir()) if (child / "SKILL.md").is_file()]
+    return sorted(trees, key=lambda t: t.name)
+
+
+def resolve_name(name: str, available: list[str]) -> str:
+    """``consume`` and ``dataspring-consume`` both name the same skill."""
+    if name in available:
+        return name
+    prefixed = NAME_PREFIX + name
+    if prefixed in available:
+        return prefixed
+    raise SkillNotFound(f"No skill named '{name}'. Available: {', '.join(available) or '(none)'}")
+
+
+def find_tree(name: str, trees: list[SkillTree]) -> SkillTree:
+    resolved = resolve_name(name, [t.name for t in trees])
+    return next(t for t in trees if t.name == resolved)
+
+
+# ---------------------------------------------------------------------------
+# The copy the wheel ships
+# ---------------------------------------------------------------------------
+
+
+def bundled_root() -> Path | None:
+    """Where the bundled skills are, or ``None`` when this install has none.
+
+    A built wheel carries ``cli/_skills/`` (the build hook copies
+    ``backend/skills/`` there); a checkout runs against ``backend/skills/``
+    itself, so there is never a second checked-in copy.
+    """
+    here = Path(__file__).resolve().parent
+    for candidate in (here / _BUNDLED_SUBDIR, here.parent / "skills"):
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def bundled_library() -> list[SkillTree]:
+    root = bundled_root()
+    return read_library(root) if root else []
+
+
+# ---------------------------------------------------------------------------
+# Installing, stamping, diffing
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Stamp:
+    skill: str
+    version: str
+    source: str  # the server URL the tree came from, or "bundled"
+    installed_at: str
+
+    def to_dict(self) -> dict:
+        return {
+            "skill": self.skill,
+            "version": self.version,
+            "source": self.source,
+            "installed_at": self.installed_at,
+        }
+
+
+def read_stamp(directory: Path) -> Stamp | None:
+    """The stamp at the root of ``directory``, or ``None`` when there is none
+    (never installed by DataSpring) or it is unreadable."""
+    path = Path(directory) / STAMP_FILE
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return Stamp(
+            skill=str(data["skill"]),
+            version=str(data["version"]),
+            source=str(data.get("source", "")),
+            installed_at=str(data.get("installed_at", "")),
+        )
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+
+
+def _is_managed(directory: Path) -> bool:
+    """Safe to replace without --force: empty, or carrying a stamp."""
+    try:
+        entries = list(directory.iterdir())
+    except OSError:
+        return False
+    return not entries or (directory / STAMP_FILE).is_file()
+
+
+def install_tree(tree: SkillTree, directory: Path, *, source: str, force: bool = False) -> Stamp:
+    """Write ``tree`` to ``directory``, replacing whatever is there.
+
+    Refuses a directory that exists, is non-empty and has no stamp
+    (``UnmanagedDirectory``) unless ``force``. The new tree is written to a
+    temporary sibling first and renamed into place, so a crash leaves either
+    the old tree or the new one, never half of each. Nothing from the old
+    tree survives: an upgrade of a stamped directory drops hand-added extras.
+    """
+    directory = Path(directory)
+    if directory.exists() and not directory.is_dir():
+        raise NotADirectoryError(f"{directory} exists and is not a directory")
+    exists = directory.is_dir()
+    if exists and not force and not _is_managed(directory):
+        raise UnmanagedDirectory(
+            f"{directory} exists and is not DataSpring-managed (no {STAMP_FILE} stamp)"
+        )
+
+    parent = directory.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    # Sweep a temp tree a crashed install left behind: it holds a complete
+    # SKILL.md and a harness may load it as a second copy of the skill.
+    for stale in parent.glob(directory.name + ".dataspring-tmp-*"):
+        shutil.rmtree(stale, ignore_errors=True)
+
+    tmp = Path(tempfile.mkdtemp(prefix=directory.name + ".dataspring-tmp-", dir=parent))
+    try:
+        for f in tree.files:
+            dest = tmp / Path(*f.path.split("/"))
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(f.content, encoding="utf-8")
+        stamp = Stamp(
+            skill=tree.name,
+            version=tree.version,
+            source=source,
+            installed_at=datetime.now(timezone.utc).isoformat(timespec="seconds"),
+        )
+        (tmp / STAMP_FILE).write_text(json.dumps(stamp.to_dict(), indent=2) + "\n", encoding="utf-8")
+        if exists:
+            shutil.rmtree(directory)
+        os.rename(tmp, directory)
+    except BaseException:
+        shutil.rmtree(tmp, ignore_errors=True)
+        raise
+    return stamp
+
+
+@dataclass(frozen=True)
+class SkillDiff:
+    """An installed directory against a served (or bundled) tree."""
+
+    name: str
+    added: tuple[str, ...]  # on disk, not in the tree
+    removed: tuple[str, ...]  # in the tree, not on disk
+    changed: tuple[str, ...]  # in both, different bytes
+    stamp_version: str | None  # None: unstamped
+    served_version: str
+
+    def ok(self) -> bool:
+        return (
+            not self.added
+            and not self.removed
+            and not self.changed
+            and self.stamp_version is not None
+            and self.stamp_version == self.served_version
+        )
+
+    def render(self) -> str:
+        if self.ok():
+            return f"{self.name}: no drift (version {self.served_version})"
+        installed = self.stamp_version or "(unstamped)"
+        lines = [f"{self.name}: drift, installed={installed} served={self.served_version}"]
+        for label, paths in (("added", self.added), ("removed", self.removed), ("changed", self.changed)):
+            if paths:
+                lines.append(f"  {label} ({len(paths)}):")
+                lines.extend(f"    {p}" for p in paths)
+        return "\n".join(lines)
+
+
+def diff_tree(tree: SkillTree, directory: Path) -> SkillDiff:
+    """Compare ``directory`` with ``tree``; a missing directory is an error."""
+    directory = Path(directory)
+    if not directory.is_dir():
+        raise FileNotFoundError(f"{directory} is not an installed skill directory")
+    on_disk = {f.path: f.content for f in _tree_files(directory)}
+    served = {f.path: f.content for f in tree.files}
+    removed = sorted(p for p in served if p not in on_disk)
+    changed = sorted(p for p in served if p in on_disk and on_disk[p] != served[p])
+    added = sorted(p for p in on_disk if p not in served)
+    stamp = read_stamp(directory)
+    return SkillDiff(
+        name=tree.name,
+        added=tuple(added),
+        removed=tuple(removed),
+        changed=tuple(changed),
+        stamp_version=stamp.version if stamp else None,
+        served_version=tree.version,
+    )

cli/upgrade.py

@@ -0,0 +1,66 @@
+"""``dataspring upgrade``: upgrade the CLI in place, however it was installed.
+
+Three installers put ``dataspring`` on a machine and each upgrades its own
+way; the install script uses ``uv tool``. The method is read off
+``sys.executable``: a uv tool's interpreter lives under ``.../uv/tools/
+dataspring-cli/``, pipx's under ``.../pipx/venvs/dataspring-cli/``, and
+anything else is a plain pip install into whatever environment this is.
+``--check`` only compares the installed version with PyPI's latest.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+import httpx
+
+from cli.version import DIST, cli_version
+
+PYPI_JSON = f"https://pypi.org/pypi/{DIST}/json"
+
+
+def detect_install_method(executable: str | None = None) -> str:
+    """``"uv"``, ``"pipx"`` or ``"pip"``."""
+    parts = Path(executable or sys.executable).resolve().parts
+    if "tools" in parts and DIST in parts:
+        return "uv"
+    if "pipx" in parts and DIST in parts:
+        return "pipx"
+    return "pip"
+
+
+def upgrade_command(method: str) -> list[str]:
+    if method == "uv":
+        return ["uv", "tool", "upgrade", DIST]
+    if method == "pipx":
+        return ["pipx", "upgrade", DIST]
+    return [sys.executable, "-m", "pip", "install", "--upgrade", DIST]
+
+
+def installed_version_after_upgrade() -> str:
+    """Ask the (possibly replaced) interpreter, not this process's cached metadata."""
+    result = subprocess.run(
+        [sys.executable, "-c", f"from importlib.metadata import version; print(version({DIST!r}))"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return result.stdout.strip() or cli_version()
+
+
+def latest_pypi_version() -> str:
+    with httpx.Client(timeout=15.0) as client:
+        response = client.get(PYPI_JSON)
+    response.raise_for_status()
+    return response.json()["info"]["version"]
+
+
+def _key(version: str) -> tuple[int, ...]:
+    return tuple(int(n) for n in re.findall(r"\d+", version)) or (0,)
+
+
+def is_newer(candidate: str, current: str) -> bool:
+    return _key(candidate) > _key(current)