@softspark/ai-toolkit 4.2.4 → 4.2.5

package/scripts/generate_cursor_hooks.py

@@ -43,6 +43,7 @@ CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
     "beforeShellExecution": [
         ("", "guard-destructive.sh"),
         ("", "commit-quality.sh"),
+        ("", "revert-guard.sh"),
     ],
     "beforeReadFile": [
         ("", "guard-path.sh"),
@@ -50,6 +51,7 @@ CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
     "afterFileEdit": [
         ("", "post-tool-use.sh"),
         ("", "governance-capture.sh"),
+        ("", "test-cohesion.sh"),
     ],
     "beforeSubmitPrompt": [
         ("", "user-prompt-submit.sh"),
@@ -58,6 +60,9 @@ CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
     "beforeMCPExecution": [
         ("", "guard-config.sh"),
     ],
+    "afterMCPExecution": [
+        ("", "search-tracker.sh"),
+    ],
     "preCompact": [
         ("", "pre-compact.sh"),
         ("", "pre-compact-save.sh"),
@@ -71,6 +76,7 @@ CURSOR_HOOKS: dict[str, list[tuple[str, str]]] = {
     "stop": [
         ("", "quality-check.sh"),
         ("", "save-session.sh"),
+        ("", "stop-search-check.sh"),
     ],
     "sessionEnd": [
         ("", "session-end.sh"),

package/scripts/generate_gemini_hooks.py

@@ -29,7 +29,7 @@ import json
 import sys
 from pathlib import Path
 
-HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
+HOOKS_PREFIX = 'AI_TOOLKIT_HOOK_FORMAT=json "$HOME/.softspark/ai-toolkit/hooks/'
 SOURCE_TAG = "ai-toolkit"
 
 # Event -> list of (matcher, script) pairs. Matcher semantics:
@@ -46,13 +46,16 @@ GEMINI_HOOKS: dict[str, list[tuple[str, str]]] = {
         # run_shell_command covers Bash-equivalent destructive patterns
         ("run_shell_command", "guard-destructive.sh"),
         ("run_shell_command", "commit-quality.sh"),
+        ("run_shell_command", "revert-guard.sh"),
         # File-touching tools — guard paths + config
         ("write_file|edit|replace|read_file", "guard-path.sh"),
         ("write_file|edit|replace", "guard-config.sh"),
     ],
     "AfterTool": [
         ("write_file|edit|replace", "post-tool-use.sh"),
+        ("write_file|edit|replace", "test-cohesion.sh"),
         ("run_shell_command|write_file|edit|replace", "governance-capture.sh"),
+        ("google_web_search|web_fetch", "search-tracker.sh"),
     ],
     "BeforeAgent": [
         ("", "user-prompt-submit.sh"),
@@ -62,6 +65,7 @@ GEMINI_HOOKS: dict[str, list[tuple[str, str]]] = {
         # Closest equivalent to Claude's Stop event. Gemini has no native Stop.
         ("", "quality-check.sh"),
         ("", "save-session.sh"),
+        ("", "stop-search-check.sh"),
     ],
     "BeforeModel": [
         # Light-weight observability slot. Reuses the session-context probe.

package/scripts/generate_windsurf_hooks.py

@@ -41,10 +41,12 @@ WINDSURF_HOOKS: dict[str, list[str]] = {
     "post_write_code": [
         "post-tool-use.sh",
         "governance-capture.sh",
+        "test-cohesion.sh",
     ],
     "pre_run_command": [
         "guard-destructive.sh",
         "commit-quality.sh",
+        "revert-guard.sh",
     ],
     "post_run_command": [
         "governance-capture.sh",
@@ -52,6 +54,9 @@ WINDSURF_HOOKS: dict[str, list[str]] = {
     "pre_mcp_tool_use": [
         "guard-config.sh",
     ],
+    "post_mcp_tool_use": [
+        "search-tracker.sh",
+    ],
     "pre_user_prompt": [
         "user-prompt-submit.sh",
         "track-usage.sh",
@@ -59,6 +64,7 @@ WINDSURF_HOOKS: dict[str, list[str]] = {
     "post_cascade_response": [
         "quality-check.sh",
         "save-session.sh",
+        "stop-search-check.sh",
     ],
     "post_setup_worktree": [
         "session-context.sh",

package/scripts/install_steps/hooks.py

@@ -58,6 +58,9 @@ def _copy_hook_scripts(claude_dir: Path, hooks_scripts_dir: Path) -> None:
         shutil.copy2(hook_file, dst)
         dst.chmod(dst.stat().st_mode | 0o111)
         copied += 1
+    for runtime_file in sorted(hooks_src.glob("*.json")):
+        shutil.copy2(runtime_file, hooks_scripts_dir / runtime_file.name)
+        copied += 1
     print(f"  Copied: {copied} hook scripts to ~/.softspark/ai-toolkit/hooks/")
     legacy_hooks = claude_dir / "hooks"
     if legacy_hooks.is_symlink():
@@ -68,7 +71,9 @@ def _copy_hook_scripts(claude_dir: Path, hooks_scripts_dir: Path) -> None:
 # Python helpers that hooks invoke at runtime. Kept narrow on purpose — only
 # scripts that a deployed hook actually executes belong here.
 HOOK_RUNTIME_SCRIPTS: tuple[str, ...] = (
+    "session_state.py",
     "session_token_stats.py",
+    "test_cohesion.py",
     "version_check.py",
 )
 

package/scripts/merge-hooks.py

@@ -41,7 +41,16 @@ LEGACY_TOOLKIT_HOOKS = {
                     ),
                 }
             ],
-        }
+        },
+        {
+            "matcher": "",
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": "bash ~/.softspark/ai-toolkit/hooks/notify-waiting.sh",
+                }
+            ],
+        },
     ],
 }
 

package/scripts/plugin_schema.py

@@ -32,6 +32,10 @@ VALID_HOOK_EVENTS = frozenset({
     "SessionStart", "Notification", "PreToolUse", "PostToolUse", "Stop",
     "PreCompact", "SubagentStop", "UserPromptSubmit", "TaskCompleted",
     "TeammateIdle", "SubagentStart", "SessionEnd", "PermissionRequest", "Setup",
+    "InstructionsLoaded", "ConfigChange", "PostToolUseFailure", "PostToolBatch",
+    "UserPromptExpansion", "PostCompact", "StopFailure", "CwdChanged",
+    "FileChanged", "PermissionDenied", "Elicitation", "ElicitationResult",
+    "WorktreeCreate", "WorktreeRemove", "TaskCreated",
 })
 
 

package/scripts/session_state.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python3
+"""Session edit state tracker for ai-toolkit hooks.
+
+Stores per-session file edits so hooks can:
+- Know which paths were touched (revert-guard, test-cohesion).
+- Run only related tests (quality-gate ai-toolkit branch).
+
+State file: ``~/.softspark/ai-toolkit/state/session-edits.json``
+
+Usage:
+    session_state.py reset [--session-id ID]
+    session_state.py append --tool Edit --path /abs/path [--session-id ID]
+    session_state.py was-edited /abs/path
+    session_state.py list
+    session_state.py session-id
+
+Exit codes:
+    0  success / true
+    1  false / not found (for boolean queries)
+    2  usage error
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as _dt
+import json
+import os
+import sys
+import uuid
+from pathlib import Path
+
+STATE_DIR = Path(os.path.expanduser("~/.softspark/ai-toolkit/state"))
+STATE_FILE = STATE_DIR / "session-edits.json"
+MAX_EDITS = 5000  # cap to avoid unbounded growth
+
+
+def _now() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _ensure_dir() -> None:
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def _load() -> dict:
+    if not STATE_FILE.is_file():
+        return {"session_id": "", "started_at": "", "edits": []}
+    try:
+        with STATE_FILE.open() as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {"session_id": "", "started_at": "", "edits": []}
+    data.setdefault("session_id", "")
+    data.setdefault("started_at", "")
+    data.setdefault("edits", [])
+    return data
+
+
+def _save(data: dict) -> None:
+    _ensure_dir()
+    tmp = STATE_FILE.with_suffix(".json.tmp")
+    with tmp.open("w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    os.replace(tmp, STATE_FILE)
+
+
+def cmd_reset(session_id: str | None) -> int:
+    sid = session_id or str(uuid.uuid4())
+    _save({"session_id": sid, "started_at": _now(), "edits": []})
+    return 0
+
+
+def cmd_append(tool: str, path: str, session_id: str | None) -> int:
+    if not path:
+        return 0  # silently ignore tools without file_path (e.g., bash)
+    data = _load()
+    if session_id and data["session_id"] != session_id:
+        # New session detected mid-stream — auto-reset.
+        cmd_reset(session_id)
+        data = _load()
+    abs_path = os.path.abspath(path)
+    data["edits"].append({"ts": _now(), "tool": tool, "path": abs_path})
+    if len(data["edits"]) > MAX_EDITS:
+        data["edits"] = data["edits"][-MAX_EDITS:]
+    _save(data)
+    return 0
+
+
+def cmd_was_edited(path: str) -> int:
+    abs_path = os.path.abspath(path)
+    data = _load()
+    for edit in data["edits"]:
+        if edit.get("path") == abs_path:
+            return 0
+    return 1
+
+
+def cmd_list() -> int:
+    data = _load()
+    seen: set[str] = set()
+    for edit in data["edits"]:
+        p = edit.get("path", "")
+        if p and p not in seen:
+            seen.add(p)
+            print(p)
+    return 0
+
+
+def cmd_session_id() -> int:
+    data = _load()
+    print(data.get("session_id", ""))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Session edit state tracker")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    reset = sub.add_parser("reset", help="Clear state, start fresh session")
+    reset.add_argument("--session-id", default=None)
+
+    append = sub.add_parser("append", help="Record an edit")
+    append.add_argument("--tool", required=True)
+    append.add_argument("--path", required=True)
+    append.add_argument("--session-id", default=None)
+
+    was = sub.add_parser("was-edited", help="Exit 0 if path was edited this session")
+    was.add_argument("path")
+
+    sub.add_parser("list", help="Print unique edited paths, one per line")
+    sub.add_parser("session-id", help="Print current session id")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "reset":
+        return cmd_reset(args.session_id)
+    if args.cmd == "append":
+        return cmd_append(args.tool, args.path, args.session_id)
+    if args.cmd == "was-edited":
+        return cmd_was_edited(args.path)
+    if args.cmd == "list":
+        return cmd_list()
+    if args.cmd == "session-id":
+        return cmd_session_id()
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/test_cohesion.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Test cohesion resolver for ai-toolkit hooks.
+
+Reads a project-local or toolkit-default test-cohesion-map and answers:
+"given these changed paths, what tests should run?"
+
+Map format (JSON array of rules):
+    [
+        {
+            "match": "app/hooks/*.sh",           # glob, repo-rooted
+            "tests": ["tests/test_hooks.bats"],
+            "runner": "bats",                    # bats|pytest|vitest|jest|custom
+            "command": null                      # optional: full command override
+        }
+    ]
+
+Lookup order:
+    1. $PWD/.claude/test-cohesion-map.json (project override)
+    2. $TOOLKIT_DIR/app/hooks/test-cohesion-map.json (toolkit default)
+
+Usage:
+    test_cohesion.py resolve --changed-paths PATH [PATH ...] [--repo-root DIR]
+        Prints one shell command per line. Exit 0 if any test commands resolved,
+        1 if no rules matched (so hook can skip silently).
+"""
+from __future__ import annotations
+
+import argparse
+import fnmatch
+import json
+import os
+import sys
+from pathlib import Path
+
+DEFAULT_RUNNERS: dict[str, str] = {
+    "bats": "bats --no-parallelize-within-files",
+    "pytest": "pytest -x",
+    "vitest": "npx vitest run",
+    "jest": "npx jest --bail",
+}
+
+
+def _toolkit_dir() -> Path | None:
+    env = os.environ.get("AI_TOOLKIT_DIR")
+    if env and Path(env).is_dir():
+        return Path(env)
+    # Walk up from this script: scripts/ -> repo root
+    here = Path(__file__).resolve()
+    candidate = here.parent.parent
+    if (candidate / "app" / "hooks.json").is_file():
+        return candidate
+    return None
+
+
+def _load_map(repo_root: Path) -> list[dict]:
+    candidates = [repo_root / ".claude" / "test-cohesion-map.json"]
+    tk = _toolkit_dir()
+    if tk:
+        candidates.append(tk / "hooks" / "test-cohesion-map.json")
+        candidates.append(tk / "app" / "hooks" / "test-cohesion-map.json")
+    for path in candidates:
+        if not path.is_file():
+            continue
+        try:
+            with path.open() as f:
+                data = json.load(f)
+        except (json.JSONDecodeError, OSError):
+            continue
+        if isinstance(data, list):
+            return data
+    return []
+
+
+def _matches(path: str, pattern: str) -> bool:
+    return fnmatch.fnmatch(path, pattern) or fnmatch.fnmatch(
+        os.path.basename(path), pattern
+    )
+
+
+def _relpath(repo_root: Path, abs_path: str) -> str:
+    try:
+        return str(Path(abs_path).resolve().relative_to(repo_root.resolve()))
+    except (ValueError, OSError):
+        return abs_path
+
+
+def resolve(repo_root: Path, changed: list[str]) -> list[str]:
+    rules = _load_map(repo_root)
+    if not rules:
+        return []
+    # First-match-wins per changed path. List specific rules before broad
+    # globs in the map to control scope.
+    buckets: dict[tuple[str, str | None], set[str]] = {}
+    for raw in changed:
+        rel = _relpath(repo_root, raw)
+        for rule in rules:
+            pattern = rule.get("match")
+            if not pattern or not _matches(rel, pattern):
+                continue
+            runner = rule.get("runner", "bats")
+            command_override = rule.get("command")
+            key = (runner, command_override)
+            buckets.setdefault(key, set()).update(rule.get("tests", []))
+            break  # first match wins for this path
+    if not buckets:
+        return []
+    commands: list[str] = []
+    for (runner, override), tests in buckets.items():
+        if override:
+            commands.append(override)
+            continue
+        base = DEFAULT_RUNNERS.get(runner, runner)
+        commands.append(f"{base} {' '.join(sorted(tests))}".strip())
+    return commands
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Resolve cohesion test commands")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    r = sub.add_parser("resolve")
+    r.add_argument("--changed-paths", nargs="+", required=True)
+    r.add_argument("--repo-root", default=os.getcwd())
+    args = parser.parse_args(argv)
+
+    repo_root = Path(args.repo_root)
+    commands = resolve(repo_root, args.changed_paths)
+    for c in commands:
+        print(c)
+    return 0 if commands else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())