agentsquire 0.2.2__py3-none-any.whl

agentsquire/__init__.py

@@ -0,0 +1,100 @@
+"""AgentSquire: ship agent integrations inside a Python package and install
+them into whatever agent harness is present.
+
+The full lifecycle is available as plain Python (REQ-16), no CLI required:
+enumerate skills from a source, detect harnesses, then install / status /
+update / uninstall. See docs/api.md for the reference.
+"""
+
+__version__ = "0.2.2"
+
+from agentsquire.harnesses import (
+    CLAUDE_CODE,
+    HERMES,
+    OPENCODE,
+    PI,
+    HarnessBackend,
+    HarnessNotDetectedError,
+    HarnessRegistry,
+    UnknownHarnessError,
+    UnsupportedScopeError,
+    default_registry,
+)
+from agentsquire.hashing import STAMP_KEY, skill_content_hash
+from agentsquire.skills import (
+    InvalidSkillError,
+    Skill,
+    SkillViolation,
+    load_skill,
+    validate_skill_dir,
+)
+from agentsquire.sources import (
+    ENTRY_POINT_GROUP,
+    BundledPackageDataSource,
+    DirectorySource,
+    SkillSource,
+    SourceSkill,
+)
+from agentsquire.staleness import check_stale
+from agentsquire.stamping import StampError, read_stamp
+from agentsquire.verbs import (
+    InstalledSkill,
+    InstallResult,
+    RemovedSkill,
+    SkillState,
+    SkillStatus,
+    SkippedSkill,
+    UninstallResult,
+    UpdateResult,
+    install,
+    status,
+    uninstall,
+    update,
+)
+
+__all__ = [
+    "__version__",
+    # skill model
+    "Skill",
+    "SkillViolation",
+    "InvalidSkillError",
+    "validate_skill_dir",
+    "load_skill",
+    # hashing / provenance
+    "skill_content_hash",
+    "STAMP_KEY",
+    "read_stamp",
+    "StampError",
+    # sources (enumerate)
+    "SkillSource",
+    "SourceSkill",
+    "DirectorySource",
+    "BundledPackageDataSource",
+    "ENTRY_POINT_GROUP",
+    # harnesses (detect)
+    "HarnessBackend",
+    "HarnessRegistry",
+    "default_registry",
+    "UnknownHarnessError",
+    "HarnessNotDetectedError",
+    "UnsupportedScopeError",
+    "CLAUDE_CODE",
+    "PI",
+    "HERMES",
+    "OPENCODE",
+    # staleness hook
+    "check_stale",
+    # lifecycle verbs
+    "install",
+    "status",
+    "update",
+    "uninstall",
+    "SkillState",
+    "SkillStatus",
+    "InstalledSkill",
+    "SkippedSkill",
+    "RemovedSkill",
+    "InstallResult",
+    "UpdateResult",
+    "UninstallResult",
+]

agentsquire/cli.py

