@softspark/ai-toolkit 4.2.4 → 4.3.0

package/scripts/mcp_sources.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""URL source registry for externally-injected MCP templates.
+
+Tracks which MCP templates were registered from a URL or local file so that
+`ai-toolkit update` can re-fetch the latest version and re-inject. Mirrors
+the design of hook_sources.py for parity between inject-hook and inject-mcp.
+
+Metadata stored in ~/.softspark/ai-toolkit/mcp-templates/external/sources.json.
+
+Stdlib-only -- no external dependencies.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import sys
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from paths import EXTERNAL_MCP_DIR
+
+_SOURCES_FILENAME = "sources.json"
+
+
+def _sources_path(mcp_dir: Path | None = None) -> Path:
+    return (mcp_dir or EXTERNAL_MCP_DIR) / _SOURCES_FILENAME
+
+
+def load_sources(mcp_dir: Path | None = None) -> dict[str, dict[str, Any]]:
+    """Load sources.json. Returns {} if missing or corrupt."""
+    path = _sources_path(mcp_dir)
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, encoding="utf-8") as f:
+            data = json.load(f)
+        if isinstance(data, dict):
+            return data.get("templates", {})
+        return {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_sources(mcp_dir: Path | None = None,
+                 sources: dict[str, dict[str, Any]] | None = None) -> None:
+    """Write sources.json atomically."""
+    mcp_dir = mcp_dir or EXTERNAL_MCP_DIR
+    path = _sources_path(mcp_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = json.dumps(
+        {"schema_version": 1, "templates": sources or {}}, indent=2
+    )
+
+    fd, tmp_path = tempfile.mkstemp(
+        dir=str(path.parent), prefix=".sources_", suffix=".tmp"
+    )
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(payload)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.rename(tmp_path, str(path))
+    except BaseException:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def register_url_source(
+    mcp_dir: Path | None,
+    template_name: str,
+    url: str,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a URL source entry for an MCP template.
+
+    When ``content`` is supplied, its sha256 is persisted. If a previous
+    sha256 exists and differs from the new one, a warning is printed
+    (and the process fails with exit 2 when ``AI_TOOLKIT_STRICT_PIN=1``).
+    """
+    if not template_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", template_name):
+        raise ValueError(f"Invalid MCP template name: {template_name!r}")
+    mcp_dir = mcp_dir or EXTERNAL_MCP_DIR
+    sources = load_sources(mcp_dir)
+    entry: dict[str, Any] = {
+        "url": url,
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    if content is not None:
+        new_hash = hashlib.sha256(content).hexdigest()
+        prev = sources.get(template_name) or {}
+        prev_hash = prev.get("sha256")
+        if prev_hash and prev_hash != new_hash:
+            msg = (
+                f"  CHECKSUM CHANGED: mcp '{template_name}' sha256 "
+                f"{prev_hash[:12]}... -> {new_hash[:12]}..."
+            )
+            print(msg)
+            if os.environ.get("AI_TOOLKIT_STRICT_PIN") == "1":
+                raise SystemExit(
+                    f"Refusing to update '{template_name}' under AI_TOOLKIT_STRICT_PIN=1."
+                )
+        entry["sha256"] = new_hash
+    sources[template_name] = entry
+    save_sources(mcp_dir, sources)
+
+
+def register_path_source(
+    mcp_dir: Path | None,
+    template_name: str,
+    path: Path,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a local-file source entry for an MCP template.
+
+    Stores the absolute origin path so subsequent ``ai-toolkit update`` runs
+    can detect drift, plus a sha256 of the injected content.
+    """
+    if not template_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", template_name):
+        raise ValueError(f"Invalid MCP template name: {template_name!r}")
+    mcp_dir = mcp_dir or EXTERNAL_MCP_DIR
+    sources = load_sources(mcp_dir)
+    existing = sources.get(template_name) or {}
+    # Never demote a URL-tracked entry to a local-path entry. update() flows
+    # call inject() with the cached file path after URL fetch, which would
+    # otherwise overwrite the URL.
+    if "url" in existing:
+        return
+    entry: dict[str, Any] = {
+        "path": str(Path(path).resolve()),
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    if content is not None:
+        entry["sha256"] = hashlib.sha256(content).hexdigest()
+    sources[template_name] = entry
+    save_sources(mcp_dir, sources)
+
+
+def unregister_source(mcp_dir: Path | None, template_name: str) -> bool:
+    """Remove a source entry. Returns True if found and removed."""
+    mcp_dir = mcp_dir or EXTERNAL_MCP_DIR
+    sources = load_sources(mcp_dir)
+    if template_name in sources:
+        del sources[template_name]
+        save_sources(mcp_dir, sources)
+        return True
+    return False
+
+
+def get_url_templates(mcp_dir: Path | None = None) -> dict[str, str]:
+    """Return {template_name: url} for all URL-sourced MCP templates."""
+    sources = load_sources(mcp_dir)
+    return {name: entry["url"] for name, entry in sources.items() if "url" in entry}

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/paths.py

@@ -26,6 +26,8 @@ LEGACY_DATA_DIR = Path.home() / ".ai-toolkit"
 # Sub-directories under TOOLKIT_DATA_DIR
 HOOKS_DIR = TOOLKIT_DATA_DIR / "hooks"
 EXTERNAL_HOOKS_DIR = HOOKS_DIR / "external"
+MCP_TEMPLATES_DIR = TOOLKIT_DATA_DIR / "mcp-templates"
+EXTERNAL_MCP_DIR = MCP_TEMPLATES_DIR / "external"
 RULES_DIR = TOOLKIT_DATA_DIR / "rules"
 SESSIONS_DIR = TOOLKIT_DATA_DIR / "sessions"
 COMPACTIONS_DIR = TOOLKIT_DATA_DIR / "compactions"

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())