drskill 0.1.0__py3-none-any.whl

drskill/discovery.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from drskill.harnesses import HarnessDef
+from drskill.models import BrokenSymlink, RawInstance
+
+
+def _walk_dirs(base: Path):
+    """os.walk following symlinks, guarded against loops."""
+    seen: set[str] = set()
+    for dirpath, dirnames, filenames in os.walk(base, followlinks=True):
+        real = os.path.realpath(dirpath)
+        if real in seen:
+            dirnames[:] = []
+            continue
+        seen.add(real)
+        yield Path(dirpath), dirnames, filenames
+
+
+def _find_skill_files(base: Path, recursive: bool) -> list[Path]:
+    if not recursive:
+        return sorted(base.glob("*/SKILL.md"))
+    out = []
+    for dirpath, _dirnames, filenames in _walk_dirs(base):
+        if "SKILL.md" in filenames:
+            out.append(dirpath / "SKILL.md")
+    return sorted(out)
+
+
+def _find_broken_symlinks(base: Path, recursive: bool = True) -> list[Path]:
+    out = []
+    if not recursive:
+        # Check only entries directly in base and in base/* directories (depth matching */SKILL.md glob)
+        for name in os.listdir(base):
+            p = base / name
+            if p.is_symlink() and not p.exists():
+                out.append(p)
+        # Also check one level deep (base/*/...)
+        for subdir in base.iterdir():
+            if subdir.is_dir():
+                for name in os.listdir(subdir):
+                    p = subdir / name
+                    if p.is_symlink() and not p.exists():
+                        out.append(p)
+    else:
+        for dirpath, dirnames, filenames in _walk_dirs(base):
+            for name in list(dirnames) + list(filenames):
+                p = dirpath / name
+                if p.is_symlink() and not p.exists():
+                    out.append(p)
+    return sorted(out)
+
+
+def _via_symlink(f: Path, base: Path) -> bool:
+    cur = f
+    while True:
+        if cur.is_symlink():
+            return True
+        if cur == base or cur.parent == cur:
+            return False
+        cur = cur.parent
+
+
+def discover(
+    h: HarnessDef, project_root: Path, home: Path, global_only: bool = False
+) -> tuple[list[RawInstance], list[BrokenSymlink]]:
+    instances: list[RawInstance] = []
+    broken: list[BrokenSymlink] = []
+    for order, (base, scope, spec_str) in enumerate(
+        h.search_paths(project_root, home, global_only)
+    ):
+        if not base.is_dir():
+            continue
+        files = _find_skill_files(base, h.recursive)
+        if spec_str in h.root_md_paths:
+            files += sorted(
+                p for p in base.glob("*.md")
+                if p.name != "SKILL.md" and p.is_file()
+            )
+        for f in files:
+            # Skip dangling symlinks (they are already reported as broken)
+            if not f.exists():
+                continue
+            instances.append(
+                RawInstance(
+                    harness=h.id,
+                    scope=scope,
+                    skill_file=f,
+                    via_symlink=_via_symlink(f, base),
+                    order=order,
+                )
+            )
+        broken += [BrokenSymlink(harness=h.id, path=p) for p in _find_broken_symlinks(base, h.recursive)]
+    return instances, broken

drskill/harnesses.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import tomllib
+from functools import cache
+from importlib import resources
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class HarnessDef(BaseModel):
+    id: str
+    display_name: str
+    verified: bool = False
+    detect: list[str] = Field(default_factory=list)
+    project_paths: list[str] = Field(default_factory=list)
+    global_paths: list[str] = Field(default_factory=list)
+    search_order: Literal["project-first", "global-first"] = "project-first"
+    recursive: bool = True
+    root_md_paths: list[str] = Field(default_factory=list)
+
+    def search_paths(
+        self, project_root: Path, home: Path, global_only: bool = False
+    ) -> list[tuple[Path, str, str]]:
+        """(directory, scope, spec_str) triples in precedence order."""
+        proj = [(project_root / s, "project", s) for s in self.project_paths]
+        glob = [(home / s.removeprefix("~/"), "user", s) for s in self.global_paths]
+        if global_only:
+            return glob
+        if self.search_order == "global-first":
+            return glob + proj
+        return proj + glob
+
+
+@cache
+def load_harnesses() -> tuple[HarnessDef, ...]:
+    text = resources.files("drskill.data").joinpath("harnesses.toml").read_text()
+    data = tomllib.loads(text)
+    return tuple(HarnessDef(**h) for h in data["harness"])
+
+
+def detect_harnesses(
+    project_root: Path, home: Path, global_only: bool = False
+) -> list[HarnessDef]:
+    found = []
+    for h in load_harnesses():
+        for marker in h.detect:
+            if marker.startswith("~/"):
+                p = home / marker.removeprefix("~/")
+            elif global_only:
+                continue
+            else:
+                p = project_root / marker
+            if p.exists():
+                found.append(h)
+                break
+    return found

