skillsctl 0.1.0__tar.gz

skillsctl-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: skillsctl
+Version: 0.1.0
+Summary: CLI tool for installing skills, agents, workflows, and rules from an Enterprise Skills Catalog
+Project-URL: Homepage, https://github.com/your-org/enterprise-skills-catalog
+Project-URL: Repository, https://github.com/your-org/enterprise-skills-catalog
+Project-URL: Issues, https://github.com/your-org/enterprise-skills-catalog/issues
+Author: Enterprise Skills Catalog
+License: MIT
+Keywords: agents,catalog,cli,enterprise,skills,workflows
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# skillsctl
+
+CLI tool for installing skills, agents, workflows, and rules from an Enterprise Skills Catalog.
+
+## Installation
+
+```bash
+pip install skillsctl
+```
+
+## Quick Start
+
+```bash
+# Search the catalog
+skillsctl search slack
+
+# Install a skill
+skillsctl install send-slack-notification
+
+# Install multiple items with dependencies
+skillsctl install send-slack-notification slack-ops-agent --with-deps
+
+# List installed items
+skillsctl list
+
+# Update an item
+skillsctl update send-slack-notification
+
+# Sync all installed items to latest versions
+skillsctl sync
+
+# Remove an item
+skillsctl remove send-slack-notification
+```
+
+## Configuration
+
+By default, `skillsctl` connects to `http://localhost:8000`. Override with:
+
+```bash
+# CLI flag
+skillsctl --source https://catalog.company.com install my-skill
+
+# Environment variable
+export SKILLSCTL_SOURCE=https://catalog.company.com
+
+# Or set in skills.yaml
+```
+
+## Lockfile
+
+`skillsctl` maintains a `skills.yaml` file in your project root:
+
+```yaml
+source: https://catalog.company.com
+installed:
+  send-slack-notification: "2.1.0"
+  http-request: "1.3.0"
+  slack-ops-agent: "1.0.0"
+```
+
+Installed files are saved to `.skills/{category}/{name}.md`.

skillsctl-0.1.0/README.md

@@ -0,0 +1,62 @@
+# skillsctl
+
+CLI tool for installing skills, agents, workflows, and rules from an Enterprise Skills Catalog.
+
+## Installation
+
+```bash
+pip install skillsctl
+```
+
+## Quick Start
+
+```bash
+# Search the catalog
+skillsctl search slack
+
+# Install a skill
+skillsctl install send-slack-notification
+
+# Install multiple items with dependencies
+skillsctl install send-slack-notification slack-ops-agent --with-deps
+
+# List installed items
+skillsctl list
+
+# Update an item
+skillsctl update send-slack-notification
+
+# Sync all installed items to latest versions
+skillsctl sync
+
+# Remove an item
+skillsctl remove send-slack-notification
+```
+
+## Configuration
+
+By default, `skillsctl` connects to `http://localhost:8000`. Override with:
+
+```bash
+# CLI flag
+skillsctl --source https://catalog.company.com install my-skill
+
+# Environment variable
+export SKILLSCTL_SOURCE=https://catalog.company.com
+
+# Or set in skills.yaml
+```
+
+## Lockfile
+
+`skillsctl` maintains a `skills.yaml` file in your project root:
+
+```yaml
+source: https://catalog.company.com
+installed:
+  send-slack-notification: "2.1.0"
+  http-request: "1.3.0"
+  slack-ops-agent: "1.0.0"
+```
+
+Installed files are saved to `.skills/{category}/{name}.md`.

skillsctl-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "skillsctl"
+version = "0.1.0"
+description = "CLI tool for installing skills, agents, workflows, and rules from an Enterprise Skills Catalog"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Enterprise Skills Catalog"},
+]
+keywords = ["skills", "catalog", "cli", "enterprise", "agents", "workflows"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "click>=8.1",
+    "httpx>=0.27",
+    "pyyaml>=6.0",
+    "rich>=13.0",
+]
+
+[project.scripts]
+skillsctl = "skillsctl.main:cli"
+
+[project.urls]
+Homepage = "https://github.com/your-org/enterprise-skills-catalog"
+Repository = "https://github.com/your-org/enterprise-skills-catalog"
+Issues = "https://github.com/your-org/enterprise-skills-catalog/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/skillsctl"]

