alysis-code 0.13.0__py3-none-any.whl

alysis_code/skills/install.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from time import strftime
+
+from .paths import global_managed_skill_root, project_managed_skill_root, skill_bundle_dir_name
+from .state import (
+    ManagedSkillRecord,
+    SkillLifecycleError,
+    load_global_skill_state,
+    load_project_skill_state,
+    resolve_managed_bundle_path,
+    save_global_skill_state,
+    save_project_skill_state,
+    with_managed_install,
+    without_managed_install,
+)
+from .transactions import commit_managed_bundle_removal, commit_managed_bundle_update
+from .validation import SkillValidationResult, validate_skill_bundle
+
+MAX_SKILL_ZIP_FILES = 256
+MAX_SKILL_ZIP_UNCOMPRESSED_BYTES = 8 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class SkillInstallResult:
+    bundle_path: Path
+    installed_name: str
+    source_kind: str
+    source_commit: str | None = None
+    validation: SkillValidationResult | None = None
+
+
+@dataclass(frozen=True)
+class SkillRemoveResult:
+    bundle_path: Path | None
+    removed_name: str
+    scope: str
+
+
+def install_skill_bundle(
+    *,
+    source: str,
+    workspace_root: Path,
+    project: bool = False,
+    subdir: str | None = None,
+    force: bool = False,
+    user_config_dir: Path | None = None,
+) -> SkillInstallResult:
+    with tempfile.TemporaryDirectory(prefix="alysis-skill-install-") as temp_dir:
+        temp_root = Path(temp_dir)
+        source_kind, source_root, source_commit = _materialize_install_source(
+            source=source,
+            temp_root=temp_root,
+        )
+        bundle = _resolve_install_bundle(source_root=source_root, subdir=subdir)
+        validation = validate_skill_bundle(bundle)
+        if not validation.valid:
+            raise SkillLifecycleError(_format_validation_failure(validation))
+        target_root = (
+            project_managed_skill_root(workspace_root)
+            if project
+            else global_managed_skill_root(user_config_dir=user_config_dir)
+        )
+        bundle_dir = skill_bundle_dir_name(validation.name)
+        target_path = resolve_managed_bundle_path(managed_root=target_root, bundle_dir=bundle_dir)
+        record = ManagedSkillRecord(
+            name=validation.name,
+            bundle_dir=bundle_dir,
+            scope=("project" if project else "user"),
+            source_kind=source_kind,
+            source=source,
+            source_subdir=(str(subdir).strip() or None),
+            source_commit=source_commit,
+            installed_at=strftime("%Y-%m-%dT%H:%M:%SZ"),
+        )
+        if project:
+            state = with_managed_install(load_project_skill_state(workspace_root), record)
+            commit_managed_bundle_update(
+                target_path=target_path,
+                force=force,
+                stage_bundle=lambda staged: shutil.copytree(bundle, staged),
+                persist_state=lambda: save_project_skill_state(workspace_root, state),
+            )
+        else:
+            state = with_managed_install(
+                load_global_skill_state(user_config_dir=user_config_dir),
+                record,
+            )
+            commit_managed_bundle_update(
+                target_path=target_path,
+                force=force,
+                stage_bundle=lambda staged: shutil.copytree(bundle, staged),
+                persist_state=lambda: save_global_skill_state(
+                    state,
+                    user_config_dir=user_config_dir,
+                ),
+            )
+        return SkillInstallResult(
+            bundle_path=target_path,
+            installed_name=validation.name,
+            source_kind=source_kind,
+            source_commit=source_commit,
+            validation=validation,
+        )
+
+
+def remove_managed_skill(
+    *,
+    name: str,
+    workspace_root: Path,
+    project: bool = False,
+    user_config_dir: Path | None = None,
+) -> SkillRemoveResult:
+    key = str(name or "").strip().casefold()
+    if not key:
+        raise SkillLifecycleError("Skill name cannot be empty.")
+    if project:
+        state = load_project_skill_state(workspace_root)
+        record = state.managed_installs.get(key)
+        if record is None:
+            raise SkillLifecycleError(f"Managed project skill not found: {name}")
+        bundle_path = resolve_managed_bundle_path(
+            managed_root=project_managed_skill_root(workspace_root),
+            bundle_dir=record.bundle_dir,
+        )
+        commit_managed_bundle_removal(
+            target_path=bundle_path,
+            persist_state=lambda: save_project_skill_state(
+                workspace_root,
+                without_managed_install(state, name),
+            ),
+        )
+        return SkillRemoveResult(bundle_path=bundle_path, removed_name=record.name, scope="project")
+    state = load_global_skill_state(user_config_dir=user_config_dir)
+    record = state.managed_installs.get(key)
+    if record is None:
+        raise SkillLifecycleError(f"Managed user skill not found: {name}")
+    bundle_path = resolve_managed_bundle_path(
+        managed_root=global_managed_skill_root(user_config_dir=user_config_dir),
+        bundle_dir=record.bundle_dir,
+    )
+    commit_managed_bundle_removal(
+        target_path=bundle_path,
+        persist_state=lambda: save_global_skill_state(
+            without_managed_install(state, name),
+            user_config_dir=user_config_dir,
+        ),
+    )
+    return SkillRemoveResult(bundle_path=bundle_path, removed_name=record.name, scope="user")
+
+
+def _materialize_install_source(
+    *,
+    source: str,
+    temp_root: Path,
+) -> tuple[str, Path, str | None]:
+    raw_source = str(source or "").strip()
+    if not raw_source:
+        raise SkillLifecycleError("Install source cannot be empty.")
+    source_path = Path(raw_source).expanduser()
+    if source_path.exists() and source_path.is_dir():
+        return "dir", source_path.resolve(), None
+    if source_path.exists() and source_path.is_file() and source_path.suffix.casefold() == ".zip":
+        extract_root = temp_root / "zip"
+        extract_root.mkdir(parents=True, exist_ok=True)
+        _extract_skill_zip(source_path.resolve(), extract_root)
+        return "zip", extract_root, None
+    return _clone_git_source(raw_source, temp_root / "git")
+
+
+def _resolve_install_bundle(*, source_root: Path, subdir: str | None) -> Path:
+    root = source_root.resolve()
+    if subdir:
+        candidate = (root / Path(subdir)).resolve()
+        try:
+            candidate.relative_to(root)
+        except ValueError as exc:
+            raise SkillLifecycleError("Install subdir escapes the source root.") from exc
+        root = candidate
+    if (root / "SKILL.md").is_file():
+        return root
+    candidates: list[Path] = []
+    for entry in root.rglob("SKILL.md"):
+        if ".git" in entry.parts:
+            continue
+        candidates.append(entry.parent)
+    if not candidates:
+        raise SkillLifecycleError("No skill bundle found in install source.")
+    if len(candidates) > 1:
+        raise SkillLifecycleError(
+            "Install source contains multiple skill bundles; use --subdir to choose one."
+        )
+    return candidates[0]
+
+
+def _extract_skill_zip(zip_path: Path, target_root: Path) -> None:
+    try:
+        archive = zipfile.ZipFile(zip_path)
+    except OSError as exc:
+        raise SkillLifecycleError(f"Failed to open zip archive: {zip_path}") from exc
+    with archive:
+        file_infos: list[tuple[zipfile.ZipInfo, list[str]]] = []
+        total_uncompressed = 0
+        for info in archive.infolist():
+            if _is_zip_symlink(info):
+                raise SkillLifecycleError(
+                    "Zip archive contains symlink entries, which are not allowed."
+                )
+            if info.is_dir():
+                continue
+            parts = _sanitize_zip_parts(info.filename)
+            if not parts:
+                continue
+            file_infos.append((info, parts))
+            if len(file_infos) > MAX_SKILL_ZIP_FILES:
+                raise SkillLifecycleError(
+                    f"Zip archive exceeds file-count limit ({MAX_SKILL_ZIP_FILES} files)."
+                )
+            total_uncompressed += max(0, int(info.file_size))
+            if total_uncompressed > MAX_SKILL_ZIP_UNCOMPRESSED_BYTES:
+                raise SkillLifecycleError(
+                    "Zip archive exceeds uncompressed-size limit "
+                    f"({MAX_SKILL_ZIP_UNCOMPRESSED_BYTES} bytes)."
+                )
+        for info, parts in file_infos:
+            destination = _resolve_zip_target(target_root, parts)
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            with archive.open(info, "r") as src, destination.open("wb") as dst:
+                shutil.copyfileobj(src, dst)
+
+
+def _clone_git_source(source: str, target_root: Path) -> tuple[str, Path, str | None]:
+    if shutil.which("git") is None:
+        raise SkillLifecycleError("git is required for git-based skill installs.")
+    try:
+        subprocess.run(
+            ["git", "clone", "--depth", "1", source, str(target_root)],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        stderr = str(exc.stderr or "").strip()
+        raise SkillLifecycleError(f"Failed to clone git skill source: {stderr or source}") from exc
+    commit = None
+    try:
+        completed = subprocess.run(
+            ["git", "-C", str(target_root), "rev-parse", "HEAD"],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        commit = str(completed.stdout or "").strip() or None
+    except subprocess.CalledProcessError:
+        commit = None
+    return "git", target_root, commit
+
+
+def _is_zip_symlink(info: zipfile.ZipInfo) -> bool:
+    return bool((info.external_attr >> 16) & 0o170000 == 0o120000)
+
+
+def _sanitize_zip_parts(name: str) -> list[str]:
+    clean_name = str(name or "").replace("\\", "/")
+    path = PurePosixPath(clean_name)
+    parts = [part for part in path.parts if part not in {"", "."}]
+    if any(part == ".." for part in parts):
+        raise SkillLifecycleError("Zip archive entry escapes extraction root.")
+    if path.is_absolute():
+        raise SkillLifecycleError("Zip archive contains absolute paths, which are not allowed.")
+    return parts
+
+
+def _resolve_zip_target(base: Path, rel_parts: list[str]) -> Path:
+    target = base.joinpath(*rel_parts).resolve()
+    try:
+        target.relative_to(base.resolve())
+    except ValueError as exc:
+        raise SkillLifecycleError("Zip archive entry escapes extraction root.") from exc
+    return target
+
+
+def _format_validation_failure(result: SkillValidationResult) -> str:
+    if not result.issues:
+        return f"Skill validation failed: {result.bundle_path}"
+    first = result.issues[0]
+    return f"Skill validation failed: {first.message} ({first.path})"

alysis_code/skills/loader.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .models import SkillBundle, SkillDiscoveryIssue, SkillSourceKind, SkillSourceScope
+from .validation import validate_skill_bundle
+
+
+class SkillReadError(RuntimeError):
+    pass
+
+
+def load_skill_bundle(
+    *,
+    bundle_path: Path,
+    source_scope: SkillSourceScope,
+    source_kind: SkillSourceKind,
+    source_family: str,
+    ancestor_distance: int | None,
+) -> tuple[SkillBundle | None, SkillDiscoveryIssue | None]:
+    validation = validate_skill_bundle(bundle_path)
+    if not validation.valid:
+        first_error = next(iter(validation.errors))
+        return None, SkillDiscoveryIssue(
+            source_path=bundle_path,
+            message=first_error.message,
+        )
+
+    bundle_name = bundle_path.name.strip() or validation.name
+    aliases = _ordered_unique_strings(
+        [validation.name, bundle_name, *_metadata_aliases(validation.metadata)]
+    )
+    return (
+        SkillBundle(
+            name=validation.name,
+            description=validation.description,
+            instructions=validation.instructions,
+            bundle_name=bundle_name,
+            bundle_path=bundle_path,
+            entry_path=validation.entry_path,
+            source_scope=source_scope,
+            source_kind=source_kind,
+            source_family=source_family,
+            source_path=bundle_path,
+            trust_level="untrusted",
+            ancestor_distance=ancestor_distance,
+            aliases=tuple(aliases),
+            metadata={
+                key: str(value)
+                for key, value in validation.metadata.items()
+                if key in {"name", "description"} and str(value).strip()
+            },
+        ),
+        None,
+    )
+
+
+def read_skill_bundle_file(skill: SkillBundle, path: str | None = None) -> dict[str, Any]:
+    requested_path = str(path or "").strip()
+    if not requested_path:
+        target_path = skill.entry_path
+        relative_path = "SKILL.md"
+    else:
+        candidate = Path(requested_path)
+        if candidate.is_absolute():
+            raise SkillReadError("skill_read path must be relative to the skill bundle root")
+        target_path = (skill.bundle_path / candidate).resolve()
+        bundle_root = skill.bundle_path.resolve()
+        try:
+            target_path.relative_to(bundle_root)
+        except ValueError as exc:
+            raise SkillReadError("skill_read path escapes the skill bundle root") from exc
+        try:
+            relative_path = target_path.relative_to(bundle_root).as_posix()
+        except ValueError as exc:
+            raise SkillReadError("skill_read path escapes the skill bundle root") from exc
+    if not target_path.exists() or not target_path.is_file():
+        raise SkillReadError(f"Skill file not found: {requested_path or 'SKILL.md'}")
+    try:
+        content = target_path.read_text(encoding="utf-8")
+    except UnicodeDecodeError as exc:
+        raise SkillReadError(f"Skill file is not readable as UTF-8 text: {relative_path}") from exc
+    except OSError as exc:
+        raise SkillReadError(f"Failed to read skill file: {relative_path}") from exc
+    return {
+        "name": skill.name,
+        "bundle_name": skill.bundle_name,
+        "path": relative_path,
+        "content": content,
+        "source_scope": skill.source_scope,
+        "source_kind": skill.source_kind,
+        "source_family": skill.source_family,
+        "source_path": skill.source_path.as_posix(),
+        "trust_level": skill.trust_level,
+    }
+
+
+def _ordered_unique_strings(values: list[str]) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    for raw in values:
+        value = str(raw or "").strip()
+        if not value:
+            continue
+        lowered = value.casefold()
+        if lowered in seen:
+            continue
+        seen.add(lowered)
+        out.append(value)
+    return out
+
+
+def _metadata_aliases(metadata: dict[str, Any]) -> list[str]:
+    raw = metadata.get("aliases")
+    if isinstance(raw, list):
+        return [str(item).strip() for item in raw if str(item).strip()]
+    return []

alysis_code/skills/matching.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import re
+
+from .models import SkillBundle, SkillMatch
+
+_TOKEN_RE = re.compile(r"[a-z0-9][a-z0-9_./+-]*", re.IGNORECASE)
+_STOPWORDS = {
+    "a",
+    "an",
+    "and",
+    "build",
+    "do",
+    "for",
+    "help",
+    "i",
+    "in",
+    "is",
+    "it",
+    "me",
+    "my",
+    "of",
+    "on",
+    "please",
+    "the",
+    "this",
+    "to",
+    "we",
+    "with",
+}
+
+
+def match_skills(
+    request: str,
+    *,
+    skills: list[SkillBundle] | tuple[SkillBundle, ...],
+    max_results: int = 5,
+) -> tuple[SkillMatch, ...]:
+    request_text = str(request or "").strip()
+    if not request_text:
+        return ()
+    request_tokens = _tokenize(request_text)
+    if not request_tokens:
+        return ()
+    matches: list[SkillMatch] = []
+    request_lower = request_text.casefold()
+    for skill in skills:
+        name_tokens = _tokenize(skill.name)
+        description_tokens = _tokenize(skill.description)
+        score = 0
+        matched_terms: list[str] = []
+        if skill.name.casefold() in request_lower or skill.bundle_name.casefold() in request_lower:
+            score += 12
+            matched_terms.append(skill.name)
+        overlap = sorted(request_tokens & name_tokens)
+        if overlap:
+            score += len(overlap) * 5
+            matched_terms.extend(overlap)
+        desc_overlap = sorted(request_tokens & description_tokens)
+        if desc_overlap:
+            score += len(desc_overlap) * 2
+            matched_terms.extend(desc_overlap)
+        if score <= 0:
+            continue
+        matches.append(
+            SkillMatch(
+                skill=skill,
+                score=score,
+                matched_terms=tuple(_ordered_unique(matched_terms)),
+            )
+        )
+    matches.sort(
+        key=lambda item: (
+            -item.score,
+            item.skill.name.casefold(),
+            item.skill.bundle_path.as_posix(),
+        )
+    )
+    return tuple(matches[: max(0, max_results)])
+
+
+def _tokenize(text: str) -> set[str]:
+    tokens = {
+        token.casefold()
+        for token in _TOKEN_RE.findall(str(text or ""))
+        if token and token.casefold() not in _STOPWORDS
+    }
+    return {token for token in tokens if len(token) > 1}
+
+
+def _ordered_unique(values: list[str]) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    for raw in values:
+        value = str(raw or "").strip()
+        if not value:
+            continue
+        lowered = value.casefold()
+        if lowered in seen:
+            continue
+        seen.add(lowered)
+        out.append(value)
+    return out

alysis_code/skills/models.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+SkillSourceScope = Literal["project", "user"]
+SkillSourceKind = Literal["native", "interop"]
+SkillTrustLevel = Literal["untrusted"]
+
+
+@dataclass(frozen=True)
+class SkillBundle:
+    name: str
+    description: str
+    instructions: str
+    bundle_name: str
+    bundle_path: Path
+    entry_path: Path
+    source_scope: SkillSourceScope
+    source_kind: SkillSourceKind
+    source_family: str
+    source_path: Path
+    trust_level: SkillTrustLevel
+    ancestor_distance: int | None = None
+    aliases: tuple[str, ...] = ()
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    @property
+    def source_label(self) -> str:
+        return f"{self.source_scope}/{self.source_kind}"
+
+    def lookup_keys(self) -> tuple[str, ...]:
+        keys: list[str] = []
+        for value in (self.name, self.bundle_name, *self.aliases):
+            candidate = str(value or "").strip()
+            if not candidate:
+                continue
+            lowered = candidate.casefold()
+            if lowered in keys:
+                continue
+            keys.append(lowered)
+        return tuple(keys)
+
+
+@dataclass(frozen=True)
+class SkillDiscoveryIssue:
+    source_path: Path
+    message: str
+
+
+@dataclass(frozen=True)
+class DiscoveredSkills:
+    skills: dict[str, SkillBundle]
+    ordered: tuple[SkillBundle, ...]
+    issues: tuple[SkillDiscoveryIssue, ...] = ()
+
+
+@dataclass(frozen=True)
+class SkillMatch:
+    skill: SkillBundle
+    score: int
+    matched_terms: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ConventionDocument:
+    name: str
+    path: Path
+    content: str
+    trust_level: SkillTrustLevel = "untrusted"

alysis_code/skills/paths.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Literal
+
+from ..branding import canonical_user_config_dir
+
+ProjectSkillFamily = Literal["native", "agents", "claude", "github"]
+
+_PROJECT_FAMILY_ROOTS: dict[ProjectSkillFamily, tuple[str, ...]] = {
+    "native": (".alysis_skills",),
+    "agents": (".agents", "skills"),
+    "claude": (".claude", "skills"),
+    "github": (".github", "skills"),
+}
+
+
+def global_managed_skill_root(*, user_config_dir: Path | None = None) -> Path:
+    base = (
+        user_config_dir.expanduser().resolve() if user_config_dir else canonical_user_config_dir()
+    )
+    return base / "skills"
+
+
+def global_skills_state_path(*, user_config_dir: Path | None = None) -> Path:
+    base = (
+        user_config_dir.expanduser().resolve() if user_config_dir else canonical_user_config_dir()
+    )
+    return base / "skills.json"
+
+
+def project_managed_skill_root(workspace_root: Path) -> Path:
+    return workspace_root.expanduser().resolve() / ".alysis_skills"
+
+
+def project_skills_state_path(workspace_root: Path) -> Path:
+    return workspace_root.expanduser().resolve() / ".alysis" / "skills.json"
+
+
+def project_skill_root_for_family(workspace_root: Path, *, family: ProjectSkillFamily) -> Path:
+    return workspace_root.expanduser().resolve().joinpath(*_PROJECT_FAMILY_ROOTS[family])
+
+
+def normalize_project_skill_family(raw: str | None) -> ProjectSkillFamily:
+    normalized = str(raw or "native").strip().lower()
+    if normalized in _PROJECT_FAMILY_ROOTS:
+        return normalized  # type: ignore[return-value]
+    raise ValueError("Unsupported skill family. Expected one of: native, agents, claude, github.")
+
+
+def skill_bundle_dir_name(raw_name: str) -> str:
+    candidate = re.sub(r"[^a-z0-9._-]+", "-", str(raw_name or "").strip().casefold()).strip("-")
+    if not candidate:
+        raise ValueError("Skill name must contain at least one letter or digit.")
+    return candidate