drskill/ledger.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import datetime as dt
+import tomllib
+from pathlib import Path
+
+import tomli_w
+from pydantic import BaseModel, Field, ValidationError
+
+from drskill.models import Finding
+
+
+class LedgerError(Exception):
+    """Raised when a drskill.toml ledger file is malformed or schema-invalid.
+
+    Callers (the CLI layer) catch this and print a one-line error instead of
+    letting a raw tomllib/pydantic traceback reach the user."""
+
+
+class Budget(BaseModel):
+    catalog_tokens_max: int = 6000
+    body_tokens_warn: int = 20000
+
+
+class Thresholds(BaseModel):
+    near_duplicate: float = 0.85
+
+
+class Ack(BaseModel):
+    check: str
+    skills: list[str]
+    fingerprint: str
+    note: str | None = None
+    date: dt.date | None = None
+
+
+class Config(BaseModel):
+    budget: Budget = Budget()
+    thresholds: Thresholds = Thresholds()
+    ack: list[Ack] = Field(default_factory=list)
+
+
+def ledger_path(project_root: Path, home: Path, global_mode: bool) -> Path:
+    return home / ".drskill.toml" if global_mode else project_root / "drskill.toml"
+
+
+def _validation_one_liner(e: ValidationError) -> str:
+    first = e.errors()[0]
+    loc = ".".join(str(p) for p in first["loc"])
+    return f"{loc}: {first['msg']}" if loc else first["msg"]
+
+
+def load_config(path: Path) -> Config:
+    if not path.is_file():
+        return Config()
+    try:
+        data = tomllib.loads(path.read_text())
+    except tomllib.TOMLDecodeError as e:
+        raise LedgerError(f"{path}: invalid TOML: {e}") from e
+    try:
+        return Config(**data)
+    except ValidationError as e:
+        raise LedgerError(f"{path}: {_validation_one_liner(e)}") from e
+
+
+def append_ack(path: Path, ack: Ack) -> None:
+    data = tomllib.loads(path.read_text()) if path.is_file() else {}
+    entry = {k: v for k, v in ack.model_dump().items() if v is not None}
+    data.setdefault("ack", []).append(entry)
+    path.write_text(tomli_w.dumps(data))
+
+
+def filter_findings(
+    findings: list[Finding], config: Config
+) -> tuple[list[Finding], list[Finding]]:
+    acked_fps = {a.fingerprint for a in config.ack}
+    active = [f for f in findings if f.fingerprint not in acked_fps]
+    acked = [f for f in findings if f.fingerprint in acked_fps]
+    return active, acked

drskill/models.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class RawInstance(BaseModel):
+    """A skill file as one harness sees it, before resolution."""
+
+    harness: str
+    scope: Literal["project", "user"]
+    skill_file: Path
+    via_symlink: bool
+    order: int  # index of the containing search path in the harness's list
+
+
+class Deployment(BaseModel):
+    harness: str
+    path: Path
+    scope: Literal["project", "user"]
+    via_symlink: bool
+    order: int
+    shadowed_by: str | None = None  # contributor id of the winner, when shadowed
+
+
+class Provenance(BaseModel):
+    kind: Literal["skills-lock", "gh-skill", "linked", "unmanaged"] = "unmanaged"
+    source: str | None = None
+
+
+class TokenCost(BaseModel):
+    catalog_tokens: int  # name + description, approximate
+    body_tokens: int  # full body, approximate
+
+
+class Contributor(BaseModel):
+    id: str  # str(realpath of the skill file)
+    kind: Literal["skill"] = "skill"
+    name: str
+    source: Provenance = Provenance()
+    scope: Literal["project", "user"]
+    deployments: list[Deployment] = Field(default_factory=list)
+    routing_text: str = ""
+    body: str = ""
+    token_cost: TokenCost
+    content_hash: str
+    frontmatter_valid: bool = True
+    frontmatter: dict = Field(default_factory=dict)
+    frontmatter_text: str = ""
+
+
+class Finding(BaseModel):
+    check_id: str
+    severity: Literal["error", "warning"]
+    contributors: list[str]  # contributor ids
+    contributor_names: list[str]
+    harnesses: list[str]
+    message: str
+    fix_commands: list[str] = Field(default_factory=list)
+    fingerprint: str
+
+
+class BrokenSymlink(BaseModel):
+    harness: str
+    path: Path

