@softspark/ai-toolkit 1.0.0

package/scripts/benchmark_ecosystem.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""benchmark-ecosystem — Generate ecosystem benchmark snapshot.
+
+Usage:
+    benchmark_ecosystem.py [--offline] [--json|--dashboard-json|--markdown] [--out FILE]
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.request
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+SNAPSHOT_DATE = "2026-03-28"
+STALE_THRESHOLD_DAYS = 30
+
+SNAPSHOT_DATA = [
+    {
+        "repo": "anthropics/claude-code",
+        "category": "official",
+        "stars": 83535,
+        "updated_at": "2026-03-27T16:50:16Z",
+        "commands_md": 18,
+        "agents_md": 15,
+        "skills": 10,
+        "hook_settings_files": 5,
+        "notes": "Official Claude Code repo with plugin layout, development kits, and modular commands/agents/hooks.",
+    },
+    {
+        "repo": "affaan-m/everything-claude-code",
+        "category": "ecosystem-scale",
+        "stars": 111863,
+        "updated_at": "2026-03-27T16:55:18Z",
+        "commands_md": 271,
+        "agents_md": 152,
+        "skills": 397,
+        "hook_settings_files": 2,
+        "notes": "Large ecosystem catalog. High inspiration value, high discoverability-debt risk.",
+    },
+    {
+        "repo": "ChrisWiles/claude-code-showcase",
+        "category": "practical-showcase",
+        "stars": 5593,
+        "updated_at": "2026-03-27T13:13:35Z",
+        "commands_md": 6,
+        "agents_md": 2,
+        "skills": 6,
+        "hook_settings_files": 1,
+        "notes": "Practical edit-time hooks, branch safety, formatting, and testing patterns.",
+    },
+    {
+        "repo": "disler/claude-code-hooks-mastery",
+        "category": "hooks-reference",
+        "stars": 3421,
+        "updated_at": "2026-03-27T15:49:11Z",
+        "commands_md": 21,
+        "agents_md": 19,
+        "skills": 0,
+        "hook_settings_files": 1,
+        "notes": "Strong reference for lifecycle breadth, status lines, and operational hook patterns.",
+    },
+    {
+        "repo": "codeaholicguy/ai-devkit",
+        "category": "cross-tool",
+        "stars": 985,
+        "updated_at": "2026-03-27T00:00:00Z",
+        "commands_md": 0,
+        "agents_md": 0,
+        "skills": 0,
+        "hook_settings_files": 0,
+        "notes": "Cross-tool toolkit positioning benchmark.",
+    },
+    {
+        "repo": "alirezarezvani/claude-code-skill-factory",
+        "category": "meta-tooling",
+        "stars": 638,
+        "updated_at": "2026-03-27T00:00:00Z",
+        "commands_md": 0,
+        "agents_md": 0,
+        "skills": 0,
+        "hook_settings_files": 0,
+        "notes": "Skill/agent/prompt factory inspiration for creator workflows.",
+    },
+]
+
+COMPARISON_MATRIX = [
+    {
+        "pattern": "plugin-manifest-support",
+        "current_state": "implemented",
+        "benchmark_signal": "official Claude Code plugin layout",
+        "priority": "high",
+        "evidence": ["anthropics/claude-code"],
+    },
+    {
+        "pattern": "creator-workflows",
+        "current_state": "implemented",
+        "benchmark_signal": "meta-tooling for commands, hooks, agents, plugins",
+        "priority": "high",
+        "evidence": ["anthropics/claude-code", "alirezarezvani/claude-code-skill-factory"],
+    },
+    {
+        "pattern": "lifecycle-breadth",
+        "current_state": "implemented",
+        "benchmark_signal": "prompt governance, post-tool feedback, subagent hooks, session end",
+        "priority": "high",
+        "evidence": ["disler/claude-code-hooks-mastery", "ChrisWiles/claude-code-showcase"],
+    },
+    {
+        "pattern": "plugin-packs",
+        "current_state": "implemented-experimental",
+        "benchmark_signal": "modular domain packaging",
+        "priority": "medium",
+        "evidence": ["anthropics/claude-code", "affaan-m/everything-claude-code"],
+    },
+    {
+        "pattern": "benchmark-harvesting",
+        "current_state": "implemented",
+        "benchmark_signal": "repeatable evidence for docs and roadmap decisions",
+        "priority": "medium",
+        "evidence": ["anthropics/claude-code", "codeaholicguy/ai-devkit"],
+    },
+]
+
+
+def refresh_online(snapshot: list[dict]) -> list[dict]:
+    """Try to refresh star counts from GitHub API."""
+    import copy
+    rows = copy.deepcopy(snapshot)
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "User-Agent": "ai-toolkit-benchmark-script",
+    }
+    for item in rows:
+        repo = item["repo"]
+        url = f"https://api.github.com/repos/{repo}"
+        try:
+            req = urllib.request.Request(url, headers=headers)
+            with urllib.request.urlopen(req, timeout=10) as response:
+                data = json.load(response)
+            item["stars"] = data.get("stargazers_count", item["stars"])
+            item["updated_at"] = data.get("updated_at", item["updated_at"])
+            item["source"] = "github-api"
+            if data.get("description"):
+                item["description"] = data["description"]
+        except Exception:
+            item["source"] = "snapshot"
+    return rows
+
+
+def annotate_snapshot(snapshot: list[dict]) -> list[dict]:
+    """Add source annotation to snapshot data."""
+    import copy
+    rows = copy.deepcopy(snapshot)
+    for row in rows:
+        row.setdefault("source", "snapshot")
+    return rows
+
+
+def render_dashboard(rows: list[dict], mode: str) -> dict:
+    """Build dashboard JSON."""
+    snapshot_date = date.fromisoformat(SNAPSHOT_DATE)
+    today = datetime.now(timezone.utc).date()
+    age_days = (today - snapshot_date).days
+
+    def status_for_age(days: int, stale_days: int) -> str:
+        if days <= max(7, stale_days // 3):
+            return "fresh"
+        if days <= stale_days:
+            return "aging"
+        return "stale"
+
+    return {
+        "generated_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+        "mode": mode,
+        "snapshot_date": str(snapshot_date),
+        "freshness": {
+            "stale_threshold_days": STALE_THRESHOLD_DAYS,
+            "age_days": age_days,
+            "status": status_for_age(age_days, STALE_THRESHOLD_DAYS),
+        },
+        "summary": {
+            "repo_count": len(rows),
+            "stars_total": sum(int(r.get("stars", 0)) for r in rows),
+            "categories": sorted({r.get("category", "unknown") for r in rows}),
+            "official_repo": "anthropics/claude-code",
+        },
+        "comparison_matrix": COMPARISON_MATRIX,
+        "repos": rows,
+    }
+
+
+def render_markdown(dashboard: dict) -> str:
+    """Render dashboard as Markdown."""
+    lines: list[str] = []
+    data = dashboard
+    rows = data["repos"]
+
+    lines.append("# Claude Ecosystem Benchmark Snapshot")
+    lines.append("")
+    lines.append("Generated by `scripts/benchmark-ecosystem.sh`.")
+    lines.append("")
+    lines.append(f"- Snapshot date: `{data['snapshot_date']}`")
+    f = data["freshness"]
+    lines.append(f"- Freshness: `{f['status']}` ({f['age_days']} day(s) old, threshold {f['stale_threshold_days']} days)")
+    lines.append(f"- Mode: `{data['mode']}`")
+    lines.append("")
+    lines.append("| Repository | Category | Stars | Commands | Agents | Skills | Hook/Settings Files |")
+    lines.append("|------------|----------|-------|----------|--------|--------|---------------------|")
+    for row in rows:
+        lines.append(f"| `{row['repo']}` | {row['category']} | {row['stars']} | {row['commands_md']} | {row['agents_md']} | {row['skills']} | {row['hook_settings_files']} |")
+    lines.append("")
+    lines.append("## Comparison Matrix")
+    lines.append("")
+    lines.append("| Pattern | Current State | Benchmark Signal | Priority |")
+    lines.append("|---------|---------------|------------------|----------|")
+    for row in data["comparison_matrix"]:
+        lines.append(f"| `{row['pattern']}` | {row['current_state']} | {row['benchmark_signal']} | {row['priority']} |")
+    lines.append("")
+    lines.append("## Notes")
+    lines.append("")
+    for row in rows:
+        lines.append(f"- **`{row['repo']}`** — {row['notes']}")
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    fmt = "markdown"
+    outfile = ""
+    offline = False
+
+    args = sys.argv[1:]
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--offline":
+            offline = True
+        elif a == "--json":
+            fmt = "json"
+        elif a == "--dashboard-json":
+            fmt = "dashboard-json"
+        elif a == "--markdown":
+            fmt = "markdown"
+        elif a == "--format":
+            i += 1
+            fmt = args[i] if i < len(args) else "markdown"
+        elif a == "--out":
+            i += 1
+            outfile = args[i] if i < len(args) else ""
+        elif a in ("-h", "--help"):
+            print(__doc__)
+            sys.exit(0)
+        else:
+            print(f"Unknown option: {a}", file=sys.stderr)
+            sys.exit(1)
+        i += 1
+
+    mode = "offline"
+    if offline:
+        data = annotate_snapshot(SNAPSHOT_DATA)
+    else:
+        mode = "online"
+        try:
+            data = refresh_online(SNAPSHOT_DATA)
+        except Exception:
+            data = annotate_snapshot(SNAPSHOT_DATA)
+            mode = "offline"
+
+    dashboard = render_dashboard(data, mode)
+
+    if fmt == "json":
+        output = json.dumps(data, indent=2)
+    elif fmt == "dashboard-json":
+        output = json.dumps(dashboard, indent=2)
+    else:
+        output = render_markdown(dashboard)
+
+    if outfile:
+        Path(outfile).parent.mkdir(parents=True, exist_ok=True)
+        Path(outfile).write_text(output + "\n", encoding="utf-8")
+    else:
+        print(output)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/check_deps.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Check required dependencies and tell the user what to install.
+
+Detects OS/distro and provides ready-to-copy install commands.
+Called automatically by install.py and doctor.py.
+
+Exit codes:
+    0  all required deps present
+    1  missing required deps (printed to stderr)
+"""
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# Add scripts/ to path for _common import
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import detect_os
+
+
+# ---------------------------------------------------------------------------
+# Dependency definitions
+# ---------------------------------------------------------------------------
+
+REQUIRED = [
+    {
+        "name": "python3",
+        "check": "python3",
+        "min_version": "3.8",
+        "packages": {
+            "brew": "python3",
+            "apt": "python3",
+            "dnf": "python3",
+            "pacman": "python3",
+            "apk": "python3",
+            "zypper": "python3",
+        },
+        "reason": "All toolkit scripts run on Python 3 (stdlib only, no pip needed)",
+    },
+    {
+        "name": "git",
+        "check": "git",
+        "packages": {
+            "brew": "git",
+            "apt": "git",
+            "dnf": "git",
+            "pacman": "git",
+            "apk": "git",
+            "zypper": "git",
+        },
+        "reason": "Version control — hooks, commits, PR workflows",
+    },
+    {
+        "name": "node",
+        "check": "node",
+        "min_version": "18",
+        "packages": {
+            "brew": "node",
+            "apt": "nodejs",
+            "dnf": "nodejs",
+            "pacman": "nodejs",
+            "apk": "nodejs",
+            "zypper": "nodejs18",
+        },
+        "reason": "CLI entry point (bin/ai-toolkit.js)",
+    },
+]
+
+OPTIONAL = [
+    {
+        "name": "sqlite3",
+        "check": "sqlite3",
+        "packages": {
+            "brew": "sqlite",
+            "apt": "sqlite3",
+            "dnf": "sqlite",
+            "pacman": "sqlite",
+            "apk": "sqlite",
+            "zypper": "sqlite3",
+        },
+        "reason": "Memory plugin pack (session persistence via SQLite + FTS5)",
+    },
+    {
+        "name": "bats",
+        "check": "bats",
+        "packages": {
+            "brew": "bats-core",
+            "apt": "bats",
+            "dnf": "bats",
+            "pacman": "bash-bats",
+            "apk": "bats",
+            "zypper": "bats",
+        },
+        "reason": "Running toolkit test suite (npm test)",
+    },
+]
+
+
+# ---------------------------------------------------------------------------
+# Version check helpers
+# ---------------------------------------------------------------------------
+
+def get_version(binary: str) -> str:
+    """Get version string from a binary."""
+    try:
+        result = subprocess.run(
+            [binary, "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        output = result.stdout.strip() or result.stderr.strip()
+        # Extract version number pattern
+        import re
+        match = re.search(r"(\d+\.\d+(?:\.\d+)?)", output)
+        return match.group(1) if match else "unknown"
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return ""
+
+
+def version_ge(actual: str, minimum: str) -> bool:
+    """Check if actual version >= minimum version."""
+    try:
+        actual_parts = [int(x) for x in actual.split(".")[:3]]
+        min_parts = [int(x) for x in minimum.split(".")[:3]]
+        # Pad to same length
+        while len(actual_parts) < len(min_parts):
+            actual_parts.append(0)
+        while len(min_parts) < len(actual_parts):
+            min_parts.append(0)
+        return actual_parts >= min_parts
+    except (ValueError, IndexError):
+        return True  # Can't parse, assume OK
+
+
+# ---------------------------------------------------------------------------
+# Main check
+# ---------------------------------------------------------------------------
+
+def check_deps(verbose: bool = True) -> dict:
+    """Check all dependencies and return status report.
+
+    Returns:
+        dict with keys: os_info, required, optional, all_ok, missing_cmds
+    """
+    os_info = detect_os()
+    pkg_mgr = os_info["pkg_manager"]
+    install_cmd = os_info["install_cmd"]
+
+    results: dict = {
+        "os_info": os_info,
+        "required": [],
+        "optional": [],
+        "all_ok": True,
+        "missing_cmds": [],
+    }
+
+    def check_one(dep: dict, required: bool) -> dict:
+        binary = dep["check"]
+        found = shutil.which(binary) is not None
+        version = get_version(binary) if found else ""
+        min_ver = dep.get("min_version", "")
+
+        ok = found
+        version_ok = True
+        if found and min_ver and version and version != "unknown":
+            version_ok = version_ge(version, min_ver)
+            ok = version_ok
+
+        install_hint = ""
+        if not ok and install_cmd and pkg_mgr in dep.get("packages", {}):
+            pkg = dep["packages"][pkg_mgr]
+            install_hint = f"{install_cmd} {pkg}"
+
+        return {
+            "name": dep["name"],
+            "found": found,
+            "version": version,
+            "version_ok": version_ok,
+            "min_version": min_ver,
+            "required": required,
+            "reason": dep["reason"],
+            "install_hint": install_hint,
+        }
+
+    for dep in REQUIRED:
+        result = check_one(dep, required=True)
+        results["required"].append(result)
+        if not result["found"] or not result["version_ok"]:
+            results["all_ok"] = False
+            if result["install_hint"]:
+                results["missing_cmds"].append(result["install_hint"])
+
+    for dep in OPTIONAL:
+        result = check_one(dep, required=False)
+        results["optional"].append(result)
+
+    return results
+
+
+def print_report(results: dict) -> None:
+    """Print human-readable dependency report."""
+    os_info = results["os_info"]
+    print(f"System: {os_info['os']} ({os_info.get('distro', 'unknown')})")
+    print(f"Package manager: {os_info['pkg_manager']}")
+    print()
+
+    print("Required:")
+    for dep in results["required"]:
+        if dep["found"] and dep["version_ok"]:
+            ver = f" ({dep['version']})" if dep["version"] else ""
+            print(f"  OK  {dep['name']}{ver}")
+        elif dep["found"] and not dep["version_ok"]:
+            print(f"  !!  {dep['name']} ({dep['version']}) — need >= {dep['min_version']}")
+            if dep["install_hint"]:
+                print(f"      Fix: {dep['install_hint']}")
+        else:
+            print(f"  !!  {dep['name']} — NOT FOUND")
+            print(f"      Why: {dep['reason']}")
+            if dep["install_hint"]:
+                print(f"      Fix: {dep['install_hint']}")
+
+    print()
+    print("Optional:")
+    for dep in results["optional"]:
+        if dep["found"]:
+            ver = f" ({dep['version']})" if dep["version"] else ""
+            print(f"  OK  {dep['name']}{ver}")
+        else:
+            print(f"  --  {dep['name']} — not installed")
+            print(f"      Why: {dep['reason']}")
+            if dep["install_hint"]:
+                print(f"      Fix: {dep['install_hint']}")
+
+    if not results["all_ok"]:
+        print()
+        print("Missing required dependencies! Install with:")
+        for cmd in results["missing_cmds"]:
+            print(f"  {cmd}")
+        print()
+
+
+def main() -> None:
+    """CLI entry point."""
+    json_mode = "--json" in sys.argv
+    results = check_deps()
+
+    if json_mode:
+        print(json.dumps(results, indent=2))
+    else:
+        print_report(results)
+
+    sys.exit(0 if results["all_ok"] else 1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/create_skill.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+"""ai-toolkit create skill -- Scaffold a new skill from a template.
+
+Usage:
+  create_skill.py <name> --template=<type> [--description="..."] [--output-dir=<path>]
+
+Templates: linter, reviewer, generator, workflow, knowledge
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import toolkit_dir
+
+
+def _parse_args(argv: list[str]) -> dict[str, str]:
+    """Parse CLI arguments into a dict."""
+    result: dict[str, str] = {
+        "name": "",
+        "template": "",
+        "description": "",
+        "output_dir": str(toolkit_dir / "app" / "skills"),
+    }
+
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg.startswith("--template="):
+            result["template"] = arg.split("=", 1)[1]
+        elif arg == "--template":
+            i += 1
+            result["template"] = argv[i] if i < len(argv) else ""
+        elif arg.startswith("--description="):
+            result["description"] = arg.split("=", 1)[1]
+        elif arg == "--description":
+            i += 1
+            result["description"] = argv[i] if i < len(argv) else ""
+        elif arg.startswith("--output-dir="):
+            result["output_dir"] = arg.split("=", 1)[1]
+        elif arg == "--output-dir":
+            i += 1
+            result["output_dir"] = argv[i] if i < len(argv) else ""
+        elif arg.startswith("-"):
+            print(f"Unknown option: {arg}", file=sys.stderr)
+            sys.exit(1)
+        else:
+            result["name"] = arg
+        i += 1
+
+    return result
+
+
+def main() -> None:
+    """Scaffold a new skill from a template."""
+    args = _parse_args(sys.argv[1:])
+    name = args["name"]
+    template = args["template"]
+    description = args["description"]
+    output_dir = Path(args["output_dir"])
+    templates_dir = toolkit_dir / "app" / "templates" / "skill"
+
+    # Validate name
+    if not name:
+        print("Error: skill name is required", file=sys.stderr)
+        print("Usage: ai-toolkit create skill <name> --template=<type>", file=sys.stderr)
+        sys.exit(1)
+
+    if re.search(r"[^a-z0-9-]", name):
+        print(f"Error: skill name must be lowercase with hyphens only (got: {name})", file=sys.stderr)
+        sys.exit(1)
+
+    if len(name) > 64:
+        print(f"Error: skill name must be at most 64 characters (got: {len(name)})", file=sys.stderr)
+        sys.exit(1)
+
+    # Validate template
+    if not template:
+        print("Error: --template is required", file=sys.stderr)
+        print("Available templates: linter, reviewer, generator, workflow, knowledge", file=sys.stderr)
+        sys.exit(1)
+
+    template_file = templates_dir / template / "SKILL.md.template"
+    if not template_file.is_file():
+        available = " ".join(
+            d.name for d in sorted(templates_dir.iterdir()) if d.is_dir()
+        ) if templates_dir.is_dir() else "(none)"
+        print(f"Error: unknown template '{template}'", file=sys.stderr)
+        print(f"Available templates: {available}", file=sys.stderr)
+        sys.exit(1)
+
+    # Check target does not exist
+    target_dir = output_dir / name
+    if target_dir.is_dir():
+        print(f"Error: skill '{name}' already exists at {target_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    # Default description
+    if not description:
+        description = f"Provides {name} functionality"
+
+    # Create skill from template
+    target_dir.mkdir(parents=True, exist_ok=True)
+    content = template_file.read_text(encoding="utf-8")
+    content = content.replace("{{NAME}}", name).replace("{{DESCRIPTION}}", description)
+    (target_dir / "SKILL.md").write_text(content, encoding="utf-8")
+
+    print(f"Created: {target_dir}/SKILL.md (from {template} template)")
+    print()
+    print("Next steps:")
+    print(f"  1. Edit {target_dir}/SKILL.md")
+    print("  2. Run: ai-toolkit validate")
+
+
+if __name__ == "__main__":
+    main()