skillsctl-0.1.0/src/skillsctl/__init__.py

@@ -0,0 +1,3 @@
+"""skillsctl — CLI for the Enterprise Skills Catalog."""
+
+__version__ = "0.1.0"

skillsctl-0.1.0/src/skillsctl/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as `python -m skillsctl`."""
+from .main import cli
+
+cli()

skillsctl-0.1.0/src/skillsctl/client.py

@@ -0,0 +1,61 @@
+"""HTTP client for the Skills Catalog API."""
+from __future__ import annotations
+
+import click
+import httpx
+
+
+class CatalogClient:
+    def __init__(self, base_url: str) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(base_url=self.base_url, timeout=30.0)
+
+    def _get(self, path: str, **params: str) -> httpx.Response:
+        try:
+            resp = self._http.get(path, params=params)
+        except httpx.ConnectError:
+            raise click.ClickException(
+                f"Cannot connect to catalog at {self.base_url}. "
+                "Is the server running?"
+            )
+        if resp.status_code == 404:
+            return resp  # let caller handle
+        if resp.status_code >= 400:
+            raise click.ClickException(
+                f"API error {resp.status_code}: {resp.text[:200]}"
+            )
+        return resp
+
+    def get_item(self, name: str) -> dict | None:
+        resp = self._get(f"/api/v1/items/{name}")
+        if resp.status_code == 404:
+            return None
+        return resp.json()
+
+    def get_raw(self, name: str) -> str | None:
+        resp = self._get(f"/api/v1/items/{name}/raw")
+        if resp.status_code == 404:
+            return None
+        return resp.text
+
+    def get_bundle(self, names: list[str]) -> dict:
+        resp = self._get("/api/v1/items/bundle", items=",".join(names))
+        try:
+            data = resp.json()
+        except Exception:
+            raise click.ClickException(
+                f"Unexpected response from {self.base_url}/api/v1/items/bundle — "
+                "is the catalog server up-to-date?"
+            )
+        return data
+
+    def search(self, query: str, **kwargs: str) -> dict:
+        resp = self._get("/api/v1/items/search", q=query, **kwargs)
+        return resp.json()
+
+    def list_items(self, **kwargs: str) -> dict:
+        resp = self._get("/api/v1/items", **kwargs)
+        return resp.json()
+
+    def close(self) -> None:
+        self._http.close()

skillsctl-0.1.0/src/skillsctl/commands/install.py

@@ -0,0 +1,97 @@
+"""skillsctl install — download and save items from the catalog."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from ..client import CatalogClient
+from ..lockfile import Lockfile
+
+console = Console()
+SKILLS_DIR = ".skills"
+
+
+def _resolve_deps(
+    client: CatalogClient,
+    names: list[str],
+    resolved: dict[str, dict],
+) -> None:
+    """Recursively resolve requires dependencies."""
+    for name in names:
+        if name in resolved:
+            continue
+        item = client.get_item(name)
+        if item is None:
+            console.print(f"[yellow]Warning:[/] '{name}' not found in catalog, skipping")
+            continue
+        resolved[name] = item
+        requires = item.get("requires", [])
+        if requires:
+            _resolve_deps(client, requires, resolved)
+
+
+@click.command("install")
+@click.argument("names", nargs=-1, required=True)
+@click.option("--with-deps/--no-deps", default=True, help="Install required dependencies")
+@click.pass_context
+def install(ctx: click.Context, names: tuple[str, ...], with_deps: bool) -> None:
+    """Install skills, agents, rules, or workflows from the catalog."""
+    client: CatalogClient = ctx.obj["client"]
+    lockfile: Lockfile = ctx.obj["lockfile"]
+    project_root = lockfile.path.parent
+
+    # Resolve all items (and deps if requested)
+    resolved: dict[str, dict] = {}
+    if with_deps:
+        _resolve_deps(client, list(names), resolved)
+    else:
+        for name in names:
+            item = client.get_item(name)
+            if item is None:
+                console.print(f"[yellow]Warning:[/] '{name}' not found in catalog, skipping")
+                continue
+            resolved[name] = item
+
+    if not resolved:
+        raise click.ClickException("No items to install.")
+
+    # Download raw files via bundle endpoint for efficiency
+    bundle = client.get_bundle(list(resolved.keys()))
+    content_map = {bi["name"]: bi for bi in bundle["items"]}
+
+    if bundle["errors"]:
+        for err in bundle["errors"]:
+            console.print(f"[yellow]Warning:[/] could not download '{err}'")
+
+    # Write files and update lockfile
+    installed: list[tuple[str, str, str, Path]] = []  # (name, version, category, path)
+
+    for name, item_meta in resolved.items():
+        if name not in content_map:
+            continue
+        bi = content_map[name]
+        category = bi["category"]
+        target_dir = project_root / SKILLS_DIR / category
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target_file = target_dir / f"{name}.md"
+        target_file.write_text(bi["content"], encoding="utf-8")
+        lockfile.add(name, bi["version"])
+        installed.append((name, bi["version"], category, target_file))
+
+    lockfile.save()
+
+    # Summary table
+    table = Table(title="Installed", show_lines=False)
+    table.add_column("Name", style="cyan")
+    table.add_column("Version", style="green")
+    table.add_column("Category", style="magenta")
+    table.add_column("Path", style="dim")
+    for name, version, category, path in installed:
+        is_dep = name not in names
+        label = f"{name} [dim](dep)[/]" if is_dep else name
+        table.add_row(label, version, category, str(path.relative_to(project_root)))
+    console.print(table)
+    console.print(f"[green]{len(installed)} item(s) installed.[/]")

