agent-skill-sync 0.1.0__py3-none-any.whl

skillsync/config.py

@@ -0,0 +1,185 @@
+"""Configuration: where to scan, and the target to sync into.
+
+Config resolution order (later wins):
+1. Built-in defaults — auto-discover common skill roots on this machine.
+2. ``skillsync.toml`` in the current working directory.
+3. ``skillsync.toml`` under the user's config home.
+4. Explicit ``--config`` path passed on the CLI.
+
+The TOML schema is intentionally small::
+
+    [target]
+    label = "workbuddy"
+    path  = "~/.workbuddy/skills"
+
+    [[sources]]
+    label = "codex"
+    path  = "~/.codex/skills"
+    glob  = "*/SKILL.md"          # optional, default "*/SKILL.md"
+    system = false                # optional, mark platform-private roots
+
+    [deps]
+    # name -> how to check availability. "shutil" uses shutil.which,
+    # "path" checks a filesystem path, "env" checks an env var is set.
+    ffmpeg = { kind = "shutil", value = "ffmpeg" }
+    codex  = { kind = "shutil", value = "codex" }
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+DEFAULT_GLOB = "*/SKILL.md"
+
+
+@dataclass
+class Dep:
+    name: str
+    kind: str          # "shutil" | "path" | "env"
+    value: str
+    note: str = ""
+
+    def available(self) -> bool:
+        if self.kind == "shutil":
+            import shutil
+
+            return shutil.which(self.value) is not None
+        if self.kind == "path":
+            return Path(os.path.expanduser(self.value)).exists()
+        if self.kind == "env":
+            return bool(os.environ.get(self.value))
+        return False
+
+
+@dataclass
+class SourceRoot:
+    label: str
+    path: Path
+    glob: str = DEFAULT_GLOB
+    system: bool = False
+
+    def exists(self) -> bool:
+        return self.path.is_dir()
+
+
+@dataclass
+class TargetRoot:
+    label: str
+    path: Path
+    glob: str = DEFAULT_GLOB
+
+
+@dataclass
+class Config:
+    sources: list[SourceRoot] = field(default_factory=list)
+    target: TargetRoot | None = None
+    deps: dict[str, Dep] = field(default_factory=dict)
+    # Hints that push a skill toward category C/D regardless of deps.
+    platform_private_markers: list[str] = field(
+        default_factory=lambda: [
+            "image_gen", "view_image", "control-in-app-browser", "computer-use",
+            "tool_search", "codex-security", "/plugin", "AGENTS.md", "CLAUDE.md",
+            "--tools codex", "present-artifact", "publish-artifact-to-sites",
+        ]
+    )
+    config_path: Path | None = None
+
+
+def _expand(p: str) -> Path:
+    return Path(os.path.expanduser(os.path.expandvars(p)))
+
+
+def user_config_home() -> Path:
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg)
+    appdata = os.environ.get("APPDATA")
+    if appdata:
+        return Path(appdata) / "skillsync"
+    return Path.home() / ".config" / "skillsync"
+
+
+def default_config() -> Config:
+    """Auto-discover the well-known skill roots on this machine."""
+    home = Path.home()
+    sources: list[SourceRoot] = []
+
+    def add(label: str, path: Path, *, system: bool = False, glob: str = DEFAULT_GLOB) -> None:
+        if path.is_dir():
+            sources.append(SourceRoot(label=label, path=path, glob=glob, system=system))
+
+    # OpenAI Codex
+    add("codex", home / ".codex" / "skills")
+    add("codex-system", home / ".codex" / "skills" / ".system", system=True)
+    add(
+        "codex-marketplace",
+        home / ".codex" / "plugins" / "cache",
+        glob="**/skills/*/SKILL.md",
+    )
+    # Claude Code
+    add("claude", home / ".claude" / "skills")
+
+    target = TargetRoot(label="workbuddy", path=home / ".workbuddy" / "skills")
+
+    return Config(sources=sources, target=target)
+
+
+def _load_toml(path: Path) -> dict:
+    try:
+        with path.open("rb") as fh:
+            return tomllib.load(fh)
+    except (OSError, tomllib.TOMLDecodeError):
+        return {}
+
+
+def _merge(cfg: Config, data: dict) -> None:
+    if "target" in data and isinstance(data["target"], dict):
+        t = data["target"]
+        cfg.target = TargetRoot(
+            label=t.get("label", cfg.target.label if cfg.target else "target"),
+            path=_expand(t["path"]) if "path" in t else (cfg.target.path if cfg.target else Path(".")),
+            glob=t.get("glob", DEFAULT_GLOB),
+        )
+    if "sources" in data and isinstance(data["sources"], list):
+        cfg.sources = []
+        for s in data["sources"]:
+            cfg.sources.append(
+                SourceRoot(
+                    label=s["label"],
+                    path=_expand(s["path"]),
+                    glob=s.get("glob", DEFAULT_GLOB),
+                    system=bool(s.get("system", False)),
+                )
+            )
+    if "deps" in data and isinstance(data["deps"], dict):
+        for name, spec in data["deps"].items():
+            if isinstance(spec, str):
+                cfg.deps[name] = Dep(name=name, kind="shutil", value=spec)
+            elif isinstance(spec, dict):
+                cfg.deps[name] = Dep(
+                    name=name,
+                    kind=spec.get("kind", "shutil"),
+                    value=spec.get("value", name),
+                    note=spec.get("note", ""),
+                )
+    if "platform_private_markers" in data and isinstance(data["platform_private_markers"], list):
+        cfg.platform_private_markers = list(data["platform_private_markers"])
+
+
+def load_config(explicit_path: str | None = None) -> Config:
+    cfg = default_config()
+    for candidate in [
+        Path.cwd() / "skillsync.toml",
+        user_config_home() / "skillsync.toml",
+    ]:
+        if candidate.is_file():
+            _merge(cfg, _load_toml(candidate))
+            cfg.config_path = candidate
+    if explicit_path:
+        p = _expand(explicit_path)
+        _merge(cfg, _load_toml(p))
+        cfg.config_path = p
+    return cfg

skillsync/differ.py

@@ -0,0 +1,98 @@
+"""Differ: compare scanned source skills against the target root.
+
+Matching a source skill to its target slot:
+
+1. Qualified ``plugin:base`` prefers target dir ``plugin-base`` (the WorkBuddy
+   convention for the superpowers family), then falls back to ``base``.
+2. Bare ``base`` prefers target dir ``base``, then tries known prefixed
+   variants (``superpowers-base`` …) — qoder-cn stores superpowers skills
+   without the prefix, so a bare source name can legitimately own a prefixed
+   target slot.
+
+States: **missing** (no target slot), **identical** (same content modulo line
+endings), **drifted** (target slot exists but content differs).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .config import Config
+from .model import Skill
+
+DEFAULT_PREFIXES = ("superpowers-",)
+
+
+def build_target_index(config: Config) -> dict[str, Path]:
+    """Map raw target directory name → SKILL.md path."""
+    index: dict[str, Path] = {}
+    target = config.target
+    if target is None or not target.path.is_dir():
+        return index
+    for match in sorted(target.path.glob(target.glob)):
+        if match.is_file():
+            index[match.parent.name] = match
+    return index
+
+
+def match_target(
+    skill_name: str,
+    target_index: dict[str, Path],
+    prefixes: tuple[str, ...] = DEFAULT_PREFIXES,
+) -> Path | None:
+    """Find the target SKILL.md a source skill name maps onto (or None)."""
+    plugin: str | None = None
+    base = skill_name
+    if ":" in skill_name:
+        plugin, base = skill_name.split(":", 1)
+    # Qualified names prefer their prefixed slot to avoid hijacking a
+    # same-basename skill from a different plugin.
+    if plugin:
+        prefixed = f"{plugin}-{base}"
+        if prefixed in target_index:
+            return target_index[prefixed]
+    if base in target_index:
+        return target_index[base]
+    for prefix in prefixes:
+        if base.startswith(prefix):
+            continue
+        variant = prefix + base
+        if variant in target_index:
+            return target_index[variant]
+    return None
+
+
+def _norm(data: bytes) -> bytes:
+    return data.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+
+
+def diff(skill: Skill, target_index: dict[str, Path]) -> None:
+    candidate = match_target(skill.name, target_index)
+    if candidate is None:
+        skill.synced_to = None
+        skill.in_sync = None
+        return
+    skill.synced_to = candidate
+    try:
+        same = _norm(candidate.read_bytes()) == _norm(skill.path.read_bytes())
+    except OSError:
+        same = False
+    skill.in_sync = same
+
+
+def diff_all(
+    skills,
+    config: Config,
+    prefixes: tuple[str, ...] = DEFAULT_PREFIXES,
+) -> dict[str, Path]:
+    target_index = build_target_index(config)
+    for skill in skills:
+        diff(skill, target_index)
+    return target_index
+
+
+def sync_state(skill: Skill) -> str:
+    """Human-readable sync state for one skill."""
+    if skill.synced_to is None:
+        return "missing"
+    return "identical" if skill.in_sync else "drifted"

