skills-manager-cli 0.1.0__py3-none-any.whl

skills_manager/__init__.py

@@ -0,0 +1,3 @@
+"""skills-manager: a CLI to handle agent skills."""
+
+__version__ = "0.1.0"

skills_manager/adapters.py

@@ -0,0 +1,62 @@
+"""Real adapters for ports; tests use the fakes defined here."""
+
+import subprocess
+from datetime import datetime
+from pathlib import Path
+
+import typer
+
+from .ports import ProcessResult
+
+
+class TyperConsole:
+    def echo(self, message: str = "", *, err: bool = False) -> None:
+        typer.echo(message, err=err)
+
+
+class BufferConsole:
+    def __init__(self) -> None:
+        self.lines: list[str] = []
+        self.errors: list[str] = []
+
+    def echo(self, message: str = "", *, err: bool = False) -> None:
+        (self.errors if err else self.lines).append(message)
+
+
+class SubprocessGitRunner:
+    def run(self, args: list[str], cwd: Path) -> ProcessResult:
+        completed = subprocess.run(
+            ["git", *args], cwd=cwd, capture_output=True, text=True, check=False
+        )
+        return ProcessResult(completed.returncode, completed.stdout, completed.stderr)
+
+
+class SubprocessRunner:
+    def run(self, args: list[str], cwd: Path) -> ProcessResult:
+        completed = subprocess.run(
+            list(args), cwd=cwd, capture_output=True, text=True, check=False
+        )
+        return ProcessResult(completed.returncode, completed.stdout, completed.stderr)
+
+
+class FakeGitRunner:
+    def __init__(self, results: list[ProcessResult] | None = None) -> None:
+        self._results = list(results or [ProcessResult(0, "", "")])
+        self.calls: list = []
+
+    def run(self, args: list[str], cwd: Path) -> ProcessResult:
+        self.calls.append((list(args), Path(cwd)))
+        return self._results[min(len(self.calls) - 1, len(self._results) - 1)]
+
+
+class SystemClock:
+    def now(self) -> datetime:
+        return datetime.now()
+
+
+class FakeClock:
+    def __init__(self, moment: datetime) -> None:
+        self._moment = moment
+
+    def now(self) -> datetime:
+        return self._moment

skills_manager/agents.py

