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

skillsync/report.py

@@ -0,0 +1,134 @@
+"""Report generation: markdown index + JSON inventory.
+
+The markdown output is designed to drop straight into a ``local-tool-reuse``
+style index skill: one section per category, a summary table, and per-skill
+reasons so a human (or an agent) can act on it without re-deriving anything.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from collections import Counter
+from pathlib import Path
+
+from .differ import sync_state
+from .model import CATEGORIES, ScanResult, Skill
+
+_CATEGORY_TITLES = {
+    "A": "A — 可直接复制使用（无平台绑定，依赖齐全）",
+    "B": "B — 可迁移，但缺外部依赖（按需补齐）",
+    "C": "C — 方法论可复用，文本须为目标平台改写",
+    "D": "D — 平台私有，不要迁移",
+    "?": "? — 未分类",
+}
+
+_CATEGORY_TITLES_EN = {
+    "A": "A — portable (no platform bindings, all deps present)",
+    "B": "B — portable but missing external dependencies",
+    "C": "C — methodology reusable, text must be rewritten for the target",
+    "D": "D — platform-private, do not migrate",
+    "?": "? — unclassified",
+}
+
+
+def to_json(result: ScanResult) -> str:
+    payload = {
+        "generated_at": _dt.datetime.now().isoformat(timespec="seconds"),
+        "roots": [{"label": lbl, "path": str(p)} for lbl, p in result.roots_scanned],
+        "errors": result.errors,
+        "counts": dict(Counter(s.category for s in result.skills)),
+        "skills": [
+            {
+                "name": s.name,
+                "source": s.source,
+                "path": str(s.path),
+                "category": s.category,
+                "category_reason": s.category_reason,
+                "missing_deps": s.missing_deps,
+                "sync": sync_state(s),
+                "synced_to": str(s.synced_to) if s.synced_to else None,
+                "description": s.description[:200],
+                "warnings": s.parse_warnings,
+            }
+            for s in sorted(result.skills, key=lambda x: (x.source, x.name))
+        ],
+    }
+    return json.dumps(payload, ensure_ascii=False, indent=2)
+
+
+def to_markdown(result: ScanResult, *, lang: str = "zh") -> str:
+    titles = _CATEGORY_TITLES if lang == "zh" else _CATEGORY_TITLES_EN
+    by_cat = result.by_category()
+    counts = Counter(s.category for s in result.skills)
+    sync_counts = Counter(sync_state(s) for s in result.skills)
+
+    lines: list[str] = []
+    stamp = _dt.datetime.now().strftime("%Y-%m-%d %H:%M")
+    lines.append("# Skill 迁移索引（自动生成）" if lang == "zh" else "# Skill migration index (generated)")
+    lines.append("")
+    lines.append(
+        f"> 由 `skillsync` 生成于 {stamp} — 不要手工编辑此文件。"
+        if lang == "zh"
+        else f"> Generated by `skillsync` at {stamp} — do not edit by hand."
+    )
+    lines.append("")
+
+    lines.append("## 概览" if lang == "zh" else "## Overview")
+    lines.append("")
+    lines.append("| 指标 | 数量 |")
+    lines.append("|---|---|")
+    lines.append(f"| 扫描到 skill 总数 | {len(result.skills)} |")
+    for cat in CATEGORIES:
+        lines.append(f"| {cat} 类 | {counts.get(cat, 0)} |")
+    lines.append(f"| 已同步（identical） | {sync_counts.get('identical', 0)} |")
+    lines.append(f"| 内容漂移（drifted） | {sync_counts.get('drifted', 0)} |")
+    lines.append(f"| 目标缺失（missing） | {sync_counts.get('missing', 0)} |")
+    lines.append("")
+
+    lines.append("## 扫描根目录" if lang == "zh" else "## Roots scanned")
+    lines.append("")
+    for label, path in result.roots_scanned:
+        lines.append(f"- `{label}` → `{path}`")
+    if result.errors:
+        lines.append("")
+        lines.append("### 警告" if lang == "zh" else "### Warnings")
+        for err in result.errors:
+            lines.append(f"- {err}")
+    lines.append("")
+
+    for cat in (*CATEGORIES, "?"):
+        skills = by_cat.get(cat) or []
+        if not skills:
+            continue
+        lines.append(f"## {titles[cat]}（{len(skills)}）")
+        lines.append("")
+        lines.append("| skill | 来源 | 同步状态 | 判定依据 / 缺失依赖 |")
+        lines.append("|---|---|---|---|")
+        for s in sorted(skills, key=lambda x: x.name):
+            reason = s.category_reason.replace("|", "\\|")
+            if s.missing_deps:
+                reason += " — 缺: " + ", ".join(f"`{d}`" for d in s.missing_deps)
+            state = sync_state(s)
+            mark = {"identical": "✅", "drifted": "⚠️ 漂移", "missing": "—"}.get(state, state)
+            lines.append(f"| `{s.name}` | {s.source} | {mark} | {reason} |")
+        lines.append("")
+
+    drifted = [s for s in result.skills if sync_state(s) == "drifted"]
+    if drifted:
+        lines.append("## 漂移明细（源与目标内容不一致）" if lang == "zh" else "## Drift details")
+        lines.append("")
+        for s in sorted(drifted, key=lambda x: x.name):
+            lines.append(f"- `{s.name}`: 源 `{s.path}` ≠ 目标 `{s.synced_to}`")
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def write_outputs(result: ScanResult, out_dir: Path, *, lang: str = "zh") -> list[Path]:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    md_path = out_dir / "INDEX.md"
+    json_path = out_dir / "inventory.json"
+    md_path.write_text(to_markdown(result, lang=lang), encoding="utf-8")
+    json_path.write_text(to_json(result), encoding="utf-8")
+    return [md_path, json_path]

skillsync/resolve.py

@@ -0,0 +1,114 @@
+"""Cross-source resolution: one logical skill may exist in several roots.
+
+After scanning, many skill *names* appear in multiple source roots (Codex,
+Qoder-CN...). ``resolve()`` collapses them into a single authoritative skill:
+
+* **identical** — every copy has the same content (ignoring line endings).
+  Keep one representative, record the rest as ``duplicates``.
+* **shadowed** — copies differ. The highest-priority source (per
+  ``source_priority``) is the *canonical* version and is kept; lower-priority
+  copies are recorded as ``shadowed`` (stale duplicates superseded by the
+  canonical one). They are dropped from the main list so they cannot create
+  false drift signals or be synced back over the newer version.
+
+Grouping uses the **expected target directory name**, not the bare skill name,
+so that distinct skills that merely share a base name — e.g.
+``agent-skills:test-driven-development`` (target ``test-driven-development``)
+and ``superpowers:test-driven-development`` (target
+``superpowers-test-driven-development``) — are never merged.
+"""
+
+from __future__ import annotations
+
+from .differ import DEFAULT_PREFIXES
+from .model import Skill
+
+DEFAULT_PRIORITY = ("codex-marketplace", "codex", "qoder-cn", "qoder", "claude")
+
+
+def _norm(data: bytes) -> bytes:
+    return data.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+
+
+def _content(skill: Skill) -> bytes:
+    try:
+        return _norm(skill.path.read_bytes())
+    except OSError:
+        return b""
+
+
+def expected_target_name(skill_name: str) -> str:
+    """Map a (possibly qualified) source skill name to its target dir name.
+
+    ``superpowers:X`` → ``superpowers-X`` (the WorkBuddy convention that keeps
+    the superpowers family from clashing with same-named skills); any other
+    qualified ``plugin:X`` and every bare ``X`` → ``X``.
+    """
+    if ":" not in skill_name:
+        return skill_name
+    plugin, skill_part = skill_name.split(":", 1)
+    if f"{plugin}-" in DEFAULT_PREFIXES:
+        return f"{plugin}-{skill_part}"
+    return skill_part
+
+
+def _rank(source: str, priority: tuple[str, ...]) -> int:
+    try:
+        return priority.index(source)
+    except ValueError:
+        return len(priority)
+
+
+def _group_key(skill: Skill) -> str:
+    """Group skills by the target slot they map onto.
+
+    Prefer the slot the differ actually matched (``synced_to``), so a bare
+    qoder-cn copy that owns a prefixed target dir (e.g. bare
+    ``finishing-a-development-branch`` → ``superpowers-finishing-a-development-branch``)
+    groups together with its qualified codex counterpart. Fall back to the
+    expected target name for skills with no target slot yet.
+    """
+    if skill.synced_to is not None:
+        return f"@{skill.synced_to.parent}"
+    return expected_target_name(skill.name)
+
+
+def resolve(
+    skills: list[Skill],
+    *,
+    source_priority: tuple[str, ...] = DEFAULT_PRIORITY,
+) -> tuple[list[Skill], list[tuple[str, list[str]]], list[tuple[str, str, list[str]]]]:
+    """Deduplicate skills across sources.
+
+    Returns ``(resolved, duplicates, shadowed)``:
+
+    * ``resolved``   — the canonical skill list (one entry per target slot).
+    * ``duplicates`` — ``(target_name, [source labels])`` collapsed as identical.
+    * ``shadowed``   — ``(target_name, winner_source, [loser sources])`` where a
+      lower-priority stale copy was superseded by a newer canonical version.
+    """
+    groups: dict[str, list[Skill]] = {}
+    for skill in skills:
+        groups.setdefault(_group_key(skill), []).append(skill)
+
+    resolved: list[Skill] = []
+    duplicates: list[tuple[str, list[str]]] = []
+    shadowed: list[tuple[str, str, list[str]]] = []
+
+    for target_name, group in groups.items():
+        group.sort(key=lambda s: (_rank(s.source, source_priority), str(s.path)))
+        if len(group) == 1:
+            resolved.append(group[0])
+            continue
+        contents = [_content(s) for s in group]
+        if len(set(contents)) == 1:
+            resolved.append(group[0])
+            duplicates.append((target_name, [s.source for s in group]))
+        else:
+            winner = group[0]
+            resolved.append(winner)
+            losers = group[1:]
+            shadowed.append((target_name, winner.source, [s.source for s in losers]))
+
+    resolved.sort(key=lambda s: (s.source, expected_target_name(s.name)))
+    return resolved, duplicates, shadowed

skillsync/scanner.py

@@ -0,0 +1,90 @@
+"""Scanner: walk configured roots and produce :class:`Skill` records."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .config import DEFAULT_GLOB, Config, SourceRoot
+from .frontmatter import parse_file
+from .model import ScanResult, Skill
+
+_SKIP_DIRS = {".git", "node_modules", ".venv", "venv", "__pycache__", ".mypy_cache", ".pytest_cache"}
+
+
+def _iter_skill_files(root: SourceRoot) -> list[Path]:
+    if not root.path.is_dir():
+        return []
+    if root.glob == DEFAULT_GLOB:
+        # Non-recursive: only direct child directories.
+        files = []
+        for child in sorted(root.path.iterdir()):
+            if child.is_dir() and child.name not in _SKIP_DIRS:
+                candidate = child / "SKILL.md"
+                if candidate.is_file():
+                    files.append(candidate)
+        return files
+    files = []
+    seen: set[Path] = set()
+    for match in root.path.glob(root.glob):
+        rel_parts = match.relative_to(root.path).parts[:-1]
+        if any(part in _SKIP_DIRS for part in rel_parts):
+            continue
+        resolved = match.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        files.append(match)
+    return sorted(files)
+
+
+def _qualified_name(root: SourceRoot, path: Path) -> str:
+    """Derive a readable skill name.
+
+    For marketplace-style roots (``**/skills/<name>/SKILL.md``) the name is the
+    directory. For plugin caches we keep a ``plugin:skill`` qualified name when
+    the layout allows it.
+    """
+    rel = path.relative_to(root.path)
+    parts = rel.parts[:-1]  # drop SKILL.md
+    if not parts:
+        return root.path.name
+    name = parts[-1]
+    # Heuristic: .../<plugin>/<version>/skills/<name> → plugin:name
+    if "skills" in parts:
+        idx = parts.index("skills")
+        if idx > 0:
+            plugin = parts[idx - 2] if idx >= 2 else parts[idx - 1]
+            if plugin != "skills":
+                return f"{plugin}:{name}"
+    return name
+
+
+def scan(config: Config) -> ScanResult:
+    result = ScanResult()
+    for root in config.sources:
+        result.roots_scanned.append((root.label, root.path))
+        if not root.exists():
+            result.errors.append(f"source root missing: {root.label} ({root.path})")
+            continue
+        for skill_file in _iter_skill_files(root):
+            try:
+                doc = parse_file(skill_file)
+            except OSError as exc:
+                result.errors.append(f"unreadable: {skill_file}: {exc}")
+                continue
+            data = doc.data or {}
+            name_in_meta = data.get("name")
+            skill = Skill(
+                name=_qualified_name(root, skill_file),
+                path=skill_file,
+                source=root.label,
+                root=root.path,
+                frontmatter=data,
+                description=str(data.get("description") or "").strip(),
+                parse_warnings=doc.parse_warnings,
+            )
+            if isinstance(name_in_meta, str) and name_in_meta and ":" not in skill.name:
+                # Prefer the declared name when it looks sane.
+                skill.name = name_in_meta
+            result.skills.append(skill)
+    return result