skillsctl-0.1.0/src/skillsctl/commands/list_cmd.py

@@ -0,0 +1,40 @@
+"""skillsctl list — show installed items."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from ..lockfile import Lockfile
+
+console = Console()
+SKILLS_DIR = ".skills"
+
+
+@click.command("list")
+@click.pass_context
+def list_cmd(ctx: click.Context) -> None:
+    """List all installed items from skills.yaml."""
+    lockfile: Lockfile = ctx.obj["lockfile"]
+    project_root = lockfile.path.parent
+    skills_dir = project_root / SKILLS_DIR
+
+    if not lockfile.installed:
+        console.print("[dim]No items installed. Run 'skillsctl install <name>' to get started.[/]")
+        return
+
+    table = Table(title="Installed Items", show_lines=False)
+    table.add_column("Name", style="cyan")
+    table.add_column("Version", style="green")
+    table.add_column("Path", style="dim")
+
+    for name, version in sorted(lockfile.installed.items()):
+        # Find the file to show path
+        matches = list(skills_dir.rglob(f"{name}.md")) if skills_dir.exists() else []
+        path_str = str(matches[0].relative_to(project_root)) if matches else "[red]missing[/]"
+        table.add_row(name, version, path_str)
+
+    console.print(table)
+    console.print(f"[dim]Source: {lockfile.source}[/]")

skillsctl-0.1.0/src/skillsctl/commands/remove.py

@@ -0,0 +1,47 @@
+"""skillsctl remove — remove installed items."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from ..lockfile import Lockfile
+
+console = Console()
+SKILLS_DIR = ".skills"
+
+
+@click.command("remove")
+@click.argument("names", nargs=-1, required=True)
+@click.pass_context
+def remove(ctx: click.Context, names: tuple[str, ...]) -> None:
+    """Remove installed skills, agents, rules, or workflows."""
+    lockfile: Lockfile = ctx.obj["lockfile"]
+    project_root = lockfile.path.parent
+    skills_dir = project_root / SKILLS_DIR
+
+    removed = 0
+    for name in names:
+        if not lockfile.has(name):
+            console.print(f"[yellow]'{name}' is not installed, skipping[/]")
+            continue
+
+        # Find and delete the file (scan subdirs since category is in path)
+        found = False
+        for md in skills_dir.rglob(f"{name}.md"):
+            md.unlink()
+            found = True
+            # Remove empty parent dirs
+            parent = md.parent
+            if parent != skills_dir and not any(parent.iterdir()):
+                parent.rmdir()
+
+        lockfile.remove(name)
+        removed += 1
+        status = "removed" if found else "removed from lockfile (file not found)"
+        console.print(f"  [red]- {name}[/] ({status})")
+
+    lockfile.save()
+    if removed:
+        console.print(f"[green]{removed} item(s) removed.[/]")