@@ -0,0 +1,231 @@
+import os
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import Config, load_config, save_config
+
+SKILLS_DIR = "skills"
+
+
+class AgentLinkError(RuntimeError):
+    """Raised when a managed symlink cannot be created or removed."""
+
+
+@dataclass(frozen=True)
+class Agent:
+    name: str
+    base_dir: str
+    skills_dir: str
+
+    def base(self, user_home: Path) -> Path:
+        return Path(user_home) / self.base_dir
+
+    def skills(self, user_home: Path) -> Path:
+        return Path(user_home) / self.skills_dir
+
+
+SUPPORTED_AGENTS: dict[str, Agent] = {
+    "claude": Agent("claude", ".claude", ".claude/skills"),
+    "opencode": Agent("opencode", ".config/opencode", ".config/opencode/skills"),
+    "codex": Agent("codex", ".codex", ".codex/skills"),
+    "cursor": Agent("cursor", ".cursor", ".cursor/skills"),
+    "gemini": Agent("gemini", ".gemini", ".gemini/skills"),
+}
+
+
+def detect_agents(user_home: Path | None = None) -> list[Agent]:
+    root = Path(user_home) if user_home is not None else Path.home()
+    return [agent for agent in SUPPORTED_AGENTS.values() if agent.base(root).is_dir()]
+
+
+class AgentState:
+    """Which agents receive skill links (backed by the config file)."""
+
+    def __init__(self, home: Path):
+        self.home = Path(home)
+        self._cached: Config | None = None
+
+    def _load(self) -> Config:
+        if self._cached is None:
+            self._cached = load_config(self.home)
+        return self._cached
+
+    def is_enabled(self, name: str) -> bool:
+        return name not in self._load().disabled
+
+    def set_enabled(self, name: str, enabled: bool) -> None:
+        config = self._load()
+        disabled = set(config.disabled)
+        if enabled:
+            disabled.discard(name)
+        else:
+            disabled.add(name)
+        updated = Config(config.search_paths, sorted(disabled))
+        save_config(self.home, updated)
+        self._cached = updated
+
+
+def installed_skills(home: Path) -> list[str]:
+    root = Path(home) / SKILLS_DIR
+    if not root.is_dir():
+        return []
+    return sorted(entry.name for entry in root.iterdir() if entry.is_dir())
+
+
+def relink_agents(
+    home: Path,
+    names: list[str],
+    user_home: Path | None = None,
+    *,
+    take_over: bool = False,
+) -> None:
+    """Ensure managed links for skills across every detected agent."""
+    root = Path(user_home) if user_home is not None else Path.home()
+    for agent in detect_agents(root):
+        for name in names:
+            relink_skill(agent, home, name, user_home=root, take_over=take_over)
+    root = Path(home) / SKILLS_DIR
+    if not root.is_dir():
+        return []
+    return sorted(entry.name for entry in root.iterdir() if entry.is_dir())
+
+
+def is_linked(
+    agent: Agent,
+    home: Path,
+    name: str,
+    user_home: Path | None = None,
+) -> bool:
+    """Return whether the agent folder holds a managed link for a skill."""
+    root = Path(user_home) if user_home is not None else Path.home()
+    if not agent.base(root).is_dir():
+        return False
+    link = agent.skills(root) / name
+    return bool(link.is_symlink() and _points_into(link, (Path(home) / SKILLS_DIR).resolve()))
+
+
+def unlink_skills(
+    agent: Agent,
+    home: Path,
+    names: list[str],
+    user_home: Path | None = None,
+) -> None:
+    """Remove ``names`` from one agent folder when managed by this tool.
+
+    Only symlinks pointing into ``<home>/skills`` are removed; anything
+    else (real directories, foreign links, missing entries) is left alone.
+    """
+    root = Path(user_home) if user_home is not None else Path.home()
+    skills_root = (Path(home) / SKILLS_DIR).resolve()
+    agent_skills = agent.skills(root)
+    if not agent_skills.is_dir():
+        return
+    for name in names:
+        link = agent_skills / name
+        if link.is_symlink() and _points_into(link, skills_root):
+            try:
+                link.unlink()
+            except OSError as exc:
+                raise AgentLinkError(
+                    f"could not unlink {name!r} for {agent.name}: {exc}"
+                ) from exc
+
+
+def unlink_agents(
+    home: Path,
+    names: list[str],
+    user_home: Path | None = None,
+) -> None:
+    """Remove managed links for skills across every detected agent."""
+    root = Path(user_home) if user_home is not None else Path.home()
+    for agent in detect_agents(root):
+        unlink_skills(agent, home, names, user_home=root)
+
+
+def _points_into(link: Path, root: Path) -> bool:
+    try:
+        resolved = link.resolve()
+    except OSError:
+        return False
+    return resolved == root or root in resolved.parents
+
+
+def reconcile(
+    agent: Agent,
+    home: Path,
+    *,
+    enable: bool,
+    user_home: Path | None = None,
+) -> None:
+    root = Path(user_home) if user_home is not None else Path.home()
+    skills_root = (Path(home) / SKILLS_DIR).resolve()
+    agent_skills = agent.skills(root)
+
+    if enable:
+        agent_skills.mkdir(parents=True, exist_ok=True)
+    elif not agent_skills.is_dir():
+        return
+
+    for name in installed_skills(home):
+        link = agent_skills / name
+        if enable:
+            if link.is_symlink() or link.exists():
+                continue
+            try:
+                os.symlink(skills_root / name, link)
+            except OSError as exc:
+                raise AgentLinkError(
+                    f"could not link {name!r} for {agent.name}: {exc}"
+                ) from exc
+        elif link.is_symlink() and _points_into(link, skills_root):
+            try:
+                link.unlink()
+            except OSError as exc:
+                raise AgentLinkError(
+                    f"could not unlink {name!r} for {agent.name}: {exc}"
+                ) from exc
+
+
+def relink_skill(
+    agent: Agent,
+    home: Path,
+    name: str,
+    user_home: Path | None = None,
+    *,
+    take_over: bool = False,
+) -> None:
+    """Ensure one managed link exists for an installed skill.
+
+    A managed link is left alone; a missing link is created. Anything else
+    under the skill's name (a real directory, a file, a foreign link) is
+    replaced with a managed link only when ``take_over`` is true.
+    """
+    root = Path(user_home) if user_home is not None else Path.home()
+    skills_root = (Path(home) / SKILLS_DIR).resolve()
+    if not agent.base(root).is_dir():
+        return
+    agent_skills = agent.skills(root)
+    link = agent_skills / name
+    if link.is_symlink() and _points_into(link, skills_root):
+        return
+    if link.is_symlink() or link.exists():
+        if not take_over:
+            return
+        try:
+            if link.is_dir() and not link.is_symlink():
+                shutil.rmtree(link)
+            else:
+                link.unlink()
+        except OSError as exc:
+            raise AgentLinkError(
+                f"could not take over {name!r} for {agent.name}: {exc}"
+            ) from exc
+    try:
+        agent_skills.mkdir(parents=True, exist_ok=True)
+        if not link.is_symlink():
+            os.symlink(skills_root / name, link)
+    except OSError as exc:
+        raise AgentLinkError(
+            f"could not link {name!r} for {agent.name}: {exc}"
+        ) from exc