skillsync/sync.py

@@ -0,0 +1,155 @@
+"""Sync: copy category-A (and optionally B) skills into the target root.
+
+Safety rules, all mandatory:
+
+* Never overwrite by default. ``--force`` is required to replace a drifted
+  copy, and the replaced directory is first moved to ``.skillsync-backup/``
+  inside the target root (never deleted).
+* Skills with large private payloads (``.venv``, ``.env``, node_modules) are
+  excluded from the copy — secrets must not travel silently.
+* Dry-run (``--dry-run``) prints the exact plan and touches nothing.
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .differ import sync_state
+from .model import Skill
+from .resolve import DEFAULT_PRIORITY
+
+_EXCLUDE_NAMES = {".venv", "venv", "node_modules", "__pycache__", ".env", ".git"}
+
+
+def _priority_rank(source: str) -> int:
+    try:
+        return DEFAULT_PRIORITY.index(source)
+    except ValueError:
+        return len(DEFAULT_PRIORITY)
+
+
+@dataclass
+class SyncPlanItem:
+    skill: Skill
+    dest: Path
+    action: str          # "copy" | "update" | "skip"
+    note: str = ""
+
+
+@dataclass
+class SyncReport:
+    planned: list[SyncPlanItem] = field(default_factory=list)
+    copied: list[SyncPlanItem] = field(default_factory=list)
+    updated: list[SyncPlanItem] = field(default_factory=list)
+    skipped: list[SyncPlanItem] = field(default_factory=list)
+    backed_up: list[Path] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+def _copy_tree_filtered(src_dir: Path, dest_dir: Path) -> None:
+    def ignore(directory: str, names: list[str]) -> set[str]:
+        return {n for n in names if n in _EXCLUDE_NAMES}
+
+    shutil.copytree(src_dir, dest_dir, ignore=ignore, dirs_exist_ok=False)
+
+
+def plan_sync(
+    skills: list[Skill],
+    target: Path,
+    *,
+    categories: tuple[str, ...] = ("A",),
+    prefix_collisions: set[str] | None = None,
+    force: bool = False,
+    name_prefix: str = "",
+    drifted_only: bool = False,
+    sources: tuple[str, ...] | None = None,
+) -> SyncReport:
+    report = SyncReport()
+    prefix_collisions = prefix_collisions or set()
+    planned_dests: dict[Path, str] = {}
+    # Sort by source priority first, so the authoritative root (codex) claims a
+    # destination before a lower-priority variant (qoder-cn) of the same skill.
+    ordered = sorted(skills, key=lambda s: (_priority_rank(s.source), s.name))
+    for skill in ordered:
+        if skill.category not in categories:
+            continue
+        if sources and skill.source not in sources:
+            continue
+        if drifted_only and sync_state(skill) != "drifted":
+            continue
+        base = skill.name.split(":", 1)[1] if ":" in skill.name else skill.name
+        if base in prefix_collisions:
+            base = name_prefix + base
+        elif name_prefix:
+            base = name_prefix + base
+        # If the differ already located this skill in the target (including any
+        # naming convention like a "superpowers-" prefix), update that exact
+        # path instead of computing a fresh one — this prevents creating a
+        # duplicate unprefixed directory next to the canonical copy.
+        dest = skill.synced_to.parent if skill.synced_to is not None else target / base
+        if dest in planned_dests:
+            # Another (higher-priority) source variant already claimed this
+            # destination in this run — first wins, later variants skip.
+            report.skipped.append(
+                SyncPlanItem(skill, dest, "skip", f"destination already planned from {planned_dests[dest]}")
+            )
+            continue
+        src_dir = skill.path.parent
+        if dest.exists():
+            same = False
+            try:
+                src_skill = skill.path.read_bytes()
+                dest_skill = dest / "SKILL.md"
+                norm = lambda b: b.replace(b"\r\n", b"\n").replace(b"\r", b"\n")
+                same = dest_skill.is_file() and norm(dest_skill.read_bytes()) == norm(src_skill)
+            except OSError:
+                same = False
+            if same:
+                report.skipped.append(SyncPlanItem(skill, dest, "skip", "identical"))
+            elif force:
+                report.planned.append(SyncPlanItem(skill, dest, "update", "drifted, --force given"))
+                planned_dests[dest] = skill.source
+            else:
+                report.skipped.append(
+                    SyncPlanItem(skill, dest, "skip", "exists and differs; use --force to update")
+                )
+        else:
+            if drifted_only:
+                report.skipped.append(
+                    SyncPlanItem(skill, dest, "skip", "not in target (drifted-only mode)")
+                )
+            else:
+                report.planned.append(SyncPlanItem(skill, dest, "copy"))
+                planned_dests[dest] = skill.source
+    return report
+
+
+def execute_sync(
+    report: SyncReport,
+    target: Path,
+    *,
+    dry_run: bool = False,
+) -> SyncReport:
+    if dry_run:
+        return report
+    backup_root = target / ".skillsync-backup"
+    for item in report.planned:
+        src_dir = item.skill.path.parent
+        try:
+            if item.action == "update" and item.dest.exists():
+                backup_root.mkdir(parents=True, exist_ok=True)
+                backup_dest = backup_root / item.dest.name
+                if backup_dest.exists():
+                    shutil.rmtree(backup_dest)
+                shutil.move(str(item.dest), str(backup_dest))
+                report.backed_up.append(backup_dest)
+            _copy_tree_filtered(src_dir, item.dest)
+            if item.action == "update":
+                report.updated.append(item)
+            else:
+                report.copied.append(item)
+        except (OSError, shutil.Error) as exc:
+            report.errors.append(f"{item.skill.name}: {exc}")
+    return report