skillsctl-0.1.0/src/skillsctl/commands/search.py

@@ -0,0 +1,46 @@
+"""skillsctl search — search the remote catalog."""
+from __future__ import annotations
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from ..client import CatalogClient
+
+console = Console()
+
+
+@click.command("search")
+@click.argument("query")
+@click.option("--category", "-c", default=None, help="Filter by category")
+@click.option("--tag", "-t", default=None, help="Filter by tag")
+@click.pass_context
+def search(ctx: click.Context, query: str, category: str | None, tag: str | None) -> None:
+    """Search the catalog for skills, agents, rules, or workflows."""
+    client: CatalogClient = ctx.obj["client"]
+
+    kwargs: dict = {}
+    if category:
+        kwargs["category"] = category
+    if tag:
+        kwargs["tags"] = tag
+
+    result = client.search(query, **kwargs)
+
+    if not result["results"]:
+        console.print(f"[dim]No results for '{query}'[/]")
+        return
+
+    table = Table(title=f"Search: '{query}'", show_lines=False)
+    table.add_column("Name", style="cyan")
+    table.add_column("Version", style="green")
+    table.add_column("Category", style="magenta")
+    table.add_column("Description", max_width=50)
+
+    for r in result["results"]:
+        item = r["item"]
+        desc = item["description"][:80] + ("..." if len(item["description"]) > 80 else "")
+        table.add_row(item["name"], item["version"], item["category"], desc)
+
+    console.print(table)
+    console.print(f"[dim]{result['total']} result(s) found[/]")

skillsctl-0.1.0/src/skillsctl/commands/sync.py

@@ -0,0 +1,63 @@
+"""skillsctl sync — sync installed items to their catalog versions."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from ..client import CatalogClient
+from ..lockfile import Lockfile
+
+console = Console()
+SKILLS_DIR = ".skills"
+
+
+@click.command("sync")
+@click.pass_context
+def sync(ctx: click.Context) -> None:
+    """Re-download all installed items from the catalog (update to latest)."""
+    client: CatalogClient = ctx.obj["client"]
+    lockfile: Lockfile = ctx.obj["lockfile"]
+    project_root = lockfile.path.parent
+
+    if not lockfile.installed:
+        console.print("[dim]Nothing to sync — no items in skills.yaml[/]")
+        return
+
+    updated = 0
+    unchanged = 0
+    errors = 0
+
+    for name, local_version in list(lockfile.installed.items()):
+        item = client.get_item(name)
+        if item is None:
+            console.print(f"  [yellow]! {name}[/] — not found in catalog")
+            errors += 1
+            continue
+
+        remote_version = item["version"]
+        raw = client.get_raw(name)
+        if raw is None:
+            console.print(f"  [yellow]! {name}[/] — could not download")
+            errors += 1
+            continue
+
+        category = item["category"]
+        target_dir = project_root / SKILLS_DIR / category
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target_file = target_dir / f"{name}.md"
+        target_file.write_text(raw, encoding="utf-8")
+        lockfile.add(name, remote_version)
+
+        if local_version != remote_version:
+            console.print(f"  [green]+ {name}[/] {local_version} → {remote_version}")
+            updated += 1
+        else:
+            unchanged += 1
+
+    lockfile.save()
+    console.print(
+        f"\n[green]{updated} updated[/], {unchanged} unchanged, "
+        f"{'[yellow]' + str(errors) + ' errors[/]' if errors else '0 errors'}"
+    )

skillsctl-0.1.0/src/skillsctl/commands/update.py

@@ -0,0 +1,54 @@
+"""skillsctl update — update a specific item to the latest version."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from ..client import CatalogClient
+from ..lockfile import Lockfile
+
+console = Console()
+SKILLS_DIR = ".skills"
+
+
+@click.command("update")
+@click.argument("names", nargs=-1, required=True)
+@click.pass_context
+def update(ctx: click.Context, names: tuple[str, ...]) -> None:
+    """Update specific installed items to their latest catalog version."""
+    client: CatalogClient = ctx.obj["client"]
+    lockfile: Lockfile = ctx.obj["lockfile"]
+    project_root = lockfile.path.parent
+
+    for name in names:
+        if not lockfile.has(name):
+            console.print(f"[yellow]'{name}' is not installed — use 'skillsctl install {name}' first[/]")
+            continue
+
+        local_version = lockfile.installed[name]
+        item = client.get_item(name)
+        if item is None:
+            console.print(f"[yellow]'{name}' not found in catalog[/]")
+            continue
+
+        remote_version = item["version"]
+        if local_version == remote_version:
+            console.print(f"  [dim]{name} already at {local_version} (latest)[/]")
+            continue
+
+        raw = client.get_raw(name)
+        if raw is None:
+            console.print(f"[yellow]'{name}' — could not download[/]")
+            continue
+
+        category = item["category"]
+        target_dir = project_root / SKILLS_DIR / category
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target_file = target_dir / f"{name}.md"
+        target_file.write_text(raw, encoding="utf-8")
+        lockfile.add(name, remote_version)
+        console.print(f"  [green]+ {name}[/] {local_version} → {remote_version}")
+
+    lockfile.save()

