agent-skill-sync 0.2.0__tar.gz → 0.3.0__tar.gz

{agent_skill_sync-0.2.0 → agent_skill_sync-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-skill-sync
-Version: 0.2.0
+Version: 0.3.0
 Summary: Scan, classify and sync AI-agent skills (SKILL.md) across toolchains like OpenAI Codex, Claude Code and WorkBuddy.
 License: MIT
 Project-URL: Homepage, https://github.com/kina-cmd/agent-skill-sync
@@ -100,6 +100,10 @@ skillsync scan --json                # machine-readable inventory
 # or paste into a "tool reuse" skill for your agent to read
 skillsync index --out ./output --lang zh
 
+# What changed upstream since I last looked?
+skillsync check          # diffs against the last snapshot, then records a new one
+skillsync check --quiet  # summary line only (cron-friendly)
+
 # Sync portable skills into the target root — plan first, always
 skillsync sync --dry-run
 skillsync sync --categories A

{agent_skill_sync-0.2.0 → agent_skill_sync-0.3.0}/README.md

@@ -77,6 +77,10 @@ skillsync scan --json                # machine-readable inventory
 # or paste into a "tool reuse" skill for your agent to read
 skillsync index --out ./output --lang zh
 
+# What changed upstream since I last looked?
+skillsync check          # diffs against the last snapshot, then records a new one
+skillsync check --quiet  # summary line only (cron-friendly)
+
 # Sync portable skills into the target root — plan first, always
 skillsync sync --dry-run
 skillsync sync --categories A

{agent_skill_sync-0.2.0 → agent_skill_sync-0.3.0}/agent_skill_sync.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-skill-sync
-Version: 0.2.0
+Version: 0.3.0
 Summary: Scan, classify and sync AI-agent skills (SKILL.md) across toolchains like OpenAI Codex, Claude Code and WorkBuddy.
 License: MIT
 Project-URL: Homepage, https://github.com/kina-cmd/agent-skill-sync
@@ -100,6 +100,10 @@ skillsync scan --json                # machine-readable inventory
 # or paste into a "tool reuse" skill for your agent to read
 skillsync index --out ./output --lang zh
 
+# What changed upstream since I last looked?
+skillsync check          # diffs against the last snapshot, then records a new one
+skillsync check --quiet  # summary line only (cron-friendly)
+
 # Sync portable skills into the target root — plan first, always
 skillsync sync --dry-run
 skillsync sync --categories A

{agent_skill_sync-0.2.0 → agent_skill_sync-0.3.0}/agent_skill_sync.egg-info/SOURCES.txt

@@ -16,5 +16,6 @@ skillsync/model.py
 skillsync/report.py
 skillsync/resolve.py
 skillsync/scanner.py
+skillsync/state.py
 skillsync/sync.py
 tests/test_skillsync.py

{agent_skill_sync-0.2.0 → agent_skill_sync-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-skill-sync"
-version = "0.2.0"
+version = "0.3.0"
 description = "Scan, classify and sync AI-agent skills (SKILL.md) across toolchains like OpenAI Codex, Claude Code and WorkBuddy."
 readme = "README.md"
 license = { text = "MIT" }

{agent_skill_sync-0.2.0 → agent_skill_sync-0.3.0}/skillsync/__init__.py

@@ -6,6 +6,6 @@ etc. — and want one honest inventory: what exists, where it lives, whether it
 is runnable, and what it would take to migrate it.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = ["__version__"]

{agent_skill_sync-0.2.0 → agent_skill_sync-0.3.0}/skillsync/cli.py

@@ -9,15 +9,22 @@ from pathlib import Path
 
 from . import __version__
 from .classifier import classify_all
-from .config import load_config
+from .config import load_config, user_config_home
 from .differ import diff_all, sync_state
 from .model import CATEGORIES
 from .report import to_markdown, write_outputs
 from .resolve import resolve
 from .scanner import scan
+from .state import compare, format_report, load_snapshot, save_snapshot, snapshot_from
 from .sync import execute_sync, plan_sync
 
 
+def _state_path(args) -> Path:
+    if getattr(args, "state", None):
+        return Path(args.state).expanduser()
+    return user_config_home() / "state.json"
+
+
 def _prepare(cfg, *, dedupe: bool = False):
     """Scan → classify → diff → (optionally) resolve cross-source duplicates."""
     result = scan(cfg)
@@ -56,6 +63,14 @@ def _build_parser() -> argparse.ArgumentParser:
     p_index = sub.add_parser("index", help="generate INDEX.md + inventory.json")
     p_index.add_argument("--out", default=".", help="output directory (default: cwd)")
     p_index.add_argument("--lang", choices=["zh", "en"], default="zh")
+    p_index.add_argument("--state", help="path to the change-detection snapshot (default: config home)")
+
+    p_check = sub.add_parser(
+        "check",
+        help="report what changed upstream since the last run (and record a new baseline)",
+    )
+    p_check.add_argument("--state", help="path to the change-detection snapshot (default: config home)")
+    p_check.add_argument("--quiet", action="store_true", help="print only the summary line")
 
     p_sync = sub.add_parser("sync", help="copy portable skills into the target root")
     p_sync.add_argument("--categories", default="A", help="comma list, e.g. A,B (default: A)")
@@ -152,12 +167,33 @@ def _do_index(cfg, args) -> int:
     paths = write_outputs(result, out_dir, lang=args.lang)
     for p in paths:
         print(f"wrote {p}")
+    # Change detection: report what moved upstream, then refresh the baseline.
+    state_path = _state_path(args)
+    old = load_snapshot(state_path)
+    changes = compare(old, result)
+    print()
+    print(format_report(changes, old))
+    save_snapshot(state_path, snapshot_from(result))
     # Also echo the markdown to stdout for quick piping.
     print()
     print(to_markdown(result, lang=args.lang)[:2000])
     return 0
 
 
+def _do_check(cfg, args) -> int:
+    result = _prepare(cfg, dedupe=getattr(args, "dedupe", False))
+    state_path = _state_path(args)
+    old = load_snapshot(state_path)
+    changes = compare(old, result)
+    report = format_report(changes, old)
+    if args.quiet:
+        print(report.splitlines()[0])
+    else:
+        print(report)
+    save_snapshot(state_path, snapshot_from(result))
+    return 0
+
+
 def _do_sync(cfg, args) -> int:
     if cfg.target is None or not cfg.target.path.is_dir():
         print("[error] target root missing; set [target] in skillsync.toml", file=sys.stderr)
@@ -210,6 +246,7 @@ def main(argv: list[str] | None = None) -> int:
         "status": _do_status,
         "index": _do_index,
         "sync": _do_sync,
+        "check": _do_check,
     }
     return handlers[args.command](cfg, args)
 

agent_skill_sync-0.3.0/skillsync/state.py

@@ -0,0 +1,102 @@
+"""Snapshot state: detect upstream changes between runs.
+
+Each ``check`` / ``index`` run records a snapshot of every scanned skill
+(content hash + category + sync state). The next run compares against it and
+reports what moved upstream: new skills, removed skills, content changes,
+category re-classifications and new drift against the target.
+
+This is the "come back and maintain me" hook: the tool tells you, in one
+screen, exactly what changed since you last looked.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .differ import sync_state
+from .model import ScanResult, Skill
+
+KINDS = ("new", "removed", "content", "category", "sync")
+
+
+@dataclass
+class Change:
+    kind: str     # one of KINDS
+    key: str      # "<source>:<name>"
+    detail: str = ""
+
+
+def _key(skill: Skill) -> str:
+    return f"{skill.source}:{skill.name}"
+
+
+def snapshot_from(result: ScanResult) -> dict:
+    return {
+        "generated_at": _dt.datetime.now().isoformat(timespec="seconds"),
+        "skills": {
+            _key(s): {
+                "hash": s.body_hash,
+                "category": s.category,
+                "sync": sync_state(s),
+            }
+            for s in result.skills
+        },
+    }
+
+
+def load_snapshot(path: Path) -> dict | None:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    if not isinstance(data, dict) or not isinstance(data.get("skills"), dict):
+        return None
+    return data
+
+
+def save_snapshot(path: Path, snap: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(snap, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def compare(old: dict | None, result: ScanResult) -> list[Change]:
+    """Diff the previous snapshot against the current scan.
+
+    An absent baseline (first run) yields no changes — there is nothing to
+    compare against yet.
+    """
+    changes: list[Change] = []
+    current = snapshot_from(result)["skills"]
+    if old is None:
+        return changes
+    prev = old.get("skills", {})
+    for key, cur in sorted(current.items()):
+        if key not in prev:
+            changes.append(Change("new", key, f"category {cur['category']}"))
+            continue
+        p = prev[key]
+        if p.get("hash") != cur["hash"]:
+            changes.append(Change("content", key, "upstream content changed"))
+        if p.get("category") != cur["category"]:
+            changes.append(
+                Change("category", key, f"{p.get('category')} -> {cur['category']}")
+            )
+        if p.get("sync") != cur["sync"]:
+            changes.append(Change("sync", key, f"{p.get('sync')} -> {cur['sync']}"))
+    for key in sorted(set(prev) - set(current)):
+        changes.append(Change("removed", key, "no longer present in any source root"))
+    return changes
+
+
+def format_report(changes: list[Change], old: dict | None) -> str:
+    if old is None:
+        return "first run: baseline recorded; future runs report upstream changes"
+    if not changes:
+        return "no upstream changes since last run"
+    lines = [f"{len(changes)} change(s) since {old.get('generated_at', 'last run')}:"]
+    for c in changes:
+        lines.append(f"  [{c.kind:8}] {c.key}  {c.detail}")
+    return "\n".join(lines)

{agent_skill_sync-0.2.0 → agent_skill_sync-0.3.0}/tests/test_skillsync.py

@@ -340,5 +340,73 @@ class TestSyncControls(unittest.TestCase):
         self.assertIn("already planned", report.skipped[0].note)
 
 
+class TestStateChangeDetection(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        base = Path(self.tmp.name)
+        self.src = base / "src"
+        self.tgt = base / "tgt"
+        self.src.mkdir()
+        self.tgt.mkdir()
+        self.cfg = Config(
+            sources=[SourceRoot(label="src", path=self.src)],
+            target=TargetRoot(label="tgt", path=self.tgt),
+        )
+        self.state_path = base / "state.json"
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def _scan(self):
+        from skillsync.classifier import classify_all
+        from skillsync.differ import diff_all
+        from skillsync.scanner import scan
+
+        r = scan(self.cfg)
+        classify_all(r.skills, self.cfg)
+        diff_all(r.skills, self.cfg)
+        return r
+
+    def test_first_run_is_baseline(self):
+        from skillsync.state import compare, load_snapshot, save_snapshot, snapshot_from
+
+        _write_skill(self.src, "a", "# a\n")
+        r = self._scan()
+        self.assertEqual(compare(None, r), [])
+        save_snapshot(self.state_path, snapshot_from(r))
+        self.assertIsNotNone(load_snapshot(self.state_path))
+
+    def test_detects_content_new_and_removed(self):
+        from skillsync.state import compare, load_snapshot, save_snapshot, snapshot_from
+
+        _write_skill(self.src, "a", "# a v1\n")
+        _write_skill(self.src, "gone", "# gone\n")
+        r1 = self._scan()
+        save_snapshot(self.state_path, snapshot_from(r1))
+
+        # upstream: modify a, remove gone, add b
+        (self.src / "a" / "SKILL.md").write_text("---\nname: a\n---\n# a v2\n", encoding="utf-8")
+        import shutil
+
+        shutil.rmtree(self.src / "gone")
+        _write_skill(self.src, "b", "# b\n")
+        r2 = self._scan()
+
+        changes = compare(load_snapshot(self.state_path), r2)
+        kinds = {(c.kind, c.key.split(":", 1)[1]) for c in changes}
+        self.assertIn(("content", "a"), kinds)
+        self.assertIn(("removed", "gone"), kinds)
+        self.assertIn(("new", "b"), kinds)
+
+    def test_corrupt_snapshot_treated_as_absent(self):
+        from skillsync.state import compare, load_snapshot
+
+        self.state_path.write_text("{ not json", encoding="utf-8")
+        _write_skill(self.src, "a", "# a\n")
+        r = self._scan()
+        self.assertIsNone(load_snapshot(self.state_path))
+        self.assertEqual(compare(None, r), [])
+
+
 if __name__ == "__main__":
     unittest.main()