@@ -0,0 +1,198 @@
+"""Ready-made CLI subcommand group consumers mount into their own CLI.
+
+One factory call — parameterized by (package, resource path, default scope) —
+returns a click group with install/status/update/uninstall, so a consumer CLI
+exposes e.g. ``<consumer> skills install`` with no glue code (REQ-15). The
+group works identically mounted into a click app or a typer app via typer's
+click compatibility. It carries no consumer-specific logic; everything the
+consumer-specific comes in through the factory parameters.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.metadata
+from pathlib import Path
+
+import click
+
+from agentsquire.harnesses import (
+    SCOPES,
+    HarnessNotDetectedError,
+    UnknownHarnessError,
+    UnsupportedScopeError,
+    default_registry,
+)
+from agentsquire.roots import resolve_roots
+from agentsquire.verbs import install as install_verb
+from agentsquire.verbs import status as status_verb
+from agentsquire.verbs import uninstall as uninstall_verb
+from agentsquire.verbs import update as update_verb
+from agentsquire.sources import BundledPackageDataSource
+
+
+def _consumer_version(package: str, source_package: str) -> str:
+    try:
+        return importlib.metadata.version(source_package)
+    except importlib.metadata.PackageNotFoundError:
+        return getattr(importlib.import_module(package), "__version__", "unknown")
+
+
+def skills_command_group(
+    package: str,
+    resource_path: str = "skills",
+    default_scope: str = "user",
+    *,
+    name: str = "skills",
+    source_package: str | None = None,
+    source_version: str | None = None,
+    home: Path | None = None,
+    project: Path | None = None,
+) -> click.Group:
+    """Build the mountable ``skills`` subcommand group for one consumer.
+
+    ``package`` is the consumer's importable package carrying skills as
+    package data under ``resource_path``; ``default_scope`` is the scope a
+    plain invocation uses (--scope overrides it, REQ-14). ``source_package``
+    and ``source_version`` default to the package name and its installed
+    distribution (or ``__version__``) and end up in the provenance stamp.
+    ``home`` and ``project`` point the group at explicit directories - tests
+    pass fixture paths; production omits them and each invocation resolves
+    the real ``Path.home()``/``Path.cwd()``.
+    """
+    source = BundledPackageDataSource(package, resource_path)
+    src_pkg = source_package or package
+    src_version = source_version or _consumer_version(package, src_pkg)
+
+    scope_option = click.option(
+        "--scope",
+        type=click.Choice(SCOPES),
+        default=default_scope,
+        show_default=True,
+        help="Which harness skills directory to operate on.",
+    )
+    harness_option = click.option(
+        "--harness",
+        default=None,
+        metavar="NAME",
+        help="Operate on one harness (default: all detected).",
+    )
+
+    def targets(harness: str | None):
+        """(backends, home, project) for this invocation, or a clear error."""
+        target_home, target_project = resolve_roots(home, project)
+        registry = default_registry()
+        if harness is not None:
+            try:
+                backends = [
+                    registry.resolve(harness, home=target_home, project=target_project)
+                ]
+            except (UnknownHarnessError, HarnessNotDetectedError) as error:
+                raise click.ClickException(str(error)) from error
+        else:
+            backends = registry.detect(home=target_home, project=target_project)
+            if not backends:
+                raise click.ClickException("no supported harnesses detected")
+        return backends, target_home, target_project
+
+    def run_on(backend, harness, invoke_verb):
+        """One verb call on one backend. A scope the backend lacks is a clean
+        error when that harness was asked for, a named skip otherwise — never
+        an aborted multi-harness run."""
+        try:
+            return invoke_verb()
+        except UnsupportedScopeError as error:
+            if harness is not None:
+                raise click.ClickException(str(error)) from error
+            click.echo(f"skipped {backend.name}: {error}", err=True)
+            return None
+
+    group = click.Group(name=name, help="Manage this package's bundled agent skills.")
+
+    @group.command("install")
+    @scope_option
+    @harness_option
+    @click.pass_context
+    def install(ctx, scope, harness):
+        """Install bundled skills into detected harnesses."""
+        backends, home, project = targets(harness)
+        failed = False
+        for backend in backends:
+            result = run_on(backend, harness, lambda: install_verb(
+                source, backend, scope=scope, home=home, project=project,
+                source_package=src_pkg, source_version=src_version,
+            ))
+            if result is None:
+                continue
+            for skill in result.installed:
+                click.echo(f"installed {skill.name} -> {skill.path}")
+            for skill in result.up_to_date:
+                click.echo(f"up-to-date {skill.name} ({backend.name}/{scope})")
+            for skill in result.skipped:
+                click.echo(f"skipped {skill.name}: {skill.reason}", err=True)
+            for violation in result.rejected:
+                click.echo(f"invalid skill {violation.message}", err=True)
+            failed = failed or not result.ok
+        if failed:
+            ctx.exit(1)
+
+    @group.command("status")
+    @scope_option
+    @harness_option
+    def status(scope, harness):
+        """Show each bundled skill's state per harness."""
+        backends, home, project = targets(harness)
+        for backend in backends:
+            statuses = run_on(backend, harness, lambda: status_verb(
+                source, backend, scope=scope, home=home, project=project
+            ))
+            for skill in statuses or ():
+                click.echo(f"{skill.state.value} {skill.name} ({backend.name}/{scope})")
+
+    @group.command("update")
+    @scope_option
+    @harness_option
+    @click.option("--force", is_flag=True, help="Overwrite locally-modified installs.")
+    @click.pass_context
+    def update(ctx, scope, harness, force):
+        """Update stale installed skills to the bundled version."""
+        backends, home, project = targets(harness)
+        failed = False
+        for backend in backends:
+            result = run_on(backend, harness, lambda: update_verb(
+                source, backend, scope=scope, home=home, project=project,
+                source_package=src_pkg, source_version=src_version, force=force,
+            ))
+            if result is None:
+                continue
+            for skill in result.updated:
+                click.echo(f"updated {skill.name} -> {skill.path}")
+            for skill in result.up_to_date:
+                click.echo(f"up-to-date {skill.name} ({backend.name}/{scope})")
+            for skill in result.skipped:
+                click.echo(f"skipped {skill.name}: {skill.reason}", err=True)
+            for violation in result.rejected:
+                click.echo(f"invalid skill {violation.message}", err=True)
+            failed = failed or not result.ok
+        if failed:
+            ctx.exit(1)
+
+    @group.command("uninstall")
+    @scope_option
+    @harness_option
+    def uninstall(scope, harness):
+        """Remove installed skills this package's stamp owns."""
+        backends, home, project = targets(harness)
+        for backend in backends:
+            result = run_on(backend, harness, lambda: uninstall_verb(
+                source, backend, scope=scope, home=home, project=project,
+                source_package=src_pkg,
+            ))
+            if result is None:
+                continue
+            for skill in result.removed:
+                click.echo(f"removed {skill.name} ({backend.name}/{scope})")
+            for skill in result.skipped:
+                click.echo(f"skipped {skill.name}: {skill.reason}", err=True)
+
+    return group