skillsctl-0.1.0/src/skillsctl/lockfile.py

@@ -0,0 +1,62 @@
+"""Manages the skills.yaml lockfile."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+
+DEFAULT_SOURCE = "http://localhost:8000"
+LOCKFILE_NAME = "skills.yaml"
+
+
+class Lockfile:
+    def __init__(self, path: Path, source: str, installed: dict[str, str]) -> None:
+        self.path = path
+        self.source = source
+        self.installed = installed  # name -> version
+
+    @classmethod
+    def find(cls, start: Path | None = None) -> "Lockfile":
+        """Walk up from start (default: cwd) looking for skills.yaml."""
+        cwd = start or Path.cwd()
+        current = cwd
+        while True:
+            candidate = current / LOCKFILE_NAME
+            if candidate.exists():
+                return cls.load(candidate)
+            parent = current.parent
+            if parent == current:
+                break
+            current = parent
+        # Not found — return a default at cwd
+        return cls(path=cwd / LOCKFILE_NAME, source=DEFAULT_SOURCE, installed={})
+
+    @classmethod
+    def load(cls, path: Path) -> "Lockfile":
+        text = path.read_text(encoding="utf-8")
+        data = yaml.safe_load(text) or {}
+        return cls(
+            path=path,
+            source=data.get("source", DEFAULT_SOURCE),
+            installed=data.get("installed", {}),
+        )
+
+    def save(self) -> None:
+        data = {
+            "source": self.source,
+            "installed": dict(sorted(self.installed.items())),
+        }
+        self.path.write_text(
+            yaml.dump(data, default_flow_style=False, sort_keys=False),
+            encoding="utf-8",
+        )
+
+    def add(self, name: str, version: str) -> None:
+        self.installed[name] = version
+
+    def remove(self, name: str) -> bool:
+        return self.installed.pop(name, None) is not None
+
+    def has(self, name: str) -> bool:
+        return name in self.installed

skillsctl-0.1.0/src/skillsctl/main.py

@@ -0,0 +1,49 @@
+"""Main CLI group for skillsctl."""
+from __future__ import annotations
+
+import os
+
+import click
+
+from . import __version__
+from .client import CatalogClient
+from .lockfile import Lockfile
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="skillsctl")
+@click.option(
+    "--source",
+    envvar="SKILLSCTL_SOURCE",
+    default=None,
+    help="Catalog server URL (default: from skills.yaml or http://localhost:8000)",
+)
+@click.pass_context
+def cli(ctx: click.Context, source: str | None) -> None:
+    """Enterprise Skills Catalog CLI — install, manage, and search skills."""
+    ctx.ensure_object(dict)
+
+    lockfile = Lockfile.find()
+
+    # Source resolution: --source flag > skills.yaml > env var > default
+    resolved_source = source or lockfile.source
+    lockfile.source = resolved_source
+
+    ctx.obj["lockfile"] = lockfile
+    ctx.obj["client"] = CatalogClient(resolved_source)
+
+
+# Register commands
+from .commands.install import install
+from .commands.remove import remove
+from .commands.list_cmd import list_cmd
+from .commands.search import search
+from .commands.sync import sync
+from .commands.update import update
+
+cli.add_command(install)
+cli.add_command(remove)
+cli.add_command(list_cmd)
+cli.add_command(search)
+cli.add_command(sync)
+cli.add_command(update)