skillsync/frontmatter.py

@@ -0,0 +1,260 @@
+"""Minimal YAML frontmatter parser for SKILL.md files.
+
+Deliberately dependency-free (no PyYAML). It supports the subset that skill
+frontmatter actually uses in the wild:
+
+* ``key: value`` scalars (quoted or bare)
+* block scalars ``key: >`` / ``key: |`` (folded and literal)
+* inline lists ``key: [a, b]``
+* nested block lists ``key:\\n  - item``
+* nested mappings via indentation (one or more levels)
+* ``#`` comments and blank lines
+
+This is not a general YAML implementation. It is tuned for the frontmatter
+conventions used by Codex / Claude / WorkBuddy skills and fails soft: anything
+it cannot parse is kept as a raw string rather than raising.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+_FRONTMATTER_RE = re.compile(r"\A---[ \t]*\r?\n(.*?)\r?\n---[ \t]*\r?\n?", re.DOTALL)
+
+
+@dataclass
+class Document:
+    """A parsed SKILL.md: frontmatter data plus the raw markdown body."""
+
+    data: dict[str, Any] = field(default_factory=dict)
+    body: str = ""
+    raw_frontmatter: str = ""
+    parse_warnings: list[str] = field(default_factory=list)
+
+
+def split_frontmatter(text: str) -> tuple[str | None, str]:
+    """Return ``(frontmatter_or_None, body)`` for raw file text."""
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return None, text
+    return match.group(1), text[match.end():]
+
+
+def _strip_comment(line: str) -> str:
+    """Remove a trailing ``# comment`` that is not inside quotes."""
+    out: list[str] = []
+    quote: str | None = None
+    for ch in line:
+        if quote:
+            out.append(ch)
+            if ch == quote:
+                quote = None
+            continue
+        if ch in "\"'":
+            quote = ch
+            out.append(ch)
+            continue
+        if ch == "#":
+            break
+        out.append(ch)
+    return "".join(out).rstrip()
+
+
+def _coerce_scalar(token: str) -> Any:
+    token = token.strip()
+    if token == "" or token in ("~", "null", "Null", "NULL"):
+        return None
+    if token in ("true", "True", "TRUE", "yes", "Yes", "on", "On"):
+        return True
+    if token in ("false", "False", "FALSE", "no", "No", "off", "Off"):
+        return False
+    if len(token) >= 2 and token[0] == token[-1] and token[0] in "\"'":
+        return token[1:-1]
+    if token.startswith("[") and token.endswith("]"):
+        inner = token[1:-1].strip()
+        if not inner:
+            return []
+        return [_coerce_scalar(part) for part in _split_flow(inner)]
+    try:
+        return int(token)
+    except ValueError:
+        pass
+    try:
+        return float(token)
+    except ValueError:
+        pass
+    return token
+
+
+def _split_flow(inner: str) -> list[str]:
+    parts: list[str] = []
+    depth = 0
+    quote: str | None = None
+    current: list[str] = []
+    for ch in inner:
+        if quote:
+            current.append(ch)
+            if ch == quote:
+                quote = None
+            continue
+        if ch in "\"'":
+            quote = ch
+            current.append(ch)
+            continue
+        if ch in "[{":
+            depth += 1
+        elif ch in "]}":
+            depth -= 1
+        if ch == "," and depth == 0:
+            parts.append("".join(current))
+            current = []
+            continue
+        current.append(ch)
+    if current:
+        parts.append("".join(current))
+    return [p.strip() for p in parts if p.strip()]
+
+
+def parse_frontmatter(text: str) -> Document:
+    """Parse raw SKILL.md text into a :class:`Document`."""
+    raw, body = split_frontmatter(text)
+    if raw is None:
+        return Document(body=body, parse_warnings=["no frontmatter block found"])
+
+    doc = Document(body=body, raw_frontmatter=raw)
+    # Stack entries: (indent, container). Container is the dict or list we add to.
+    root: dict[str, Any] = {}
+    stack: list[tuple[int, Any, str | None]] = [(-1, root, None)]
+    lines = raw.splitlines()
+    i = 0
+    while i < len(lines):
+        raw_line = lines[i]
+        stripped = _strip_comment(raw_line)
+        if not stripped.strip():
+            i += 1
+            continue
+
+        indent = len(raw_line) - len(raw_line.lstrip(" "))
+
+        # Block scalar: key: > or key: |
+        block_match = re.match(r"^(?P<key>[A-Za-z0-9_.\-]+):\s*(?P<style>[>|][-+]?)\s*$", stripped)
+        if block_match:
+            key = block_match.group("key")
+            style = block_match.group("style")[0]
+            collected: list[str] = []
+            block_indent: int | None = None
+            j = i + 1
+            while j < len(lines):
+                nxt = lines[j]
+                if nxt.strip() == "":
+                    collected.append("")
+                    j += 1
+                    continue
+                nxt_indent = len(nxt) - len(nxt.lstrip(" "))
+                if nxt_indent <= indent:
+                    break
+                if block_indent is None:
+                    block_indent = nxt_indent
+                collected.append(nxt[block_indent:] if len(nxt) >= block_indent else nxt.strip())
+                j += 1
+            while collected and collected[-1] == "":
+                collected.pop()
+            value = "\n".join(collected) if style == "|" else " ".join(
+                ln.strip() for ln in collected if ln.strip()
+            )
+            _assign(stack, indent, key, value)
+            i = j
+            continue
+
+        # List item at this indent level
+        if stripped.lstrip().startswith("- "):
+            item_text = stripped.lstrip()[2:].strip()
+            _append_list_item(stack, indent, _coerce_scalar(item_text))
+            i += 1
+            continue
+
+        kv = re.match(r"^(?P<key>[A-Za-z0-9_.\-]+):\s*(?P<value>.*)$", stripped)
+        if kv:
+            key = kv.group("key")
+            value_text = kv.group("value").strip()
+            if value_text == "":
+                # Could introduce a nested mapping or a block list — peek ahead.
+                container = _open_container(stack, indent, key)
+                if container is not None:
+                    i += 1
+                    continue
+                _assign(stack, indent, key, None)
+                i += 1
+                continue
+            _assign(stack, indent, key, _coerce_scalar(value_text))
+            i += 1
+            continue
+
+        doc.parse_warnings.append(f"unparsed line {i + 1}: {stripped!r}")
+        i += 1
+
+    doc.data = root
+    return doc
+
+
+def _pop_to(stack: list[tuple[int, Any, str | None]], indent: int) -> list[tuple[int, Any, str | None]]:
+    while len(stack) > 1 and stack[-1][0] >= indent:
+        stack.pop()
+    return stack
+
+
+def _assign(stack: list[tuple[int, Any, str | None]], indent: int, key: str, value: Any) -> None:
+    _pop_to(stack, indent)
+    container = stack[-1][1]
+    if isinstance(container, dict):
+        container[key] = value
+    # If the current container is a list, a stray key is ignored.
+
+
+def _open_container(stack: list[tuple[int, Any, str | None]], indent: int, key: str) -> Any:
+    """Register ``key`` as a container-to-be-filled by following indented lines.
+
+    Returns the new container, or ``None`` if we cannot decide yet (in which
+    case the caller treats the key as an empty scalar; later list items will
+    convert it).
+    """
+    _pop_to(stack, indent)
+    parent = stack[-1][1]
+    if not isinstance(parent, dict):
+        return None
+    placeholder: dict[str, Any] = {}
+    parent[key] = placeholder
+    stack.append((indent, placeholder, key))
+    return placeholder
+
+
+def _append_list_item(stack: list[tuple[int, Any, str | None]], indent: int, value: Any) -> None:
+    _pop_to(stack, indent)
+    top_indent, container, key = stack[-1]
+    parent_container = stack[-2][1] if len(stack) >= 2 else None
+    if isinstance(container, dict) and not container and key and isinstance(parent_container, dict):
+        # The placeholder dict we opened is actually a block list.
+        new_list: list[Any] = [value]
+        parent_container[key] = new_list
+        stack[-1] = (top_indent, new_list, key)
+        return
+    if isinstance(container, list):
+        container.append(value)
+        return
+    if isinstance(container, dict) and key is None:
+        return
+    # Root-level list items with no owning key are unusual; ignore.
+
+
+def parse_file(path) -> Document:
+    """Read ``path`` and parse its frontmatter."""
+    import pathlib
+
+    p = pathlib.Path(path)
+    try:
+        text = p.read_text(encoding="utf-8")
+    except UnicodeDecodeError:
+        text = p.read_text(encoding="utf-8", errors="replace")
+    return parse_frontmatter(text)

