skillmate 12.0.1.dev147__py3-none-any.whl

skillmate/distribution.py

@@ -0,0 +1,216 @@
+"""The portable distribution model and its sources.
+
+A distribution is a directory (remote base URL or local path) holding an
+``index.json`` in the published Pages schema and content-addressed skill
+archives under ``archives/sha256/``. Sources never fall back to each
+other: an unreachable, malformed, or unpinned source is a loud error.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import tarfile
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import TYPE_CHECKING
+from urllib.parse import urljoin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping, Sequence
+
+INDEX_SCHEMA = "@kisev/skills/index/v1"
+DEFAULT_INDEX_URL = "https://kisev.github.io/skills/index.json"
+
+
+class DistributionError(Exception):
+    """An unreachable, malformed, or integrity-failing distribution source."""
+
+
+@dataclass(frozen=True)
+class SkillEntry:
+    """One skill in the distribution index."""
+
+    name: str
+    archive: str
+    sha256: str
+
+
+@dataclass(frozen=True)
+class Distribution:
+    """A parsed distribution index."""
+
+    package: str
+    version: str
+    source_revision: str
+    skills: Mapping[str, SkillEntry]
+
+    def require_version(self, pin: str) -> None:
+        """Fail loudly unless the distribution carries exactly the pinned version."""
+        if self.version != pin:
+            raise DistributionError(
+                f"distribution version {self.version} does not match the pinned {pin}"
+            )
+
+
+@dataclass(frozen=True)
+class ArchiveFile:
+    """One regular file extracted from a skill archive, as bytes."""
+
+    path: str
+    data: bytes
+
+
+@dataclass(frozen=True)
+class SkillArchive:
+    """A verified, fully extracted skill archive."""
+
+    name: str
+    sha256: str
+    files: tuple[ArchiveFile, ...]
+
+
+def parse_index(text: str) -> Distribution:
+    """Parse and validate an index document against the published schema."""
+    try:
+        document = json.loads(text)
+    except json.JSONDecodeError as error:
+        raise DistributionError(f"index is not valid JSON: {error}") from error
+    if not isinstance(document, dict):
+        raise DistributionError("index must be a JSON object")
+    schema = document.get("schema")
+    if schema != INDEX_SCHEMA:
+        raise DistributionError(f"unsupported index schema {schema!r}, expected {INDEX_SCHEMA!r}")
+    package = document.get("package")
+    version = document.get("version")
+    revision = document.get("source_revision")
+    entries = document.get("skills")
+    if (
+        not isinstance(package, str)
+        or not isinstance(version, str)
+        or not isinstance(revision, str)
+    ):
+        raise DistributionError("index fields package, version, source_revision must be strings")
+    if not isinstance(entries, list):
+        raise DistributionError("index field skills must be a list")
+    skills: dict[str, SkillEntry] = {}
+    for entry in entries:
+        if not isinstance(entry, dict):
+            raise DistributionError("each skill entry must be a JSON object")
+        name = entry.get("name")
+        archive = entry.get("archive")
+        sha256 = entry.get("sha256")
+        if not (
+            isinstance(name, str)
+            and isinstance(archive, str)
+            and isinstance(sha256, str)
+            and name
+            and archive
+            and len(sha256) == 64
+        ):
+            raise DistributionError(f"skill entry {name!r} has invalid name, archive, or sha256")
+        if name in skills:
+            raise DistributionError(f"duplicate skill name {name!r} in index")
+        archive_path = PurePosixPath(archive)
+        if archive_path.is_absolute() or ".." in archive_path.parts:
+            raise DistributionError(f"skill entry {name!r} has an escaping archive path")
+        skills[name] = SkillEntry(name=name, archive=archive, sha256=sha256)
+    return Distribution(package=package, version=version, source_revision=revision, skills=skills)
+
+
+def extract_archive(name: str, sha256: str, blob: bytes) -> SkillArchive:
+    """Verify an archive's digest and extract every member in memory.
+
+    Only regular files under the archive root are accepted; absolute
+    paths, ``..`` segments, and non-regular members are rejected.
+    """
+    digest = hashlib.sha256(blob).hexdigest()
+    if digest != sha256:
+        raise DistributionError(
+            f"archive for {name!r} failed integrity: expected {sha256}, got {digest}"
+        )
+    files: list[ArchiveFile] = []
+    seen: set[str] = set()
+    try:
+        with tarfile.open(fileobj=io.BytesIO(blob), mode="r:gz") as archive:
+            members: Sequence[tarfile.TarInfo] = archive.getmembers()
+            for member in members:
+                if member.isdir():
+                    continue
+                if not member.isfile():
+                    raise DistributionError(
+                        f"archive for {name!r} contains a non-regular member {member.name!r}"
+                    )
+                member_path = PurePosixPath(member.name)
+                if member_path.is_absolute() or ".." in member_path.parts or not member.name:
+                    raise DistributionError(
+                        f"archive for {name!r} contains an escaping member path {member.name!r}"
+                    )
+                if member.name in seen:
+                    raise DistributionError(
+                        f"archive for {name!r} contains duplicate member {member.name!r}"
+                    )
+                extracted = archive.extractfile(member)
+                if extracted is None:  # pragma: no cover - guarded by isfile
+                    raise DistributionError(f"member {member.name!r} of {name!r} unreadable")
+                seen.add(member.name)
+                files.append(ArchiveFile(path=member.name, data=extracted.read()))
+    except tarfile.TarError as error:
+        raise DistributionError(
+            f"archive for {name!r} is not a readable tar.gz: {error}"
+        ) from error
+    return SkillArchive(name=name, sha256=sha256, files=tuple(files))
+
+
+def _default_fetch(url: str) -> bytes:
+    try:
+        with urllib.request.urlopen(url, timeout=30) as response:  # noqa: S310
+            blob: bytes = response.read()
+            return blob
+    except (urllib.error.URLError, OSError) as error:
+        raise DistributionError(f"cannot fetch {url}: {error}") from error
+
+
+@dataclass(frozen=True)
+class RemoteSource:
+    """The primary source: the published Pages distribution over HTTP(S).
+
+    ``fetch`` exists so tests can serve the same layout offline.
+    """
+
+    index_url: str = DEFAULT_INDEX_URL
+    fetch: Callable[[str], bytes] = _default_fetch
+
+    def index(self) -> Distribution:
+        return parse_index(self.fetch(self.index_url).decode("utf-8"))
+
+    def archive(self, entry: SkillEntry) -> SkillArchive:
+        blob = self.fetch(urljoin(self.index_url, entry.archive))
+        return extract_archive(entry.name, entry.sha256, blob)
+
+
+@dataclass(frozen=True)
+class LocalSource:
+    """A distribution directory: the layout of a checkout build or a mirror."""
+
+    base: Path
+
+    def index(self) -> Distribution:
+        index_path = self.base / "index.json"
+        try:
+            return parse_index(index_path.read_text(encoding="utf-8"))
+        except OSError as error:
+            raise DistributionError(f"cannot read {index_path}: {error}") from error
+
+    def archive(self, entry: SkillEntry) -> SkillArchive:
+        archive_path = self.base / entry.archive
+        if not archive_path.is_relative_to(self.base):
+            raise DistributionError(f"archive path {entry.archive!r} escapes the source directory")
+        try:
+            blob = archive_path.read_bytes()
+        except OSError as error:
+            raise DistributionError(f"cannot read {archive_path}: {error}") from error
+        return extract_archive(entry.name, entry.sha256, blob)

skillmate/installer.py

@@ -0,0 +1,301 @@
+"""Lifecycle orchestration: sources, adapters, and plans per host.
+
+The CLI layer resolves a source, asks the adapters for each host's desired
+state, and turns it into safety-model plans. Nothing here writes: plans are
+executed by :mod:`skillmate.safety` after confirmation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+    from pathlib import Path
+
+from skillmate.adapters import ADAPTERS, HostAdapter, install_notices
+from skillmate.checkout import CheckoutSource
+from skillmate.content import SkillContent, skill_content
+from skillmate.distribution import (
+    Distribution,
+    DistributionError,
+    RemoteSource,
+    SkillArchive,
+    SkillEntry,
+)
+from skillmate.safety import (
+    Plan,
+    build_install_plan,
+    build_remove_plan,
+    disk_digest,
+    load_ownership,
+)
+
+Scope = str  # "project" | "global"
+
+
+@dataclass(frozen=True)
+class SourceSelection:
+    """A resolved content source: the index plus an archive reader."""
+
+    distribution: Distribution
+    archive: Callable[[SkillEntry], SkillArchive]
+    label: str
+
+    def contents(self, names: tuple[str, ...] | None = None) -> tuple[SkillContent, ...]:
+        selected = (
+            [self.distribution.skills[name] for name in names]
+            if names
+            else list(self.distribution.skills.values())
+        )
+        return tuple(skill_content(self.archive(entry)) for entry in selected)
+
+
+def resolve_source(
+    from_checkout: Path | None, index_url: str, target_version: str | None
+) -> SourceSelection:
+    """Resolve the one source in play; no source falls back to another."""
+    if from_checkout is not None:
+        distribution, local = CheckoutSource(checkout=from_checkout).resolve()
+        if target_version is not None:
+            distribution.require_version(target_version)
+        return SourceSelection(distribution=distribution, archive=local.archive, label="checkout")
+    remote = RemoteSource(index_url=index_url)
+    distribution = remote.index()
+    if target_version is not None:
+        distribution.require_version(target_version)
+    return SourceSelection(distribution=distribution, archive=remote.archive, label="distribution")
+
+
+def host_root(adapter: HostAdapter, scope: str, project: Path, home: Path) -> Path:
+    """The directory a host reads (for example ``<project>/.claude``)."""
+    if scope == "global":
+        return home / adapter.skills_global.parent
+    return project / adapter.skills_project.parent
+
+
+def _adapters(hosts: tuple[str, ...]) -> tuple[HostAdapter, ...]:
+    unknown = [host for host in hosts if host not in ADAPTERS]
+    if unknown:
+        raise DistributionError(f"unknown hosts: {', '.join(unknown)}")
+    return tuple(ADAPTERS[host] for host in hosts)
+
+
+def desired_state(
+    adapter: HostAdapter, contents: tuple[SkillContent, ...], known_names: frozenset[str]
+) -> dict[str, bytes]:
+    """The full desired file set of one host: skills plus command surfaces."""
+    desired: dict[str, bytes] = {}
+    for content in contents:
+        for file in adapter.materialize(content, known_names):
+            desired[f"skills/{content.name}/{file.path}"] = file.data
+        document = adapter.command_document(content)
+        if document is not None:
+            desired[f"commands/{content.name}.md"] = document.encode("utf-8")
+    return desired
+
+
+def plan_install(
+    selection: SourceSelection,
+    hosts: tuple[str, ...],
+    scope: str,
+    project: Path,
+    home: Path,
+    skill_names: tuple[str, ...] | None = None,
+) -> tuple[Plan, ...]:
+    """Build one install/update plan per selected host."""
+    names = tuple(sorted(selection.distribution.skills)) if skill_names is None else skill_names
+    missing = [name for name in names if name not in selection.distribution.skills]
+    if missing:
+        raise DistributionError(f"unknown skills: {', '.join(missing)}")
+    contents = selection.contents(names)
+    known = frozenset(selection.distribution.skills)
+    notices = install_notices(hosts)
+    plans: list[Plan] = []
+    for adapter in _adapters(hosts):
+        root = host_root(adapter, scope, project, home)
+        desired = desired_state(adapter, contents, known)
+        plans.append(
+            build_install_plan(
+                root,
+                desired,
+                load_ownership(root),
+                selection.distribution.version,
+                selection.label,
+                notices=notices,
+            )
+        )
+    return tuple(plans)
+
+
+def plan_remove(
+    hosts: tuple[str, ...], scope: str, project: Path, home: Path
+) -> tuple[tuple[str, Plan | None], ...]:
+    """Build one removal plan per selected host; ``None`` marks no install."""
+    results: list[tuple[str, Plan | None]] = []
+    for adapter in _adapters(hosts):
+        root = host_root(adapter, scope, project, home)
+        ownership = load_ownership(root)
+        if ownership is None:
+            results.append((adapter.host, None))
+            continue
+        results.append((adapter.host, build_remove_plan(root, ownership)))
+    return tuple(results)
+
+
+@dataclass(frozen=True)
+class Diagnosis:
+    """One doctor finding: what is wrong, where, and how to repair it."""
+
+    host: str
+    scope: str
+    kind: str
+    detail: str
+    repair: str
+
+
+@dataclass(frozen=True)
+class InstallRecord:
+    """One installed host and scope, as status reports it."""
+
+    host: str
+    scope: str
+    version: str
+    source: str
+    files: int
+
+
+def status(
+    hosts: tuple[str, ...], scope: str, project: Path, home: Path
+) -> tuple[InstallRecord, ...]:
+    """Read the installed versions per host and scope."""
+    records: list[InstallRecord] = []
+    for adapter in _adapters(hosts):
+        root = host_root(adapter, scope, project, home)
+        ownership = load_ownership(root)
+        if ownership is None:
+            continue
+        records.append(
+            InstallRecord(
+                host=adapter.host,
+                scope=scope,
+                version=ownership.distribution_version,
+                source=ownership.source,
+                files=len(ownership.files),
+            )
+        )
+    return tuple(records)
+
+
+def doctor(
+    hosts: tuple[str, ...],
+    scope: str,
+    project: Path,
+    home: Path,
+    selection: SourceSelection | None,
+) -> tuple[Diagnosis, ...]:
+    """Diagnose each installation without writing anything.
+
+    Names missing files, version drift against the distribution, user
+    drift, stale ownership records, and foreign files occupying
+    distribution paths, each with its exact repair.
+    """
+    diagnoses: list[Diagnosis] = []
+    for adapter in _adapters(hosts):
+        root = host_root(adapter, scope, project, home)
+        ownership = load_ownership(root)
+        if ownership is None:
+            diagnoses.append(
+                Diagnosis(
+                    host=adapter.host,
+                    scope=scope,
+                    kind="not-installed",
+                    detail=f"no installation recorded under {root}",
+                    repair="run skillmate install",
+                )
+            )
+            continue
+        desired = None
+        if selection is not None:
+            try:
+                contents = selection.contents()
+                known = frozenset(selection.distribution.skills)
+                desired = desired_state(adapter, contents, known)
+            except DistributionError as error:
+                diagnoses.append(
+                    Diagnosis(
+                        host=adapter.host,
+                        scope=scope,
+                        kind="source-unavailable",
+                        detail=str(error),
+                        repair="check network or pass --from-checkout",
+                    )
+                )
+        for owned in ownership.files:
+            disk = disk_digest(root, owned.path)
+            if disk is None:
+                diagnoses.append(
+                    Diagnosis(
+                        host=adapter.host,
+                        scope=scope,
+                        kind="missing-file",
+                        detail=owned.path,
+                        repair=f"skillmate update --hosts {adapter.host}",
+                    )
+                )
+            elif disk != owned.sha256:
+                diagnoses.append(
+                    Diagnosis(
+                        host=adapter.host,
+                        scope=scope,
+                        kind="drifted-file",
+                        detail=f"{owned.path} differs from the recorded digest",
+                        repair="restore it or reconfirm the change with skillmate update",
+                    )
+                )
+        if (
+            selection is not None
+            and ownership.distribution_version != selection.distribution.version
+        ):
+            diagnoses.append(
+                Diagnosis(
+                    host=adapter.host,
+                    scope=scope,
+                    kind="version-drift",
+                    detail=(
+                        f"installed {ownership.distribution_version}, "
+                        f"distribution {selection.distribution.version}"
+                    ),
+                    repair=f"skillmate update --hosts {adapter.host}",
+                )
+            )
+        if desired is not None:
+            recorded = ownership.by_path()
+            stale = [path for path in recorded if path not in desired]
+            if stale:
+                diagnoses.append(
+                    Diagnosis(
+                        host=adapter.host,
+                        scope=scope,
+                        kind="stale-record",
+                        detail=f"{len(stale)} owned files are no longer part of the distribution",
+                        repair=f"skillmate update --hosts {adapter.host}",
+                    )
+                )
+            for path in sorted(desired):
+                if path in recorded or disk_digest(root, path) is None:
+                    continue
+                diagnoses.append(
+                    Diagnosis(
+                        host=adapter.host,
+                        scope=scope,
+                        kind="foreign-path",
+                        detail=f"{path} is not owned by skillmate",
+                        repair=(
+                            "remove or move it away, then run "
+                            f"skillmate update --hosts {adapter.host}"
+                        ),
+                    )
+                )
+    return tuple(diagnoses)