@softspark/ai-toolkit 1.0.0

package/scripts/plugin_schema.py

@@ -0,0 +1,138 @@
+"""Plugin manifest schema validation.
+
+Single source of truth for validating plugin.json manifests.
+Used by both validate.py and plugin.py.
+
+Stdlib-only.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+
+# Required top-level fields
+REQUIRED_FIELDS = ("name", "description", "version", "domain", "type", "status")
+
+# Valid status values
+VALID_STATUSES = frozenset({"stable", "experimental", "deprecated"})
+
+# Valid plugin types
+VALID_TYPES = frozenset({"behavioral", "language", "domain", "integration"})
+
+# Valid hook event names (must match validate.py VALID_HOOK_EVENTS)
+VALID_HOOK_EVENTS = frozenset({
+    "SessionStart", "Notification", "PreToolUse", "PostToolUse", "Stop",
+    "PreCompact", "SubagentStop", "UserPromptSubmit", "TaskCompleted",
+    "TeammateIdle", "SubagentStart", "SessionEnd", "PermissionRequest", "Setup",
+})
+
+
+def validate_manifest(data: dict, pack_dir: Path | None = None) -> list[str]:
+    """Validate a plugin manifest dict.
+
+    Returns a list of error messages (empty = valid).
+    """
+    errors: list[str] = []
+
+    # Check required fields
+    for field in REQUIRED_FIELDS:
+        if field not in data or not data[field]:
+            errors.append(f"Missing required field: {field}")
+
+    # Validate status
+    status = data.get("status", "")
+    if status and status not in VALID_STATUSES:
+        errors.append(f"Invalid status '{status}' (valid: {', '.join(sorted(VALID_STATUSES))})")
+
+    # Validate includes structure
+    includes = data.get("includes")
+    if includes is None:
+        errors.append("Missing 'includes' field")
+    elif not isinstance(includes, dict):
+        errors.append("'includes' must be a dictionary")
+    else:
+        for key in ("agents", "skills", "rules", "hooks"):
+            val = includes.get(key, [])
+            if not isinstance(val, list):
+                errors.append(f"includes.{key} must be a list")
+
+    # Validate hook_events if present
+    hook_events = data.get("hook_events", {})
+    if hook_events:
+        if not isinstance(hook_events, dict):
+            errors.append("'hook_events' must be a dictionary mapping hook filenames to event names")
+        else:
+            for hook_file, event in hook_events.items():
+                if event not in VALID_HOOK_EVENTS:
+                    errors.append(f"hook_events['{hook_file}']: invalid event '{event}'")
+
+    # Validate hook files exist (if pack_dir provided)
+    # Hooks can come from the plugin's own hooks/ dir OR from core app/hooks/
+    if pack_dir and includes and isinstance(includes, dict):
+        hooks_dir = pack_dir / "hooks"
+        # Resolve toolkit root to check core hooks
+        toolkit_hooks_dir = pack_dir.parent.parent / "hooks"
+        for hook_file in includes.get("hooks", []):
+            base_name = Path(hook_file).name
+            candidates = [
+                hooks_dir / hook_file,
+                hooks_dir / base_name,
+                pack_dir / hook_file,
+                toolkit_hooks_dir / base_name,  # core hooks
+            ]
+            if not any(c.is_file() for c in candidates):
+                errors.append(f"Hook file not found: {hook_file}")
+
+    return errors
+
+
+def validate_references(
+    data: dict,
+    agents_dir: Path,
+    skills_dir: Path,
+) -> list[str]:
+    """Validate that referenced agents and skills exist.
+
+    Returns a list of error messages.
+    """
+    errors: list[str] = []
+    includes = data.get("includes", {})
+
+    for agent in includes.get("agents", []):
+        if not (agents_dir / f"{agent}.md").is_file():
+            errors.append(f"References missing agent: {agent}")
+
+    for skill in includes.get("skills", []):
+        if not (skills_dir / skill / "SKILL.md").is_file():
+            errors.append(f"References missing skill: {skill}")
+
+    return errors
+
+
+def resolve_hook_event(hook_filename: str, manifest: dict) -> str:
+    """Resolve the Claude Code event for a hook file.
+
+    Checks hook_events in manifest first, then falls back to
+    filename-based guessing.
+    """
+    # Check explicit mapping first
+    hook_events = manifest.get("hook_events", {})
+    base_name = Path(hook_filename).name
+    if base_name in hook_events:
+        return hook_events[base_name]
+    if hook_filename in hook_events:
+        return hook_events[hook_filename]
+
+    # Fallback: filename-based guessing
+    mapping = {
+        "observation-capture.sh": "PostToolUse",
+        "session-summary.sh": "Stop",
+        "status-line.sh": "Stop",
+        "output-style.sh": "Stop",
+        "session-end.sh": "SessionEnd",
+        "guard-destructive.sh": "PreToolUse",
+        "quality-gate.sh": "TaskCompleted",
+        "user-prompt-submit.sh": "UserPromptSubmit",
+        "post-tool-use.sh": "PostToolUse",
+    }
+    return mapping.get(base_name, "")

package/scripts/remove_rule.py

@@ -0,0 +1,58 @@
+#!/usr/bin/env python3
+"""remove-rule -- Unregister a rule (opposite of add-rule).
+
+Removes the rule file from ~/.ai-toolkit/rules/ (so it is no longer
+re-applied on future 'ai-toolkit install' runs) AND strips its injected
+block from the target CLAUDE.md.
+
+Usage:
+  remove_rule.py <rule-name> [target-dir]
+
+Arguments:
+  rule-name   Name of the rule (filename without .md)
+  target-dir  Directory containing .claude/CLAUDE.md (default: $HOME)
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import remove_rule_section
+
+
+def main() -> None:
+    """Unregister a rule and strip its injected block."""
+    if len(sys.argv) < 2:
+        print("Usage: remove_rule.py <rule-name> [target-dir]", file=sys.stderr)
+        sys.exit(1)
+
+    rule_name = sys.argv[1]
+    target_dir = Path(sys.argv[2]) if len(sys.argv) > 2 else Path.home()
+    rules_dir = Path.home() / ".ai-toolkit" / "rules"
+
+    removed = 0
+
+    # 1. Unregister from ~/.ai-toolkit/rules/
+    rule_file = rules_dir / f"{rule_name}.md"
+    if rule_file.is_file():
+        rule_file.unlink()
+        print(f"Unregistered: '{rule_name}' (removed from {rules_dir})")
+        removed += 1
+    else:
+        print(f"Not registered: '{rule_name}' not found in {rules_dir}")
+
+    # 2. Strip injected block from .claude/CLAUDE.md
+    found = remove_rule_section(rule_name, target_dir)
+    if found:
+        print(f"Removed rule '{rule_name}' from {target_dir / '.claude' / 'CLAUDE.md'}")
+        removed += 1
+
+    if removed == 0:
+        print()
+        print("Nothing to unregister. To list registered rules:")
+        print("  ls ~/.ai-toolkit/rules/")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/stats.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""ai-toolkit stats -- Show skill usage statistics.
+
+Reads ~/.ai-toolkit/stats.json (populated by track-usage.sh hook)
+and displays a sorted table of skill invocations.
+
+Options:
+  --reset   Clear all stats
+  --json    Output raw JSON
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+STATS_FILE = Path.home() / ".ai-toolkit" / "stats.json"
+
+
+def main() -> None:
+    """Display, export, or reset usage statistics."""
+    flag = sys.argv[1] if len(sys.argv) > 1 else ""
+
+    # --reset
+    if flag == "--reset":
+        if STATS_FILE.is_file():
+            STATS_FILE.unlink()
+            print("Stats reset.")
+        else:
+            print("No stats file found.")
+        return
+
+    # --json
+    if flag == "--json":
+        if STATS_FILE.is_file():
+            print(STATS_FILE.read_text(encoding="utf-8"), end="")
+        else:
+            print("{}")
+        return
+
+    # Default: pretty-print table
+    if not STATS_FILE.is_file():
+        print("No usage stats recorded yet.")
+        print("Stats are collected when skills are invoked via slash commands.")
+        print()
+        print(f"File: {STATS_FILE}")
+        return
+
+    print("AI Toolkit Usage Stats")
+    print("========================")
+    print()
+
+    with open(STATS_FILE, encoding="utf-8") as f:
+        data: dict = json.load(f)
+
+    if not data:
+        print("No invocations recorded.")
+        return
+
+    rows = sorted(data.items(), key=lambda x: x[1].get("count", 0), reverse=True)
+
+    print(f"{'Skill':<30} {'Count':>6}  {'Last Used':<20}")
+    print("-" * 60)
+    for name, info in rows:
+        count = info.get("count", 0)
+        last = info.get("last_used", "unknown")
+        print(f"{name:<30} {count:>6}  {last:<20}")
+
+    total = sum(v.get("count", 0) for v in data.values())
+    print()
+    print(f"Total invocations: {total}")
+    print(f"Unique skills: {len(data)}")
+    print()
+    print(f"File: {STATS_FILE}")
+    print("Reset: ai-toolkit stats --reset")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/sync.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""ai-toolkit sync — Sync config to/from GitHub Gist.
+
+Usage:
+    sync.py --export              Export config snapshot as JSON to stdout
+    sync.py --push                Push config to GitHub Gist (requires gh CLI)
+    sync.py --pull [gist-id]      Pull config from Gist and apply
+    sync.py --import <file|url>   Import config from local file or URL
+"""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import toolkit_dir
+
+CONFIG_DIR = Path.home() / ".ai-toolkit"
+RULES_DIR = CONFIG_DIR / "rules"
+GIST_ID_FILE = CONFIG_DIR / ".gist-id"
+
+
+def do_export() -> str:
+    """Export config snapshot as JSON."""
+    # Read toolkit version
+    version = "unknown"
+    pkg = toolkit_dir / "package.json"
+    if pkg.is_file():
+        with open(pkg) as f:
+            version = json.load(f).get("version", "unknown")
+
+    # Collect rules
+    rules: dict[str, str] = {}
+    if RULES_DIR.is_dir():
+        for f in sorted(RULES_DIR.glob("*.md")):
+            rules[f.stem] = f.read_text(encoding="utf-8")
+
+    # Collect stats
+    stats: dict = {}
+    stats_file = CONFIG_DIR / "stats.json"
+    if stats_file.is_file():
+        try:
+            with open(stats_file) as f:
+                stats = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    snapshot = {
+        "schema_version": 1,
+        "exported_at": datetime.now(timezone.utc).isoformat(),
+        "toolkit_version": version,
+        "rules": rules,
+        "stats": stats,
+    }
+    return json.dumps(snapshot, indent=2)
+
+
+def do_import(source: str) -> None:
+    """Import config from file or URL."""
+    tmpfile: str | None = None
+
+    if source.startswith("http"):
+        tmpfile = tempfile.mktemp(suffix=".json")
+        urllib.request.urlretrieve(source, tmpfile)
+        source = tmpfile
+
+    source_path = Path(source)
+    if not source_path.is_file():
+        print(f"Error: file not found: {source}", file=sys.stderr)
+        sys.exit(1)
+
+    with open(source_path) as f:
+        data = json.load(f)
+
+    if data.get("schema_version") != 1:
+        print("Error: unsupported schema version", file=sys.stderr)
+        sys.exit(1)
+
+    rules = data.get("rules", {})
+    if rules:
+        RULES_DIR.mkdir(parents=True, exist_ok=True)
+        for name, content in rules.items():
+            if "/" in name or "\\" in name or ".." in name:
+                print(f"  SKIPPED: '{name}' — invalid rule name (path traversal)", file=sys.stderr)
+                continue
+            path = RULES_DIR / f"{name}.md"
+            path.write_text(content, encoding="utf-8")
+            print(f"  Applied rule: {name}")
+
+    print(f"\nImported {len(rules)} rules from {source_path}")
+    print(f"Toolkit version at export: {data.get('toolkit_version', 'unknown')}")
+
+    if tmpfile:
+        os.unlink(tmpfile)
+
+
+def do_push() -> None:
+    """Push config to GitHub Gist."""
+    if not shutil.which("gh"):
+        print("Error: gh CLI not found. Install: https://cli.github.com")
+        sys.exit(1)
+
+    result = subprocess.run(["gh", "auth", "status"], capture_output=True)
+    if result.returncode != 0:
+        print("Error: gh not authenticated. Run: gh auth login")
+        sys.exit(1)
+
+    tmpfile = tempfile.mktemp(suffix=".json")
+    Path(tmpfile).write_text(do_export(), encoding="utf-8")
+
+    if GIST_ID_FILE.is_file():
+        gist_id = GIST_ID_FILE.read_text().strip()
+        subprocess.run(
+            ["gh", "gist", "edit", gist_id, "-f", "ai-toolkit-config.json", tmpfile],
+            check=True,
+        )
+        print(f"Updated gist: {gist_id}")
+    else:
+        result = subprocess.run(
+            ["gh", "gist", "create", "--filename", "ai-toolkit-config.json",
+             "--desc", "ai-toolkit config sync", tmpfile],
+            capture_output=True, text=True,
+        )
+        gist_url = result.stdout.strip()
+        import re
+        match = re.search(r"[a-f0-9]{20,}", gist_url)
+        gist_id = match.group(0) if match else gist_url
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        GIST_ID_FILE.write_text(gist_id, encoding="utf-8")
+        print(f"Created gist: {gist_url}")
+        print(f"Gist ID saved to: {GIST_ID_FILE}")
+
+    os.unlink(tmpfile)
+
+
+def do_pull(gist_id: str = "") -> None:
+    """Pull config from GitHub Gist."""
+    if not shutil.which("gh"):
+        print("Error: gh CLI not found. Install: https://cli.github.com")
+        sys.exit(1)
+
+    if not gist_id and GIST_ID_FILE.is_file():
+        gist_id = GIST_ID_FILE.read_text().strip()
+    if not gist_id:
+        print("Error: no gist ID provided and no saved gist ID found")
+        print("Usage: ai-toolkit sync --pull <gist-id>")
+        sys.exit(1)
+
+    tmpfile = tempfile.mktemp(suffix=".json")
+    subprocess.run(
+        ["gh", "gist", "view", gist_id, "-f", "ai-toolkit-config.json"],
+        stdout=open(tmpfile, "w"),
+        check=True,
+    )
+    do_import(tmpfile)
+    os.unlink(tmpfile)
+
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    GIST_ID_FILE.write_text(gist_id, encoding="utf-8")
+
+
+def main() -> None:
+    action = ""
+    arg = ""
+    args = sys.argv[1:]
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--export":
+            action = "export"
+        elif a == "--push":
+            action = "push"
+        elif a == "--pull":
+            action = "pull"
+            if i + 1 < len(args) and not args[i + 1].startswith("--"):
+                i += 1
+                arg = args[i]
+        elif a == "--import":
+            action = "import"
+            if i + 1 < len(args):
+                i += 1
+                arg = args[i]
+        elif a.startswith("-"):
+            print(f"Unknown option: {a}")
+            sys.exit(1)
+        else:
+            arg = a
+        i += 1
+
+    if not action:
+        print("Usage: ai-toolkit sync [--export|--push|--pull <gist-id>|--import <file>]")
+        sys.exit(1)
+
+    if action == "export":
+        print(do_export())
+    elif action == "import":
+        if not arg:
+            print("Error: --import requires a file path or URL")
+            sys.exit(1)
+        do_import(arg)
+    elif action == "push":
+        do_push()
+    elif action == "pull":
+        do_pull(arg)
+
+
+if __name__ == "__main__":
+    main()