agentsquire/harnesses.py

@@ -0,0 +1,141 @@
+"""Harness backends and registry.
+
+Each supported harness gets one backend recording where it keeps skills per
+scope and which marker directories signal its presence. Directory values
+mirror docs/harnesses.md (REQ-06) — change the document first, then the
+backend. Adding harness N+1 means registering one more backend; the verbs
+never change (REQ-05).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+SCOPES = ("user", "project")
+
+
+class UnknownHarnessError(Exception):
+    """An unsupported harness was named; the message lists the supported set."""
+
+    def __init__(self, name: str, supported: list[str]):
+        self.name = name
+        self.supported = supported
+        super().__init__(
+            f"unknown harness {name!r}; supported harnesses: {', '.join(supported)}"
+        )
+
+
+class HarnessNotDetectedError(Exception):
+    """A supported harness was named but is not present in this environment."""
+
+    def __init__(self, name: str):
+        self.name = name
+        super().__init__(
+            f"harness {name!r} is supported but not detected on this machine or in this project"
+        )
+
+
+class UnsupportedScopeError(Exception):
+    """The harness has no skills directory for the requested scope."""
+
+    def __init__(self, name: str, scope: str):
+        self.name = name
+        self.scope = scope
+        super().__init__(f"harness {name!r} has no {scope}-scope skills directory")
+
+
+@dataclass(frozen=True)
+class HarnessBackend:
+    """One harness: skill directories per scope (relative to the scope root)
+    and marker directories whose presence means the harness is in use."""
+
+    name: str
+    user_skills_dir: str | None = None
+    project_skills_dir: str | None = None
+    user_marker_dirs: tuple[str, ...] = ()
+    project_marker_dirs: tuple[str, ...] = ()
+
+    def skills_dir(self, scope: str, *, home: Path, project: Path) -> Path:
+        if scope not in SCOPES:
+            raise ValueError(f"unknown scope {scope!r}; expected one of {SCOPES}")
+        relative = self.user_skills_dir if scope == "user" else self.project_skills_dir
+        if relative is None:
+            raise UnsupportedScopeError(self.name, scope)
+        root = home if scope == "user" else project
+        return root / relative
+
+    def detect(self, *, home: Path, project: Path) -> bool:
+        return any((home / marker).is_dir() for marker in self.user_marker_dirs) or any(
+            (project / marker).is_dir() for marker in self.project_marker_dirs
+        )
+
+
+class HarnessRegistry:
+    """Registered backends: detection across them, resolution by name."""
+
+    def __init__(self):
+        self._backends: dict[str, HarnessBackend] = {}
+
+    def register(self, backend: HarnessBackend) -> None:
+        self._backends[backend.name] = backend
+
+    def names(self) -> list[str]:
+        return list(self._backends)
+
+    def detect(self, *, home: Path, project: Path) -> list[HarnessBackend]:
+        return [
+            backend
+            for backend in self._backends.values()
+            if backend.detect(home=home, project=project)
+        ]
+
+    def resolve(self, name: str, *, home: Path, project: Path) -> HarnessBackend:
+        backend = self._backends.get(name)
+        if backend is None:
+            raise UnknownHarnessError(name, self.names())
+        if not backend.detect(home=home, project=project):
+            raise HarnessNotDetectedError(name)
+        return backend
+
+
+CLAUDE_CODE = HarnessBackend(
+    name="claude-code",
+    user_skills_dir=".claude/skills",
+    project_skills_dir=".claude/skills",
+    user_marker_dirs=(".claude",),
+    project_marker_dirs=(".claude",),
+)
+
+PI = HarnessBackend(
+    name="pi",
+    user_skills_dir=".pi/agent/skills",
+    project_skills_dir=".pi/skills",
+    user_marker_dirs=(".pi",),
+    project_marker_dirs=(".pi",),
+)
+
+# Hermes has no per-project skills directory; project scope errors (see doc).
+HERMES = HarnessBackend(
+    name="hermes",
+    user_skills_dir=".hermes/skills",
+    user_marker_dirs=(".hermes",),
+)
+
+OPENCODE = HarnessBackend(
+    name="opencode",
+    user_skills_dir=".config/opencode/skills",
+    project_skills_dir=".opencode/skills",
+    user_marker_dirs=(".config/opencode", ".opencode"),
+    project_marker_dirs=(".opencode",),
+)
+
+
+def default_registry() -> HarnessRegistry:
+    """A fresh registry with the launch backends registered."""
+    registry = HarnessRegistry()
+    registry.register(CLAUDE_CODE)
+    registry.register(PI)
+    registry.register(HERMES)
+    registry.register(OPENCODE)
+    return registry

agentsquire/hashing.py

@@ -0,0 +1,59 @@
+"""Deterministic content hash over a skill directory.
+
+The hash covers every file under the skill directory, sorted by relative path
+so filesystem ordering never matters. SKILL.md is hashed in canonical form —
+frontmatter minus the provenance stamp (``metadata.agentsquire``), dumped with
+sorted keys, plus the body — so a freshly stamped install hashes back to its
+own stamped value even though stamping rewrites the frontmatter bytes.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import yaml
+
+# The provenance stamp lives under this key in the SKILL.md frontmatter
+# "metadata" map (spec-legal free-form map per agentskills.io).
+STAMP_KEY = "agentsquire"
+
+
+def _canonical_skill_md(text: str) -> bytes:
+    """SKILL.md content with the stamp stripped and frontmatter canonicalized."""
+    if not text.startswith("---"):
+        return text.encode()
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return text.encode()
+    try:
+        frontmatter = yaml.safe_load(parts[1])
+    except yaml.YAMLError:
+        return text.encode()
+    if not isinstance(frontmatter, dict):
+        return text.encode()
+
+    metadata = frontmatter.get("metadata")
+    if isinstance(metadata, dict):
+        metadata.pop(STAMP_KEY, None)
+    if not metadata and "metadata" in frontmatter:
+        del frontmatter["metadata"]
+
+    canonical_fm = yaml.safe_dump(frontmatter, sort_keys=True)
+    return f"---\n{canonical_fm}---{parts[2]}".encode()
+
+
+def skill_content_hash(path: Path) -> str:
+    """Deterministic hash of a skill directory, excluding the provenance stamp."""
+    digest = hashlib.sha256()
+    for file in sorted(p for p in path.rglob("*") if p.is_file()):
+        relpath = file.relative_to(path).as_posix()
+        if relpath == "SKILL.md":
+            content = _canonical_skill_md(file.read_text())
+        else:
+            content = file.read_bytes()
+        digest.update(relpath.encode())
+        digest.update(b"\0")
+        digest.update(hashlib.sha256(content).digest())
+        digest.update(b"\0")
+    return f"sha256:{digest.hexdigest()}"

