super-skill-cli 0.9.2__py3-none-any.whl

super_skill/registry.py

@@ -0,0 +1,221 @@
+"""Git-backed registry (WS backend).
+
+Each skill is a directory under ``registry/skills/<skill_id>/`` holding immutable
+``versions/<version>/SKILL.md`` snapshots plus a ``meta.json`` aggregate (Skill
+pointer + SkillVersion DAG + audit trail). Git provides integrity, audit history
+and rollback; M1 replaces this with the SQLite Registry + signed Publisher
+without changing the entity shapes (docs/03 §3 M1, docs/02 §7.7).
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from . import config
+from .schemas import (
+    AuditEvent,
+    CandidateType,
+    OperationType,
+    Provenance,
+    Scope,
+    Skill,
+    SkillStatus,
+    SkillVersion,
+)
+from .skillmd import content_hash, parse
+
+_GIT_ID = ["-c", "user.name=super-skill", "-c", "user.email=super-skill@localhost"]
+
+
+class SkillRecord(BaseModel):
+    """Per-skill aggregate persisted as meta.json."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    skill: Skill
+    versions: dict[str, SkillVersion] = Field(default_factory=dict)
+    audit: list[AuditEvent] = Field(default_factory=list)
+
+    @property
+    def active(self) -> SkillVersion | None:
+        v = self.skill.active_version
+        return self.versions.get(v) if v else None
+
+    def next_version(self) -> str:
+        nums = [int(k.lstrip("v")) for k in self.versions if k.lstrip("v").isdigit()]
+        return f"v{1 + max(nums, default=0)}"
+
+
+class RegistryError(RuntimeError):
+    pass
+
+
+class Registry:
+    """WS registry rooted at a state dir (injectable for tests)."""
+
+    def __init__(self, root: Path | None = None) -> None:
+        self.root = root or config.state_root()
+        self.skills_root = self.root / "registry" / "skills"
+
+    # ---- lifecycle ---------------------------------------------------------
+    def init(self) -> None:
+        self.skills_root.mkdir(parents=True, exist_ok=True)
+        # candidates/ holds pre-promotion draft scratch — kept out of tracked
+        # history so only approve (the Publisher path) writes registry state.
+        gitignore = "locks/\ncandidates/\n"
+        gi = self.root / ".gitignore"
+        if not (self.root / ".git").exists():
+            self._git("init", "-q")
+            gi.write_text(gitignore, encoding="utf-8")
+            self._commit("chore: initialize super-skill registry")
+        elif gi.exists() and "candidates/" not in gi.read_text(encoding="utf-8"):
+            gi.write_text(gitignore, encoding="utf-8")
+            self._commit("chore: ignore candidates/ scratch dir")
+
+    def _git(self, *args: str) -> str:
+        proc = subprocess.run(
+            ["git", "-C", str(self.root), *args],
+            capture_output=True,
+            text=True,
+        )
+        if proc.returncode != 0:
+            raise RegistryError(f"git {' '.join(args)} failed: {proc.stderr.strip()}")
+        return proc.stdout.strip()
+
+    def _commit(self, message: str) -> str:
+        self._git("add", "-A")
+        # nothing staged is not an error (idempotent re-runs)
+        status = self._git("status", "--porcelain")
+        if not status:
+            return self.head()
+        subprocess.run(
+            ["git", "-C", str(self.root), *_GIT_ID, "commit", "-q", "-m", message],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        return self.head()
+
+    def head(self) -> str:
+        try:
+            return self._git("rev-parse", "--short", "HEAD")
+        except RegistryError:
+            return "(no commits)"
+
+    # ---- reads -------------------------------------------------------------
+    def _meta_path(self, skill_id: str) -> Path:
+        return self.skills_root / skill_id / "meta.json"
+
+    def get(self, skill_id: str) -> SkillRecord | None:
+        p = self._meta_path(skill_id)
+        if not p.exists():
+            return None
+        return SkillRecord.model_validate_json(p.read_text(encoding="utf-8"))
+
+    def list_skills(self) -> list[SkillRecord]:
+        if not self.skills_root.exists():
+            return []
+        out = [self.get(d.name) for d in sorted(self.skills_root.iterdir()) if d.is_dir()]
+        return [r for r in out if r is not None]
+
+    def version_text(self, skill_id: str, version: str) -> str:
+        p = self.skills_root / skill_id / "versions" / version / "SKILL.md"
+        if not p.exists():
+            raise RegistryError(f"{skill_id}@{version} has no SKILL.md")
+        return p.read_text(encoding="utf-8")
+
+    # ---- writes ------------------------------------------------------------
+    def add_version(
+        self,
+        skill_id: str,
+        raw: str,
+        candidate_type: CandidateType,
+        provenance: list[Provenance],
+        *,
+        status: SkillStatus = SkillStatus.ACTIVE,
+        scope: Scope = Scope.GLOBAL,
+        make_active: bool = True,
+        actor: str = "user",
+        reason: str | None = None,
+        commit: bool = True,
+    ) -> SkillVersion:
+        """Register a new immutable version; optionally make it the active pointer."""
+        parsed = parse(raw)
+        rec = self.get(skill_id) or SkillRecord(skill=Skill(skill_id=skill_id, scope=scope))
+        version = rec.next_version()
+        parents = [rec.skill.active_version] if rec.skill.active_version else []
+        sv = SkillVersion(
+            skill_id=skill_id,
+            version=version,
+            parent_versions=[p for p in parents if p],
+            candidate_type=candidate_type,
+            status=status,
+            artifact_hash=content_hash(raw),
+            frontmatter=parsed.frontmatter,
+            provenance=provenance,
+        )
+        vdir = self.skills_root / skill_id / "versions" / version
+        vdir.mkdir(parents=True, exist_ok=True)
+        (vdir / "SKILL.md").write_text(parsed.raw, encoding="utf-8")
+
+        rec.versions[version] = sv
+        prev = rec.skill.active_version
+        if make_active:
+            rec.skill.active_version = version
+        rec.audit.append(
+            AuditEvent(
+                skill_id=skill_id,
+                op=OperationType.PROMOTE,
+                from_version=prev,
+                to_version=version if make_active else prev,
+                actor=actor,
+                reason=reason,
+                artifact_hash=sv.artifact_hash,
+            )
+        )
+        self._write(rec)
+        if commit:
+            self._commit(f"promote: {skill_id}@{version} ({candidate_type})")
+        return sv
+
+    def set_active(
+        self, skill_id: str, version: str, *, op: OperationType, actor: str = "user",
+        reason: str | None = None, commit: bool = True,
+    ) -> SkillRecord:
+        """Switch the active-version pointer (rollback = point at an older version)."""
+        rec = self.get(skill_id)
+        if rec is None:
+            raise RegistryError(f"unknown skill {skill_id!r}")
+        if version not in rec.versions:
+            raise RegistryError(f"{skill_id} has no version {version!r}")
+        prev = rec.skill.active_version
+        rec.skill.active_version = version
+        rec.audit.append(
+            AuditEvent(skill_id=skill_id, op=op, from_version=prev, to_version=version,
+                       actor=actor, reason=reason)
+        )
+        self._write(rec)
+        if commit:
+            self._commit(f"{op.lower()}: {skill_id} -> {version}")
+        return rec
+
+    def _write(self, rec: SkillRecord) -> None:
+        p = self._meta_path(rec.skill.skill_id)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(rec.model_dump_json(indent=2), encoding="utf-8")
+
+    # ---- distribution ------------------------------------------------------
+    def materialize(self, skill_id: str, host_dir: Path) -> Path:
+        """Write the active version's SKILL.md into the host skills dir so the
+        Agent picks it up. Only writes that one file — never deletes siblings."""
+        rec = self.get(skill_id)
+        if rec is None or rec.skill.active_version is None:
+            raise RegistryError(f"{skill_id!r} has no active version to materialize")
+        raw = self.version_text(skill_id, rec.skill.active_version)
+        dest = host_dir / skill_id / "SKILL.md"
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(raw, encoding="utf-8")
+        return dest

super_skill/schemas.py

@@ -0,0 +1,207 @@
+"""Core data model — single source of truth (M0 deliverable).
+
+Scoped to the v1 package manager. Fields the self-learning loop (M2-M5) needs
+(ExperienceCard, CapabilityLedger, EvalRun, ...) are intentionally absent; they
+land when/if the GATE opens the research track. Entity shapes here mirror
+docs/02-architecture.md §5 so the M1 Registry/Publisher can adopt them unchanged.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from enum import StrEnum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+# agentskills.io spec: name 1-64 chars, lowercase + hyphen, must match dir name.
+NAME_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+def utcnow() -> datetime:
+    """Timezone-aware now(). Centralized so tests can monkeypatch one symbol."""
+    return datetime.now(UTC)
+
+
+class Scope(StrEnum):
+    GLOBAL = "global"
+    PROJECT = "project"
+
+
+class CandidateType(StrEnum):
+    """FR-GEN-3 six types. v1 seed/capture uses CAPTURED/FIX/DISTILLED."""
+
+    FIX = "FIX"
+    DERIVED = "DERIVED"
+    CAPTURED = "CAPTURED"
+    DISTILLED = "DISTILLED"
+    CONSOLIDATED = "CONSOLIDATED"
+    RETIRED = "RETIRED"
+
+
+class SkillStatus(StrEnum):
+    """Lifecycle states (docs/02 §6). v1/WS uses OBSERVED..ACTIVE minus the
+    security-gate states (QUARANTINED/EVALUATED) that need M4 machinery."""
+
+    OBSERVED = "Observed"
+    CANDIDATE = "Candidate"
+    QUARANTINED = "Quarantined"
+    EVALUATED = "Evaluated"
+    STAGED = "Staged"
+    CANARY = "Canary"
+    ACTIVE = "Active"
+    REJECTED = "Rejected"
+    RETIRED = "Retired"
+
+
+class OperationType(StrEnum):
+    """Writes that mutate the active skill set. In WS these are git commits;
+    M1 wraps them in a signed OperationRecord verified by the Publisher."""
+
+    PROMOTE = "PROMOTE"
+    ROLLBACK = "ROLLBACK"
+    REVOKE_CANARY = "REVOKE_CANARY"
+    QUARANTINE = "QUARANTINE"
+    RETIRE = "RETIRE"
+
+
+class ProvenanceKind(StrEnum):
+    SEED_EXISTING_SKILL = "seed_existing_skill"
+    CAPTURED_SESSION = "captured_session"
+    DISTILLED_EXTERNAL = "distilled_external"
+
+
+class EventType(StrEnum):
+    """The six host hook events captured in WS (docs/01 FR-CAP-1)."""
+
+    SESSION_START = "SessionStart"
+    USER_PROMPT_SUBMIT = "UserPromptSubmit"
+    PRE_TOOL_USE = "PreToolUse"
+    POST_TOOL_USE = "PostToolUse"
+    STOP = "Stop"
+    SESSION_END = "SessionEnd"
+
+
+class RedactionMark(BaseModel):
+    """What was redacted and where — never the value (docs/01 FR-CAP-2)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: str
+    location: str = Field(description="dotted path of the field the secret was found in")
+    count: int = 1
+
+
+class CaptureEvent(BaseModel):
+    """One redacted host event appended to the JSONL WAL. WS keeps only observable
+    actions + short outcomes — never hidden chain-of-thought (FR-CAP-7)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    event_id: str
+    session_id: str
+    event_type: EventType
+    project_id: str | None = None
+    timestamp: datetime = Field(default_factory=utcnow)
+    payload: dict[str, Any] = Field(default_factory=dict)
+    redactions: list[RedactionMark] = Field(default_factory=list)
+    consent_scope: str = "default"
+
+
+class Provenance(BaseModel):
+    """Where a version's content came from and under what license."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    kind: ProvenanceKind
+    origin: str = Field(description="path, session id, or source URL")
+    imported_at: datetime = Field(default_factory=utcnow)
+    license: str | None = None
+    notes: str | None = None
+
+
+class SkillFrontmatter(BaseModel):
+    """agentskills.io core frontmatter. Host-specific extensions are NOT held
+    here — they are injected per-host at distribution time (docs/02 §4.2)."""
+
+    model_config = ConfigDict(extra="allow")
+
+    name: str = Field(min_length=1, max_length=64)
+    description: str = Field(min_length=1, max_length=1024)
+    license: str | None = None
+    compatibility: str | None = None
+    metadata: dict[str, Any] | None = None
+
+    @field_validator("name")
+    @classmethod
+    def _name_shape(cls, v: str) -> str:
+        if not NAME_RE.match(v):
+            raise ValueError(
+                f"name must be lowercase alphanumerics + single hyphens (got {v!r})"
+            )
+        return v
+
+
+class SkillVersion(BaseModel):
+    """One immutable node in a skill's version DAG."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    skill_id: str
+    version: str
+    parent_versions: list[str] = Field(default_factory=list)
+    candidate_type: CandidateType
+    status: SkillStatus
+    artifact_hash: str = Field(description="sha256 of the normalized SKILL.md payload")
+    frontmatter: SkillFrontmatter
+    provenance: list[Provenance] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=utcnow)
+
+
+class Skill(BaseModel):
+    """Skill-level state: the active-version pointer that rollback switches,
+    distinct from the SkillVersion DAG nodes (docs/02 §5.1, review H4)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    skill_id: str
+    scope: Scope = Scope.GLOBAL
+    active_version: str | None = None
+    user_disabled: bool = False
+
+
+class OperationRecord(BaseModel):
+    """Record of an active-set mutation. WS fills actor/reason and relies on git
+    for integrity; nonce/registry_state_hash/signature are added at M1 when the
+    real Publisher exists (fields present-but-optional so the shape is stable)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    op: OperationType
+    skill_id: str
+    version: str | None = None
+    rollback_version: str | None = None
+    actor: str = "user"
+    reason: str | None = None
+    created_at: datetime = Field(default_factory=utcnow)
+    # --- M1 (signed Publisher) ---
+    nonce: str | None = None
+    registry_state_hash: str | None = None
+    signature: str | None = None
+
+
+class AuditEvent(BaseModel):
+    """Immutable audit trail entry. In WS these are reconstructable from git
+    history; kept structured so `explain` renders a uniform provenance chain."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    skill_id: str
+    op: OperationType
+    from_version: str | None = None
+    to_version: str | None = None
+    actor: str = "user"
+    reason: str | None = None
+    artifact_hash: str | None = None
+    created_at: datetime = Field(default_factory=utcnow)

super_skill/seed.py

@@ -0,0 +1,75 @@
+"""Seed mode (docs/03 M0, D-3): ingest existing host skills into the registry so
+explain/rollback/list have day-1 value with zero authoring.
+
+Read-only with respect to the host skills directory — it reads each SKILL.md and
+writes only into the registry. Idempotent: unchanged skills are skipped, changed
+ones get a new version.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .registry import Registry
+from .schemas import CandidateType, Provenance, ProvenanceKind, SkillStatus
+from .skillmd import SkillMdError, content_hash, parse
+
+
+@dataclass
+class SeedReport:
+    imported: list[str] = field(default_factory=list)
+    updated: list[str] = field(default_factory=list)
+    unchanged: list[str] = field(default_factory=list)
+    skipped: list[tuple[str, str]] = field(default_factory=list)  # (name, reason)
+
+    @property
+    def total_seen(self) -> int:
+        return len(self.imported) + len(self.updated) + len(self.unchanged) + len(self.skipped)
+
+
+def seed_from_host(reg: Registry, host_dir: Path) -> SeedReport:
+    report = SeedReport()
+    reg.init()
+    if not host_dir.exists():
+        return report
+
+    for d in sorted(p for p in host_dir.iterdir() if p.is_dir()):
+        md = d / "SKILL.md"
+        if not md.exists():
+            report.skipped.append((d.name, "no SKILL.md"))
+            continue
+        raw = md.read_text(encoding="utf-8")
+        try:
+            parsed = parse(raw)
+        except SkillMdError as e:
+            report.skipped.append((d.name, str(e)))
+            continue
+
+        skill_id = parsed.frontmatter.name
+        existing = reg.get(skill_id)
+        if (
+            existing is not None
+            and existing.active is not None
+            and existing.active.artifact_hash == content_hash(raw)
+        ):
+            report.unchanged.append(skill_id)
+            continue
+
+        prov = [Provenance(kind=ProvenanceKind.SEED_EXISTING_SKILL, origin=str(md))]
+        reg.add_version(
+            skill_id,
+            raw,
+            CandidateType.DISTILLED,
+            prov,
+            status=SkillStatus.ACTIVE,
+            actor="seed",
+            reason=f"seed import from {md}",
+            commit=False,
+        )
+        (report.updated if existing else report.imported).append(skill_id)
+
+    reg._commit(
+        f"seed: import {len(report.imported)} new / {len(report.updated)} updated from host"
+    )
+    return report

super_skill/skillmd.py

@@ -0,0 +1,61 @@
+"""Parse and hash SKILL.md files (YAML frontmatter + markdown body)."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+
+import yaml
+
+from .schemas import SkillFrontmatter
+
+_FENCE = "---"
+
+
+class SkillMdError(ValueError):
+    """Malformed SKILL.md (missing/broken frontmatter)."""
+
+
+@dataclass(frozen=True)
+class ParsedSkillMd:
+    frontmatter: SkillFrontmatter
+    body: str
+    raw: str
+
+
+def normalize(text: str) -> str:
+    """Strip BOM and CRLF so hashes ignore meaningless byte differences
+    (docs/02 §4.2 normalized hash)."""
+    return text.lstrip("").replace("\r\n", "\n").replace("\r", "\n")
+
+
+def content_hash(text: str) -> str:
+    return "sha256:" + hashlib.sha256(normalize(text).encode("utf-8")).hexdigest()
+
+
+def parse(text: str) -> ParsedSkillMd:
+    """Split a SKILL.md into validated frontmatter + body.
+
+    Frontmatter is the first ``---``-fenced YAML block. Raises SkillMdError if
+    absent or not a mapping — the seed importer skips such directories rather
+    than registering an invalid skill.
+    """
+    norm = normalize(text)
+    if not norm.startswith(_FENCE):
+        raise SkillMdError("missing YAML frontmatter fence")
+    end = norm.find(f"\n{_FENCE}", len(_FENCE))
+    if end == -1:
+        raise SkillMdError("unterminated frontmatter fence")
+    fm_text = norm[len(_FENCE) : end]
+    body = norm[end + len(_FENCE) + 1 :].lstrip("\n")
+    try:
+        data = yaml.safe_load(fm_text)
+    except yaml.YAMLError as e:
+        raise SkillMdError(f"invalid frontmatter YAML: {e}") from e
+    if not isinstance(data, dict):
+        raise SkillMdError("frontmatter is not a mapping")
+    try:
+        fm = SkillFrontmatter.model_validate(data)
+    except ValueError as e:
+        raise SkillMdError(f"frontmatter failed validation: {e}") from e
+    return ParsedSkillMd(frontmatter=fm, body=body, raw=norm)