@softspark/ai-toolkit 3.0.0 → 3.0.2

package/scripts/check_deps.py

@@ -37,6 +37,9 @@ REQUIRED = [
             "pacman": "python3",
             "apk": "python3",
             "zypper": "python3",
+            "winget": "Python.Python.3",
+            "choco": "python",
+            "scoop": "python",
         },
         "reason": "All toolkit scripts run on Python 3 (stdlib only, no pip needed)",
     },
@@ -50,6 +53,9 @@ REQUIRED = [
             "pacman": "git",
             "apk": "git",
             "zypper": "git",
+            "winget": "Git.Git",
+            "choco": "git",
+            "scoop": "git",
         },
         "reason": "Version control — hooks, commits, PR workflows",
     },
@@ -64,6 +70,9 @@ REQUIRED = [
             "pacman": "nodejs",
             "apk": "nodejs",
             "zypper": "nodejs18",
+            "winget": "OpenJS.NodeJS",
+            "choco": "nodejs",
+            "scoop": "nodejs",
         },
         "reason": "CLI entry point (bin/ai-toolkit.js)",
     },
@@ -80,6 +89,9 @@ OPTIONAL = [
             "pacman": "sqlite",
             "apk": "sqlite",
             "zypper": "sqlite3",
+            "winget": "SQLite.SQLite",
+            "choco": "sqlite",
+            "scoop": "sqlite",
         },
         "reason": "Memory plugin pack (session persistence via SQLite + FTS5)",
     },
@@ -93,6 +105,8 @@ OPTIONAL = [
             "pacman": "bash-bats",
             "apk": "bats",
             "zypper": "bats",
+            "choco": "bats",
+            "scoop": "bats",
         },
         "reason": "Running toolkit test suite (npm test)",
     },

package/scripts/stats.py