agentsquire/roots.py

@@ -0,0 +1,50 @@
+"""Resolution of the home and project roots, with env-var overrides.
+
+Explicit ``home=`` / ``project=`` arguments always win. When they are omitted
+(the production wiring, where each invocation must resolve the real roots),
+``AGENTSQUIRE_HOME`` / ``AGENTSQUIRE_PROJECT`` redirect the roots if set to a
+non-empty value; otherwise the real ``Path.home()`` / ``Path.cwd()`` are used.
+
+The env overrides exist so a consumer's CLI-level test can point the wired
+staleness hook and the mounted ``skills`` subcommands at fixture directories by
+setting two variables, instead of monkeypatching ``Path.home`` and chdir. An
+empty-string value is treated as unset - the NO_COLOR convention already used
+for ``CI`` and ``AGENTSQUIRE_NO_UPDATE_CHECK``.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+HOME_ENV = "AGENTSQUIRE_HOME"
+PROJECT_ENV = "AGENTSQUIRE_PROJECT"
+
+
+def resolve_home(home: Path | None) -> Path:
+    """The home root: explicit ``home`` if given, else ``$AGENTSQUIRE_HOME``
+    (non-empty), else the real ``Path.home()``."""
+    if home is not None:
+        return home
+    override = os.environ.get(HOME_ENV)
+    if override:
+        return Path(override)
+    return Path.home()
+
+
+def resolve_project(project: Path | None) -> Path:
+    """The project root: explicit ``project`` if given, else
+    ``$AGENTSQUIRE_PROJECT`` (non-empty), else the real ``Path.cwd()``."""
+    if project is not None:
+        return project
+    override = os.environ.get(PROJECT_ENV)
+    if override:
+        return Path(override)
+    return Path.cwd()
+
+
+def resolve_roots(
+    home: Path | None, project: Path | None
+) -> tuple[Path, Path]:
+    """``(home, project)`` roots with explicit args winning over env over real."""
+    return resolve_home(home), resolve_project(project)

agentsquire/skills.py

@@ -0,0 +1,95 @@
+"""Skill model and agentskills.io structural validation.
+
+A skill is a directory containing a SKILL.md whose YAML frontmatter carries at
+least ``name`` (equal to the directory name) and ``description``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+@dataclass(frozen=True)
+class Skill:
+    """A parsed, structurally valid skill directory."""
+
+    name: str
+    description: str
+    path: Path
+    frontmatter: dict = field(compare=False)
+
+
+@dataclass(frozen=True)
+class SkillViolation:
+    """One broken structural rule in one skill directory."""
+
+    skill: str
+    rule: str
+    message: str
+
+
+class InvalidSkillError(Exception):
+    """Raised by load_skill when a skill directory breaks structural rules."""
+
+    def __init__(self, violations: list[SkillViolation]):
+        self.violations = violations
+        super().__init__("; ".join(v.message for v in violations))
+
+
+def _parse_frontmatter(text: str) -> dict | None:
+    """Return the YAML frontmatter mapping, or None if absent/malformed."""
+    if not text.startswith("---"):
+        return None
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return None
+    try:
+        data = yaml.safe_load(parts[1])
+    except yaml.YAMLError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def validate_skill_dir(path: Path) -> list[SkillViolation]:
+    """Check one skill directory against the structural rules; [] means valid."""
+    skill = path.name
+
+    def violation(rule: str, message: str) -> SkillViolation:
+        return SkillViolation(skill=skill, rule=rule, message=f"{skill}: {message}")
+
+    manifest = path / "SKILL.md"
+    if not manifest.is_file():
+        return [violation("missing-skill-md", "no SKILL.md in skill directory")]
+
+    frontmatter = _parse_frontmatter(manifest.read_text())
+    if frontmatter is None:
+        return [violation("invalid-frontmatter", "SKILL.md has no parseable YAML frontmatter")]
+
+    violations = []
+    name = frontmatter.get("name")
+    if not name:
+        violations.append(violation("missing-name", "frontmatter has no name"))
+    elif name != skill:
+        violations.append(
+            violation("name-mismatch", f"frontmatter name {name!r} != directory name")
+        )
+    if not frontmatter.get("description"):
+        violations.append(violation("missing-description", "frontmatter has no description"))
+    return violations
+
+
+def load_skill(path: Path) -> Skill:
+    """Parse a valid skill directory into a Skill; raise InvalidSkillError otherwise."""
+    violations = validate_skill_dir(path)
+    if violations:
+        raise InvalidSkillError(violations)
+    frontmatter = _parse_frontmatter((path / "SKILL.md").read_text())
+    return Skill(
+        name=frontmatter["name"],
+        description=frontmatter["description"],
+        path=path,
+        frontmatter=frontmatter,
+    )