drskill/pipeline.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from drskill.checks import run_all
+from drskill.checks.lockfile import load_lockfile
+from drskill.discovery import discover
+from drskill.harnesses import detect_harnesses, load_harnesses
+from drskill.ledger import Config, ledger_path, load_config
+from drskill.models import Finding, Provenance
+from drskill.resolution import World, build_world
+
+
+def run_scan(
+    project_root: Path,
+    home: Path,
+    global_only: bool = False,
+    config: Config | None = None,
+    harness: str | None = None,
+) -> tuple[World, list[Finding]]:
+    if config is None:
+        config = load_config(ledger_path(project_root, home, global_only))
+    if harness is None:
+        harnesses = detect_harnesses(project_root, home, global_only)
+    else:
+        harnesses = [h for h in load_harnesses() if h.id == harness]
+    instances, broken = [], []
+    for h in harnesses:
+        i, b = discover(h, project_root, home, global_only)
+        instances += i
+        broken += b
+    world = build_world(instances, {h.id: h for h in harnesses}, broken)
+    world.lockfile = load_lockfile(project_root)
+    if world.lockfile:
+        for c in world.contributors.values():
+            if c.source.kind in ("unmanaged", "linked") and c.name in world.lockfile:
+                entry = world.lockfile[c.name]
+                world.contributors[c.id] = c.model_copy(
+                    update={
+                        "source": Provenance(
+                            kind="skills-lock", source=entry.get("source")
+                        )
+                    }
+                )
+    return world, run_all(world, config)

drskill/report.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import json
+import shlex
+
+from rich.console import Console
+from rich.markup import escape
+from rich.table import Table
+
+from drskill.models import Finding
+from drskill.resolution import World
+
+
+def to_json(findings: list[Finding]) -> str:
+    rows = [
+        dict(sorted(f.model_dump(mode="json").items())) for f in findings
+    ]
+    return json.dumps(rows, indent=2)
+
+
+def render_harness_tables(
+    world: World,
+    console: Console,
+    *,
+    tokens: bool = False,
+    harness: str | None = None,
+    show_all: bool = False,
+) -> None:
+    hidden: list[str] = []
+    for hid, hdef in sorted(world.harnesses.items()):
+        if harness and hid != harness:
+            continue
+        if not show_all and harness is None and not world.effective(hid):
+            hidden.append(hid)
+            continue
+        title = escape(hdef.display_name) + ("" if hdef.verified else " (best effort)")
+        table = Table(title=title)
+        table.add_column("skill")
+        table.add_column("scope")
+        table.add_column("source")
+        if tokens:
+            table.add_column("catalog", justify="right")
+            table.add_column("body", justify="right")
+        table.add_column("notes")
+        cat_total = body_total = 0
+        for c, d in world.harness_loads(hid):
+            notes = []
+            if d.shadowed_by:
+                notes.append("shadowed")
+            if d.via_symlink:
+                notes.append("symlink")
+            row = [escape(c.name), escape(d.scope), escape(c.source.kind)]
+            if tokens:
+                row += [str(c.token_cost.catalog_tokens), str(c.token_cost.body_tokens)]
+                if d.shadowed_by is None:
+                    cat_total += c.token_cost.catalog_tokens
+                    body_total += c.token_cost.body_tokens
+            row.append(escape(", ".join(notes)))
+            table.add_row(*row)
+        if tokens:
+            table.add_row("total (effective)", "", "", str(cat_total), str(body_total), "",
+                          style="bold")
+        console.print(table)
+    if hidden:
+        plural = "es" if len(hidden) != 1 else ""
+        console.print(
+            f"[dim]{len(hidden)} more harness{plural} detected with no skills "
+            f"({escape(', '.join(sorted(hidden)))}); show with --all[/dim]"
+        )
+    if tokens:
+        console.print("[dim]token counts are approximate[/dim]")
+
+
+def _print_finding(world: World, f: Finding, console: Console) -> None:
+    tags = ""
+    if any(
+        hid in world.harnesses and not world.harnesses[hid].verified
+        for hid in f.harnesses
+    ):
+        tags = " [dim](best effort)[/dim]"
+    console.print(f"  [[bold]{escape(f.check_id)}[/bold]] {escape(f.message)}{tags}")
+    if f.harnesses:
+        console.print(f"      harnesses: {escape(', '.join(f.harnesses))}")
+    for cmd in f.fix_commands:
+        console.print(f"      fix: {escape(cmd)}")
+    if f.contributor_names:
+        names = " ".join(shlex.quote(n) for n in f.contributor_names)
+        console.print(f"      or:  drskill ack {escape(f.check_id)} {escape(names)}")
+    else:
+        console.print(f"      or:  drskill ack {escape(f.check_id)}")
+
+
+def render(
+    world: World, active: list[Finding], acked: list[Finding], console: Console
+) -> None:
+    populated = [hid for hid in world.harnesses if world.effective(hid)]
+    empty = len(world.harnesses) - len(populated)
+    n_skills = len(world.contributors)
+    plural = "es" if len(populated) != 1 else ""
+    header = f"[bold]drskill scan[/bold] — {len(populated)} harness{plural}"
+    if empty:
+        header += f" ({empty} more empty)"
+    header += f", {n_skills} skills"
+    console.print(header)
+    errors = [f for f in active if f.severity == "error"]
+    warnings = [f for f in active if f.severity == "warning"]
+    if not active:
+        console.print("\n[green]No findings.[/green]", end="")
+    if errors:
+        console.print("\n[red bold]ERRORS[/red bold]")
+        for f in errors:
+            _print_finding(world, f, console)
+    if warnings:
+        console.print("\n[yellow bold]WARNINGS[/yellow bold]")
+        for f in warnings:
+            _print_finding(world, f, console)
+    summary = (
+        f"\n{len(errors)} error{'s' if len(errors) != 1 else ''}, "
+        f"{len(warnings)} warning{'s' if len(warnings) != 1 else ''}"
+    )
+    if acked:
+        summary += f" ({len(acked)} acknowledged)"
+    summary += " · token counts are approximate"
+    console.print(summary)