skills_manager/checks/__init__.py

@@ -0,0 +1,58 @@
+"""Deterministic pre-install rule registry (BL-064, consumed by BL-062)."""
+
+import fnmatch
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+SEVERITIES = ("low", "medium", "high", "critical")
+_RANK = {name: index for index, name in enumerate(SEVERITIES)}
+
+
+@dataclass(frozen=True)
+class Finding:
+    check_id: str
+    severity: str
+    path: str
+    message: str
+
+
+@dataclass(frozen=True)
+class Check:
+    id: str
+    severity: str
+    title: str
+    run: Callable[[Path], list[Finding]]
+
+
+@dataclass(frozen=True)
+class Report:
+    findings: tuple = ()
+    blocked: bool = False
+
+
+def _excluded(path: str, patterns: Sequence[str]) -> bool:
+    return any(fnmatch.fnmatch(path, pattern) for pattern in patterns)
+
+
+def run_checks(
+    tree: Path,
+    *,
+    checks: Sequence[Check] = (),
+    minimum: str = "medium",
+    exclude: Sequence[str] = (),
+    exclude_paths: Sequence[str] = (),
+) -> Report:
+    """Run every check over ``tree``; block when findings exceed ``minimum``."""
+    tree = Path(tree)
+    findings: list[Finding] = []
+    for check in checks:
+        if check.id in exclude:
+            continue
+        for finding in check.run(tree):
+            rel = str(Path(finding.path).as_posix())
+            if _excluded(rel, exclude_paths):
+                continue
+            findings.append(finding)
+    blocked = any(_RANK[f.severity] > _RANK[minimum] for f in findings)
+    return Report(findings=tuple(findings), blocked=blocked)

skills_manager/checks/rules.py