@@ -5,11 +5,13 @@ Reads ~/.softspark/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
+  --reset     Clear all stats
+  --json      Output raw JSON
+  --summary   Output product telemetry summary
 """
 from __future__ import annotations
 
+from datetime import datetime, timedelta
 import json
 import sys
 from pathlib import Path
@@ -18,14 +20,120 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
 from paths import STATS_FILE as _STATS_FILE
 
 STATS_FILE = _STATS_FILE
+TOOLKIT_DIR = Path(__file__).resolve().parent.parent
+
+
+def _load_stats() -> dict:
+    """Load the stats file, returning an empty dict when absent."""
+    if not STATS_FILE.is_file():
+        return {}
+    with open(STATS_FILE, encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _aggregate_rows(data: dict) -> list[tuple[str, dict]]:
+    """Normalize supported stats formats into sorted (name, info) rows."""
+    if not data:
+        return []
+
+    # Handle both formats: {skill: {count, last_used}} and {loop_runs: [...]}
+    if "loop_runs" in data:
+        agg: dict[str, dict] = {}
+        for run in data.get("loop_runs", []):
+            cmd = run.get("command", "unknown")
+            iters = run.get("iterations", [])
+            if cmd not in agg:
+                agg[cmd] = {"count": 0, "last_used": "unknown"}
+            agg[cmd]["count"] += len(iters) if iters else 1
+            started = run.get("started_at", "")
+            if started > agg[cmd]["last_used"]:
+                agg[cmd]["last_used"] = started
+        return sorted(agg.items(), key=lambda x: x[1].get("count", 0), reverse=True)
+
+    skill_data = {k: v for k, v in data.items() if isinstance(v, dict)}
+    return sorted(skill_data.items(), key=lambda x: x[1].get("count", 0), reverse=True)
+
+
+def _catalog_skill_names() -> set[str]:
+    """Return skill directory names from the installed toolkit catalog."""
+    skills_dir = TOOLKIT_DIR / "app" / "skills"
+    if not skills_dir.is_dir():
+        return set()
+    return {
+        p.name
+        for p in skills_dir.iterdir()
+        if p.is_dir() and not p.name.startswith("_") and (p / "SKILL.md").is_file()
+    }
+
+
+def _parse_datetime(value: str) -> datetime | None:
+    """Parse stats timestamps emitted by toolkit hooks and loop runs."""
+    for fmt in ("%Y-%m-%d %H:%M:%S", "%Y-%m-%dT%H:%M:%S", "%Y-%m-%dT%H:%M:%SZ"):
+        try:
+            return datetime.strptime(value[:19] + ("Z" if fmt.endswith("Z") else ""), fmt)
+        except ValueError:
+            continue
+    return None
+
+
+def _build_summary(rows: list[tuple[str, dict]]) -> dict:
+    """Build machine-readable product telemetry from aggregated rows."""
+    catalog = _catalog_skill_names()
+    used_names = {name for name, _ in rows}
+    used_catalog = used_names & catalog if catalog else used_names
+    total = sum(int(info.get("count", 0) or 0) for _, info in rows)
+
+    cutoff = datetime.now() - timedelta(days=7)
+    active_7d = 0
+    for _, info in rows:
+        last_used = _parse_datetime(str(info.get("last_used", "")))
+        if last_used and last_used >= cutoff:
+            active_7d += 1
+
+    catalog_total = len(catalog)
+    unused = max(catalog_total - len(used_catalog), 0) if catalog_total else 0
+
+    return {
+        "totalInvocations": total,
+        "uniqueSkillsUsed": len(used_names),
+        "catalogSkillsTotal": catalog_total,
+        "unusedCatalogSkills": unused,
+        "catalogCoveragePct": round((len(used_catalog) / catalog_total) * 100, 1) if catalog_total else 0,
+        "activeSkills7d": active_7d,
+        "topSkills": [
+            {
+                "name": name,
+                "count": int(info.get("count", 0) or 0),
+                "lastUsed": info.get("last_used", "unknown"),
+            }
+            for name, info in rows[:5]
+        ],
+    }
+
+
+def _print_summary(summary: dict) -> None:
+    """Print a compact human-readable product telemetry summary."""
+    print("Product Telemetry")
+    print("=================")
+    print(f"Total invocations: {summary['totalInvocations']}")
+    print(f"Unique skills used: {summary['uniqueSkillsUsed']}")
+    print(f"Catalog skills total: {summary['catalogSkillsTotal']}")
+    print(f"Unused catalog skills: {summary['unusedCatalogSkills']}")
+    print(f"Catalog coverage: {summary['catalogCoveragePct']}%")
+    print(f"Active skills in last 7 days: {summary['activeSkills7d']}")
+    if summary["topSkills"]:
+        print()
+        print("Top skills:")
+        for item in summary["topSkills"]:
+            print(f"- {item['name']}: {item['count']} ({item['lastUsed']})")
 
 
 def main() -> None:
     """Display, export, or reset usage statistics."""
-    flag = sys.argv[1] if len(sys.argv) > 1 else ""
+    args = set(sys.argv[1:])
 
     # --reset
-    if flag == "--reset":
+    if "--reset" in args:
         if STATS_FILE.is_file():
             STATS_FILE.unlink()
             print("Stats reset.")
@@ -33,12 +141,20 @@ def main() -> None:
             print("No stats file found.")
         return
 
-    # --json
-    if flag == "--json":
-        if STATS_FILE.is_file():
-            print(STATS_FILE.read_text(encoding="utf-8"), end="")
+    data = _load_stats()
+    rows = _aggregate_rows(data)
+
+    if "--summary" in args:
+        summary = _build_summary(rows)
+        if "--json" in args:
+            print(json.dumps(summary, indent=2))
         else:
-            print("{}")
+            _print_summary(summary)
+        return
+
+    # --json
+    if "--json" in args:
+        print(STATS_FILE.read_text(encoding="utf-8") if STATS_FILE.is_file() else "{}")
         return
 
     # Default: pretty-print table
@@ -53,39 +169,10 @@ def main() -> None:
     print("========================")
     print()
 
-    with open(STATS_FILE, encoding="utf-8") as f:
-        data: dict = json.load(f)
-
-    if not data:
+    if not rows:
         print("No invocations recorded.")
         return
 
-    # Handle both formats: {skill: {count, last_used}} and {loop_runs: [...]}
-    if "loop_runs" in data:
-        runs = data["loop_runs"]
-        if not runs:
-            print("No invocations recorded.")
-            return
-        # Aggregate loop_runs by command
-        agg: dict[str, dict] = {}
-        for run in runs:
-            cmd = run.get("command", "unknown")
-            iters = run.get("iterations", [])
-            if cmd not in agg:
-                agg[cmd] = {"count": 0, "last_used": "unknown"}
-            agg[cmd]["count"] += len(iters) if iters else 1
-            started = run.get("started_at", "")
-            if started > agg[cmd]["last_used"]:
-                agg[cmd]["last_used"] = started
-        rows = sorted(agg.items(), key=lambda x: x[1]["count"], reverse=True)
-    else:
-        # Original format: {skill_name: {count, last_used}}
-        skill_data = {k: v for k, v in data.items() if isinstance(v, dict)}
-        if not skill_data:
-            print("No invocations recorded.")
-            return
-        rows = sorted(skill_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:

package/scripts/validate.py

@@ -42,9 +42,9 @@ VALID_HOOK_EVENTS = frozenset({
     # Core lifecycle
     "SessionStart", "SessionEnd", "UserPromptSubmit", "Notification",
     # Tool lifecycle
-    "PreToolUse", "PostToolUse",
+    "PreToolUse", "PostToolUse", "PostToolUseFailure", "PostToolBatch",
     # Turn lifecycle
-    "Stop", "StopFailure",
+    "Stop", "StopFailure", "UserPromptExpansion",
     # Subagent lifecycle
     "SubagentStart", "SubagentStop",
     # Compaction
@@ -61,11 +61,67 @@ VALID_HOOK_EVENTS = frozenset({
     "Setup", "InstructionsLoaded",
 })
 
+VALID_HOOK_TYPES = frozenset({
+    "command",
+    "http",
+    "prompt",
+    "agent",
+    "mcp_tool",
+})
+
+HOOK_TYPE_EVENTS = {
+    "agent": frozenset({"Stop", "SubagentStop"}),
+    "prompt": frozenset({
+        "PreToolUse",
+        "PostToolUse",
+        "PostToolUseFailure",
+        "PostToolBatch",
+        "UserPromptSubmit",
+        "UserPromptExpansion",
+        "Stop",
+        "SubagentStop",
+    }),
+}
+
+HOOK_REQUIRED_FIELDS = {
+    "command": ("command",),
+    "http": ("url",),
+    "prompt": ("prompt",),
+    "agent": ("agent",),
+    "mcp_tool": ("server", "tool", "arguments"),
+}
+
 VALID_KB_CATEGORIES = frozenset({
     "reference", "howto", "procedures", "troubleshooting", "best-practices",
     "planning",
 })
 
+VALID_RULE_CATEGORIES = frozenset({
+    "coding-style",
+    "testing",
+    "security",
+    "performance",
+    "git-workflow",
+    "patterns",
+    "frameworks",
+})
+
+COMMON_RULE_CATEGORIES = frozenset({
+    "coding-style",
+    "testing",
+    "security",
+    "performance",
+    "git-workflow",
+})
+
+LANGUAGE_RULE_CATEGORIES = frozenset({
+    "coding-style",
+    "testing",
+    "security",
+    "patterns",
+    "frameworks",
+})
+
 PLANNED_ASSETS = [
     "app/.claude-plugin/plugin.json",
     "scripts/doctor.py",
@@ -354,8 +410,49 @@ def validate_legacy_commands(tk_dir: Path, vr: ValidationResult) -> None:
             print()
 
 
+def _validate_hook_handler(event: str, hook: dict, vr: ValidationResult) -> None:
+    """Validate one hooks.json handler object."""
+    hook_type = hook.get("type")
+    if not hook_type:
+        vr.error(f"{event}: hook entry missing type")
+        return
+
+    if hook_type not in VALID_HOOK_TYPES:
+        vr.error(f"Unsupported hook handler type '{hook_type}' for event {event}")
+        return
+
+    allowed_events = HOOK_TYPE_EVENTS.get(hook_type)
+    if allowed_events is not None and event not in allowed_events:
+        vr.error(f"Hook type '{hook_type}' is not supported for event {event}")
+
+    for field in HOOK_REQUIRED_FIELDS.get(hook_type, ()):
+        if field not in hook:
+            vr.error(f"{event}: hook type '{hook_type}' missing required field '{field}'")
+
+
+def _validate_hook_entries(event: str, entries: object, vr: ValidationResult) -> None:
+    """Validate hooks.json matcher entries for one event."""
+    if not isinstance(entries, list):
+        vr.error(f"{event}: expected list of hook matcher entries")
+        return
+
+    for index, entry in enumerate(entries):
+        if not isinstance(entry, dict):
+            vr.error(f"{event}[{index}]: expected hook matcher entry object")
+            continue
+        hooks = entry.get("hooks")
+        if not isinstance(hooks, list) or not hooks:
+            vr.error(f"{event}[{index}]: missing non-empty hooks list")
+            continue
+        for hook_index, hook in enumerate(hooks):
+            if not isinstance(hook, dict):
+                vr.error(f"{event}[{index}].hooks[{hook_index}]: expected hook object")
+                continue
+            _validate_hook_handler(event, hook, vr)
+
+
 def validate_hook_events(tk_dir: Path, vr: ValidationResult) -> None:
-    """Validate hook event names in hooks.json."""
+    """Validate hook event names and handler shapes in hooks.json."""
     print("## Hook Events")
     hooks_file = tk_dir / "app" / "hooks.json"
 
@@ -373,9 +470,10 @@ def validate_hook_events(tk_dir: Path, vr: ValidationResult) -> None:
         return
 
     hooks = data.get("hooks", {})
-    for event in hooks:
+    for event, entries in hooks.items():
         if event in VALID_HOOK_EVENTS:
             print(f"  OK: {event}")
+            _validate_hook_entries(event, entries, vr)
         else:
             vr.error(f"Unknown hook event: {event}")
 
@@ -386,6 +484,63 @@ def validate_hook_events(tk_dir: Path, vr: ValidationResult) -> None:
     print()
 
 
+def validate_language_rules(tk_dir: Path, vr: ValidationResult) -> None:
+    """Validate structured language-rule directories under app/rules."""
+    print("## Language Rules")
+    rules_dir = tk_dir / "app" / "rules"
+    rule_count = 0
+    rule_errors = 0
+
+    if not rules_dir.is_dir():
+        vr.error("app/rules directory not found")
+        print()
+        return
+
+    for rule_dir in sorted(p for p in rules_dir.iterdir() if p.is_dir()):
+        language = rule_dir.name
+        expected = COMMON_RULE_CATEGORIES if language == "common" else LANGUAGE_RULE_CATEGORIES
+        seen: set[str] = set()
+
+        for rule_file in sorted(rule_dir.glob("*.md")):
+            rel = str(rule_file.relative_to(tk_dir))
+            rule_count += 1
+            if not _has_frontmatter(rule_file):
+                vr.error(f"{rel} - Missing YAML frontmatter")
+                rule_errors += 1
+                continue
+
+            fm_lines = _parse_frontmatter_lines(rule_file)
+            for field in ("language", "category", "version"):
+                if not _fm_has(fm_lines, field):
+                    vr.error(f"{rel} - Missing required field: {field}")
+                    rule_errors += 1
+
+            rule_language = _fm_field(fm_lines, "language").strip()
+            if rule_language and rule_language != language:
+                vr.error(f"{rel} language '{rule_language}' does not match directory '{language}'")
+                rule_errors += 1
+
+            category = _fm_field(fm_lines, "category").strip()
+            if category:
+                seen.add(category)
+                if category not in VALID_RULE_CATEGORIES:
+                    vr.error(f"{rel} has invalid rule category '{category}'")
+                    rule_errors += 1
+                if rule_file.stem != category:
+                    vr.error(f"{rel} filename does not match category '{category}'")
+                    rule_errors += 1
+
+        for category in sorted(expected - seen):
+            vr.error(f"app/rules/{language} missing required rule category: {category}")
+            rule_errors += 1
+
+    if rule_errors == 0:
+        print(f"  OK: {rule_count} rule files validated")
+    else:
+        print(f"  Found: {rule_count} rule files ({rule_errors} with errors)")
+    print()
+
+
 def validate_planned_assets(tk_dir: Path, vr: ValidationResult) -> None:
     """Validate that planned assets exist and are non-empty."""
     print("## Planned Assets")
@@ -781,6 +936,7 @@ def _run_all_checks(tk_dir: Path, vr: ValidationResult) -> tuple[int, int, str]:
     skill_count = validate_skills(tk_dir, vr)
     validate_legacy_commands(tk_dir, vr)
     validate_hook_events(tk_dir, vr)
+    validate_language_rules(tk_dir, vr)
     validate_planned_assets(tk_dir, vr)
     validate_plugin_packs(tk_dir, vr)
     validate_kb_documents(tk_dir, vr)