drskill/resolution.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import yaml
+from pydantic import BaseModel, Field
+
+from drskill import tokens
+from drskill.harnesses import HarnessDef
+from drskill.models import BrokenSymlink, Contributor, Deployment, Provenance, RawInstance, TokenCost
+
+# Frontmatter keys `gh skill` writes for provenance (repo, ref, tree SHA).
+# Verify against a real `gh skill` install during Task 10 and adjust if the
+# observed key names differ.
+GH_PROVENANCE_KEYS: frozenset[str] = frozenset({"source", "ref", "tree_sha"})
+
+
+def split_frontmatter(text: str) -> tuple[dict | None, str, str]:
+    if not text.startswith("---\n"):
+        return {}, "", text
+    end = text.find("\n---", 4)
+    if end == -1:
+        return {}, "", text
+    raw = text[4:end]
+    body = text[end + 4 :].lstrip("\n")
+    try:
+        parsed = yaml.safe_load(raw)
+    except yaml.YAMLError:
+        return None, raw, body
+    if not isinstance(parsed, dict):
+        return None, raw, body
+    return parsed, raw, body
+
+
+def normalize_content(text: str) -> str:
+    text = text.replace("\r\n", "\n").replace("\r", "\n")
+    fm, _raw, body = split_frontmatter(text)
+    if not fm:  # None (invalid) or {} (absent): hash the raw text
+        return text
+    kept = {k: v for k, v in fm.items() if k not in GH_PROVENANCE_KEYS}
+    canonical_fm = yaml.safe_dump(kept, sort_keys=True)
+    return canonical_fm + "\n---\n" + body
+
+
+def _in_agents_store(path: Path) -> bool:
+    """Layout heuristic: the realpath lives under a `.agents/skills` canonical
+    store, which is how installers like `npx skills` materialize skills. It is
+    evidence of installer management, not a claim about which installer."""
+    return any(
+        p.name == "skills" and p.parent.name == ".agents" for p in [path, *path.parents]
+    )
+
+
+def content_hash(text: str) -> str:
+    digest = hashlib.sha256(normalize_content(text).encode()).hexdigest()
+    return "sha256:" + digest
+
+
+class World(BaseModel):
+    contributors: dict[str, Contributor] = Field(default_factory=dict)
+    harnesses: dict[str, HarnessDef] = Field(default_factory=dict)
+    broken_symlinks: list[BrokenSymlink] = Field(default_factory=list)
+    unreadable: list[tuple[str, str]] = Field(default_factory=list)  # (harness, path)
+    lockfile: dict[str, dict] | None = None
+
+    def harness_loads(self, harness_id: str) -> list[tuple[Contributor, Deployment]]:
+        out = [
+            (c, d)
+            for c in self.contributors.values()
+            for d in c.deployments
+            if d.harness == harness_id
+        ]
+        return sorted(out, key=lambda cd: (cd[1].order, str(cd[1].path)))
+
+    def effective(self, harness_id: str) -> list[Contributor]:
+        seen: list[Contributor] = []
+        for c, d in self.harness_loads(harness_id):
+            if d.shadowed_by is None and c not in seen:
+                seen.append(c)
+        return seen
+
+
+def _skill_name(fm: dict | None, skill_file: Path) -> str:
+    if fm and isinstance(fm.get("name"), str) and fm["name"].strip():
+        return fm["name"].strip()
+    if skill_file.name == "SKILL.md":
+        return skill_file.parent.name
+    return skill_file.stem
+
+
+def build_world(
+    instances: list[RawInstance],
+    harnesses: dict[str, HarnessDef],
+    broken: list[BrokenSymlink],
+) -> World:
+    world = World(harnesses=harnesses, broken_symlinks=broken)
+    for inst in instances:
+        real = inst.skill_file.resolve()
+        cid = str(real)
+        c = world.contributors.get(cid)
+        if c is None:
+            try:
+                text = real.read_text(encoding="utf-8", errors="replace")
+            except OSError:
+                world.unreadable.append((inst.harness, cid))
+                continue
+            fm, raw_fm, body = split_frontmatter(text)
+            name = _skill_name(fm, real)
+            description = ""
+            if fm and isinstance(fm.get("description"), str):
+                description = fm["description"]
+            provenance = Provenance()
+            if fm and GH_PROVENANCE_KEYS & fm.keys():
+                provenance = Provenance(kind="gh-skill", source=fm.get("source"))
+            elif _in_agents_store(real):
+                provenance = Provenance(kind="linked")
+            c = Contributor(
+                id=cid,
+                name=name,
+                scope=inst.scope,
+                source=provenance,
+                routing_text=description,
+                body=body,
+                token_cost=TokenCost(
+                    catalog_tokens=tokens.count(f"{name}: {description}"),
+                    body_tokens=tokens.count(body),
+                ),
+                content_hash=content_hash(text),
+                frontmatter_valid=fm is not None,
+                frontmatter=fm or {},
+                frontmatter_text=raw_fm,
+            )
+            world.contributors[cid] = c
+        if inst.scope == "project":
+            c.scope = "project"
+        c.deployments.append(
+            Deployment(
+                harness=inst.harness,
+                path=inst.skill_file,
+                scope=inst.scope,
+                via_symlink=inst.via_symlink,
+                order=inst.order,
+            )
+        )
+    _mark_shadows(world)
+    return world
+
+
+def _mark_shadows(world: World) -> None:
+    for hid in world.harnesses:
+        first_by_name: dict[str, Contributor] = {}
+        for c, d in world.harness_loads(hid):
+            prior = first_by_name.get(c.name)
+            if prior is None:
+                first_by_name[c.name] = c
+            elif prior.id != c.id and prior.content_hash != c.content_hash:
+                d.shadowed_by = prior.id

drskill/tokens.py

@@ -0,0 +1,28 @@
+"""Approximate token counting. tiktoken loads lazily; if it cannot load
+(or cannot fetch its encoding file offline) we fall back to len // 4."""
+
+from __future__ import annotations
+
+_encoder = None
+_unavailable = False
+
+
+def _fallback_count(text: str) -> int:
+    return len(text) // 4
+
+
+def count(text: str) -> int:
+    global _encoder, _unavailable
+    if not text:
+        return 0
+    if _unavailable:
+        return _fallback_count(text)
+    if _encoder is None:
+        try:
+            import tiktoken
+
+            _encoder = tiktoken.get_encoding("o200k_base")
+        except Exception:
+            _unavailable = True
+            return _fallback_count(text)
+    return len(_encoder.encode(text))