@@ -0,0 +1,277 @@
+"""V1 deterministic security rules (BL-062) plus expansion pack (BL-065).
+
+Pure read-only walks; never executes skill code.
+"""
+
+import os
+import re
+import tarfile
+import zipfile
+from pathlib import Path
+
+from . import Check, Finding
+
+_SCRIPT_SUFFIXES = frozenset(
+    {".sh", ".ps1", ".py", ".js", ".bat", ".cmd", ".exe", ".dll", ".so", ".dylib"}
+)
+
+
+def _walk_skill(root: Path):
+    """Yield (rel_posix, path) for every entry; never descend into symlinked dirs.
+
+    Hidden files ARE scanned (only `.git` is skipped — it is never
+    installed, per `copy_local`); malware loves dotfiles.
+    """
+    root = Path(root)
+    try:
+        children = sorted(root.iterdir(), key=lambda e: e.name)
+    except OSError:
+        return
+    for child in children:
+        if child.name == ".git":
+            continue
+        yield (child.relative_to(root).as_posix(), child)
+        if child.is_dir() and not child.is_symlink():
+            yield from _walk_skill_at(root, child)
+
+
+def _walk_skill_at(root: Path, base: Path):
+    try:
+        children = sorted(base.iterdir(), key=lambda e: e.name)
+    except OSError:
+        return
+    for child in children:
+        if child.name == ".git":
+            continue
+        yield (child.relative_to(root).as_posix(), child)
+        if child.is_dir() and not child.is_symlink():
+            yield from _walk_skill_at(root, child)
+
+
+def _readlink_text(link: Path) -> str | None:
+    try:
+        return os.readlink(link)
+    except OSError:
+        return None
+
+
+def _skl001_symlink_escape(root: Path) -> list[Finding]:
+    findings = []
+    norm_root = os.path.normpath(str(root))
+    for rel, path in _walk_skill(root):
+        if not path.is_symlink():
+            continue
+        target = _readlink_text(path)
+        if target is None:
+            continue
+        absolute = target if os.path.isabs(target) else os.path.normpath(os.path.join(str(path.parent), target))
+        absolute = os.path.normpath(absolute)
+        if absolute != norm_root and Path(norm_root) not in Path(absolute).parents:
+            findings.append(Finding("SKL001", "high", rel, f"symlink escapes the skill tree: {target}"))
+    return findings
+
+
+def _skl002_parent_reference(root: Path) -> list[Finding]:
+    findings = []
+    for rel, path in _walk_skill(root):
+        if not path.is_symlink():
+            continue
+        target = _readlink_text(path)
+        if target is None:
+            continue
+        segments = [s for s in target.replace("\\", "/").split("/")]
+        if ".." in segments:
+            findings.append(Finding("SKL002", "medium", rel, f"suspicious parent reference in link target: {target}"))
+    return findings
+
+
+def _skl003_executables(root: Path) -> list[Finding]:
+    findings = []
+    for rel, path in _walk_skill(root):
+        if path.is_symlink() or not path.is_file():
+            continue
+        try:
+            mode = path.stat().st_mode
+        except OSError:
+            continue
+        if mode & 0o111 or path.suffix.lower() in _SCRIPT_SUFFIXES:
+            findings.append(Finding("SKL003", "medium", rel, "executable or script file"))
+    return findings
+
+
+_ARCHIVE_SUFFIXES = frozenset({".tar", ".tar.gz", ".tgz", ".zip"})
+
+
+def _is_archive(path: Path) -> bool:
+    name = path.name.lower()
+    return name.endswith(".tar.gz") or path.suffix.lower() in _ARCHIVE_SUFFIXES
+
+
+def _skl004_archive_members(root: Path) -> list[Finding]:
+    findings = []
+    for rel, path in _walk_skill(root):
+        if path.is_symlink() or not path.is_file() or not _is_archive(path):
+            continue
+        for member, problem in _archive_problems(path):
+            findings.append(Finding("SKL004", "high", rel, f"unsafe archive member {member}: {problem}"))
+    return findings
+
+
+def _archive_problems(path: Path):
+    """Yield (member, problem) for traversal/link members; skip unreadable archives silently."""
+    name = path.name.lower()
+    try:
+        if name.endswith(".zip"):
+            with zipfile.ZipFile(path) as archive:
+                members = [(info.filename, False, False) for info in archive.infolist()]
+        else:
+            with tarfile.open(path, "r") as archive:
+                members = [
+                    (member.name, member.issym() or member.islnk(), False)
+                    for member in archive.getmembers()
+                ]
+    except (OSError, tarfile.TarError, zipfile.BadZipFile):
+        return
+    for member, is_link, _ in members:
+        segments = [s for s in member.replace("\\", "/").split("/")]
+        if member.startswith("/") or (len(member) > 1 and member[1] == ":"):
+            yield member, "absolute path"
+        elif ".." in segments:
+            yield member, "parent reference"
+        elif is_link:
+            yield member, "link member"
+
+
+_READ_CAP = 262144
+
+
+def _text_of(path: Path) -> str | None:
+    """Best-effort text of a file: None when missing/binary/too costly; capped."""
+    try:
+        with open(path, "rb") as handle:
+            head = handle.read(8192)
+            if b"\x00" in head:
+                return None
+            handle.seek(0)
+            return handle.read(_READ_CAP).decode("utf-8", errors="ignore")
+    except OSError:
+        return None
+
+
+def _text_files(root: Path):
+    """Yield (rel, text) for non-symlink regular files with readable text."""
+    for rel, path in _walk_skill(root):
+        if path.is_symlink() or not path.is_file():
+            continue
+        text = _text_of(path)
+        if text is not None:
+            yield rel, text
+
+
+_SECRET_KEY = re.compile(r"(?im)^\s*[A-Z0-9_]*(SECRET|TOKEN|KEY|PASSWORD|PASSWD)[A-Z0-9_]*\s*=")
+_AUTH_LINE = re.compile(r"(?im)^[^#\n]*_auth(token)?[^#\n]*=")
+
+
+def _skl005_hidden_config(root: Path) -> list[Finding]:
+    findings = []
+    for rel, path in _walk_skill(root):
+        if path.is_symlink() or not path.is_file():
+            continue
+        lowered = path.name.lower()
+        if not (lowered.startswith(".env") or lowered == ".npmrc"):
+            continue
+        text = _text_of(path)
+        if text is None:
+            continue
+        if _SECRET_KEY.search(text) or _AUTH_LINE.search(text):
+            findings.append(Finding("SKL005", "high", rel, "secret in hidden config"))
+    return findings
+
+
+_PERSISTENCE = re.compile(
+    r"(?i)(shell:startup|schtasks(\.exe)?\b|hk(cu|lm)\\[^\n]*\\run\b|crontab\b|launchagents|launchdaemons|systemd)"
+)
+
+
+def _skl006_persistence_hooks(root: Path) -> list[Finding]:
+    findings = []
+    for rel, text in _text_files(root):
+        if _PERSISTENCE.search(text):
+            findings.append(Finding("SKL006", "high", rel, "persistence hook"))
+    return findings
+
+
+_REGISTRY = re.compile(r"(?i)(\bread\s+add\b|regedit\b|set-itemproperty\s+[^\n]*hk(cu|lm):)")
+
+
+def _skl007_registry_changes(root: Path) -> list[Finding]:
+    findings = []
+    for rel, path in _walk_skill(root):
+        if path.is_symlink() or not path.is_file():
+            continue
+        if path.suffix.lower() == ".reg":
+            findings.append(Finding("SKL007", "medium", rel, "windows registry file"))
+            continue
+        text = _text_of(path)
+        if text is not None and _REGISTRY.search(text):
+            findings.append(Finding("SKL007", "medium", rel, "registry modification command"))
+    return findings
+
+
+_NATIVE = re.compile(r"(?i)(ctypes|dlopen|loadlibrary|cffi|require\s*\(\s*['\"][^'\"]*\.node['\"]\s*\))")
+_NATIVE_SUFFIXES = frozenset({".node", ".pyd"})
+
+
+def _skl008_native_loading(root: Path) -> list[Finding]:
+    findings = []
+    for rel, path in _walk_skill(root):
+        if path.is_symlink() or not path.is_file():
+            continue
+        if path.suffix.lower() in _NATIVE_SUFFIXES:
+            findings.append(Finding("SKL008", "high", rel, "native module file"))
+            continue
+        text = _text_of(path)
+        if text is not None and _NATIVE.search(text):
+            findings.append(Finding("SKL008", "high", rel, "native code loading call"))
+    return findings
+
+
+_ENV_ACCESS = re.compile(
+    r"(?i)(os\.environ|process\.env|\bgetenv\b|env\.var|aws_secret_access_key|gh_token|github_token|openai_api_key|anthropic_api_key)"
+)
+
+
+def _skl009_environment_access(root: Path) -> list[Finding]:
+    findings = []
+    for rel, text in _text_files(root):
+        if _ENV_ACCESS.search(text):
+            findings.append(Finding("SKL009", "medium", rel, "environment secret access"))
+    return findings
+
+
+_B64_BLOB = re.compile(r"[A-Za-z0-9+/]{200,}={0,2}")
+_DYNAMIC_EXEC = re.compile(r"(?i)\b(eval|exec)\s*\(")
+
+
+def _skl010_evasion(root: Path) -> list[Finding]:
+    findings = []
+    for rel, text in _text_files(root):
+        if _B64_BLOB.search(text):
+            findings.append(Finding("SKL010", "medium", rel, "possible obfuscated blob"))
+        elif _DYNAMIC_EXEC.search(text):
+            findings.append(Finding("SKL010", "medium", rel, "dynamic code execution"))
+    return findings
+
+
+RULES = (
+    Check("SKL001", "high", "symlink escape", _skl001_symlink_escape),
+    Check("SKL002", "medium", "parent reference in link target", _skl002_parent_reference),
+    Check("SKL003", "medium", "executable or script file", _skl003_executables),
+    Check("SKL004", "high", "unsafe archive member", _skl004_archive_members),
+    Check("SKL005", "high", "secret in hidden config", _skl005_hidden_config),
+    Check("SKL006", "high", "persistence hook", _skl006_persistence_hooks),
+    Check("SKL007", "medium", "registry change", _skl007_registry_changes),
+    Check("SKL008", "high", "native code loading", _skl008_native_loading),
+    Check("SKL009", "medium", "environment secret access", _skl009_environment_access),
+    Check("SKL010", "medium", "possible obfuscation", _skl010_evasion),
+)