skillsync/model.py

@@ -0,0 +1,78 @@
+"""Core data models: what a "skill" is, and what a scan produces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+# Classification taxonomy (mirrors a common migration workflow):
+#   A — copied/runnable as-is in the target toolchain
+#   B — skill is portable but needs external dependencies (CLI/MCP/venv)
+#   C — methodology is reusable but the skill must be rewritten for the target
+#   D — bound to the source platform's private runtime; do not migrate
+CATEGORIES = ("A", "B", "C", "D")
+
+
+@dataclass
+class Skill:
+    """One discovered SKILL.md and its metadata."""
+
+    name: str                       # skill directory name (or qualified name)
+    path: Path                      # absolute path to SKILL.md
+    source: str                     # label of the root it was found under
+    root: Path                      # absolute path of the scan root
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+    description: str = ""
+    parse_warnings: list[str] = field(default_factory=list)
+    # Derived by the classifier:
+    category: str = "?"             # A / B / C / D / "?"
+    category_reason: str = ""
+    missing_deps: list[str] = field(default_factory=list)
+    # Derived by the differ:
+    synced_to: str | None = None    # absolute path in the target, if present
+    in_sync: bool | None = None     # content identical? (None = not synced)
+
+    @property
+    def qualified_name(self) -> str:
+        return f"{self.source}:{self.name}"
+
+    @property
+    def body_hash(self) -> str:
+        """Stable hash of the file content, for drift detection."""
+        import hashlib
+
+        try:
+            data = self.path.read_bytes()
+        except OSError:
+            return ""
+        return hashlib.sha256(data).hexdigest()[:16]
+
+
+@dataclass
+class ScanResult:
+    """Everything one run of the scanner knows."""
+
+    skills: list[Skill] = field(default_factory=list)
+    roots_scanned: list[tuple[str, Path]] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    # Populated by resolve(): base_name -> [source labels] for names that were
+    # identical across multiple roots and collapsed to a single entry.
+    duplicates: list[tuple[str, list[str]]] = field(default_factory=list)
+    # (target_name, winner_source, [loser sources]) for stale copies superseded
+    # by a higher-priority canonical version.
+    shadowed: list[tuple[str, str, list[str]]] = field(default_factory=list)
+    resolved: bool = False
+
+    def by_name(self) -> dict[str, list[Skill]]:
+        out: dict[str, list[Skill]] = {}
+        for skill in self.skills:
+            out.setdefault(skill.name, []).append(skill)
+        return out
+
+    def by_category(self) -> dict[str, list[Skill]]:
+        out: dict[str, list[Skill]] = {c: [] for c in CATEGORIES}
+        out["?"] = []
+        for skill in self.skills:
+            out.setdefault(skill.category, []).append(skill)
+        return out