@softspark/ai-toolkit 2.3.1 → 2.4.1

package/scripts/doctor.py

@@ -10,6 +10,7 @@ Checks:
   6. Planned assets
   7. Benchmark freshness
   8. Stale rules
+  9. URL hook sources
 
 Exit codes:
   0  all checks pass
@@ -27,7 +28,7 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _common import toolkit_dir
-from paths import HOOKS_DIR as _HOOKS_DIR, RULES_DIR as _RULES_DIR
+from paths import HOOKS_DIR as _HOOKS_DIR, RULES_DIR as _RULES_DIR, EXTERNAL_HOOKS_DIR as _EXTERNAL_HOOKS_DIR
 
 
 # ---------------------------------------------------------------------------
@@ -37,6 +38,7 @@ from paths import HOOKS_DIR as _HOOKS_DIR, RULES_DIR as _RULES_DIR
 CLAUDE_DIR = Path.home() / ".claude"
 HOOKS_DIR = _HOOKS_DIR
 RULES_DIR = _RULES_DIR
+EXTERNAL_HOOKS_DIR = _EXTERNAL_HOOKS_DIR
 BENCHMARK_DASHBOARD = toolkit_dir / "benchmarks" / "ecosystem-dashboard.json"
 
 VALID_EVENTS = frozenset({
@@ -465,6 +467,75 @@ def check_stale_rules(dr: DiagResult, fix_mode: bool) -> None:
         dr.ok("All rules healthy")
 
 
+# ---------------------------------------------------------------------------
+# Check 9: URL Hook Sources
+# ---------------------------------------------------------------------------
+
+def check_url_hooks(dr: DiagResult, fix_mode: bool) -> None:
+    """Check URL-sourced hook cache integrity."""
+    print()
+    print("## 9. URL Hook Sources")
+
+    sources_file = EXTERNAL_HOOKS_DIR / "sources.json"
+    if not sources_file.is_file():
+        dr.skip("No URL hook sources registered")
+        return
+
+    try:
+        with open(sources_file, encoding="utf-8") as f:
+            data = json.load(f)
+        sources = data.get("hooks", {})
+    except (json.JSONDecodeError, OSError) as exc:
+        dr.fail(f"Corrupt sources.json: {exc}")
+        return
+
+    if not sources:
+        dr.ok("No URL hook sources registered")
+        return
+
+    issues = 0
+    for name, entry in sources.items():
+        cached = EXTERNAL_HOOKS_DIR / f"{name}.json"
+        url = entry.get("url", "")
+
+        if not cached.is_file():
+            dr.warn(f"Missing cached file for '{name}' ({url})")
+            issues += 1
+            if fix_mode:
+                try:
+                    from url_fetch import fetch_url
+                    content = fetch_url(url)
+                    json.loads(content)  # validate
+                    EXTERNAL_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+                    cached.write_bytes(content)
+                    print(f"    FIXED: re-fetched {name}")
+                except Exception as exc:
+                    print(f"    Could not re-fetch: {exc}")
+            continue
+
+        # Validate cached file is valid JSON with hooks key
+        try:
+            with open(cached, encoding="utf-8") as f:
+                hook_data = json.load(f)
+            if "hooks" not in hook_data:
+                dr.warn(f"Cached file '{name}' missing 'hooks' key")
+                issues += 1
+            else:
+                dr.ok(f"{name} ({url})")
+        except json.JSONDecodeError:
+            dr.warn(f"Corrupt cached file: {cached}")
+            issues += 1
+            if fix_mode:
+                try:
+                    from url_fetch import fetch_url
+                    content = fetch_url(url)
+                    json.loads(content)
+                    cached.write_bytes(content)
+                    print(f"    FIXED: re-fetched {name}")
+                except Exception as exc:
+                    print(f"    Could not re-fetch: {exc}")
+
+
 # ---------------------------------------------------------------------------
 # Main
 # ---------------------------------------------------------------------------
@@ -486,6 +557,7 @@ def main() -> None:
     check_planned_assets(dr)
     check_benchmark_freshness(dr)
     check_stale_rules(dr, fix_mode)
+    check_url_hooks(dr, fix_mode)
 
     # Summary
     print("========================")

package/scripts/hook_sources.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""URL source registry for remotely-sourced hooks.
+
+Tracks which hooks were registered from a URL so that `ai-toolkit update`
+can re-fetch the latest version before injection.
+
+Metadata stored in ~/.softspark/ai-toolkit/hooks/external/sources.json.
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import json
+import os
+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_HOOKS_DIR
+
+_SOURCES_FILENAME = "sources.json"
+
+
+# ---------------------------------------------------------------------------
+# Load / Save
+# ---------------------------------------------------------------------------
+
+def _sources_path(hooks_dir: Path | None = None) -> Path:
+    return (hooks_dir or EXTERNAL_HOOKS_DIR) / _SOURCES_FILENAME
+
+
+def load_sources(hooks_dir: Path | None = None) -> dict[str, dict[str, Any]]:
+    """Load sources.json. Returns {} if missing or corrupt."""
+    path = _sources_path(hooks_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("hooks", {})
+        return {}
+    except (json.JSONDecodeError, OSError):
+        return {}
+
+
+def save_sources(hooks_dir: Path | None = None,
+                 sources: dict[str, dict[str, Any]] | None = None) -> None:
+    """Write sources.json atomically."""
+    hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR
+    path = _sources_path(hooks_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    payload = json.dumps({"schema_version": 1, "hooks": 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
+
+
+# ---------------------------------------------------------------------------
+# CRUD
+# ---------------------------------------------------------------------------
+
+def register_url_source(hooks_dir: Path | None, hook_name: str, url: str) -> None:
+    """Add or update a URL source entry."""
+    import re
+    if not hook_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", hook_name):
+        raise ValueError(f"Invalid hook name: {hook_name!r}")
+    hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR
+    sources = load_sources(hooks_dir)
+    sources[hook_name] = {
+        "url": url,
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    save_sources(hooks_dir, sources)
+
+
+def unregister_source(hooks_dir: Path | None, hook_name: str) -> bool:
+    """Remove a source entry. Returns True if found and removed."""
+    hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR
+    sources = load_sources(hooks_dir)
+    if hook_name in sources:
+        del sources[hook_name]
+        save_sources(hooks_dir, sources)
+        return True
+    return False
+
+
+def get_url_hooks(hooks_dir: Path | None = None) -> dict[str, str]:
+    """Return {hook_name: url} for all URL-sourced hooks."""
+    sources = load_sources(hooks_dir)
+    return {name: entry["url"] for name, entry in sources.items() if "url" in entry}

package/scripts/inject_hook_cli.py

@@ -7,15 +7,20 @@ hooks alongside ai-toolkit's hooks.  Each injected file is tagged with a
 and removal is safe.
 
 Usage:
-    inject_hook_cli.py <hooks-file.json> [target-dir]
+    inject_hook_cli.py <hooks-file-or-url> [hook-name] [target-dir]
     inject_hook_cli.py --remove <hook-source-name> [target-dir]
 
 Arguments:
-    hooks-file    Path to a JSON file with ``{"hooks": {"EventName": [...]}}``
-    target-dir    Directory containing ``.claude/settings.json`` (default: $HOME)
+    hooks-file-or-url  Path to a JSON file or HTTPS URL with
+                       ``{"hooks": {"EventName": [...]}}``
+    hook-name          Override the source name (default: filename stem or
+                       URL last segment)
+    target-dir         Directory containing ``.claude/settings.json``
+                       (default: $HOME)
 
 Flags:
     --remove      Remove all hook entries tagged with the given source name
+                  (also unregisters URL source if present)
 
 The source name is derived from the filename stem (e.g.,
 ``rag-mcp-hooks.json`` becomes ``"rag-mcp-hooks"``).  All entries are tagged
@@ -34,12 +39,19 @@ from __future__ import annotations
 
 import json
 import os
+import re
 import sys
+import urllib.parse
 from pathlib import Path
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
 # Protected source tag -- this CLI must never touch ai-toolkit's own entries.
 PROTECTED_SOURCE = "ai-toolkit"
 
+# Codex CLI supports only these 5 hook events.
+CODEX_EVENTS = {"SessionStart", "PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop"}
+
 
 # ---------------------------------------------------------------------------
 # JSON helpers (same style as merge-hooks.py)
@@ -70,6 +82,23 @@ def save_json(path: str, data: dict) -> None:
         f.write("\n")
 
 
+# ---------------------------------------------------------------------------
+# URL helpers
+# ---------------------------------------------------------------------------
+
+def _is_url(source: str) -> bool:
+    """Check if source looks like an HTTP(S) URL."""
+    return source.startswith("https://") or source.startswith("http://")
+
+
+def _name_from_url(url: str) -> str:
+    """Derive a hook source name from a URL's last path segment."""
+    parsed = urllib.parse.urlparse(url)
+    filename = parsed.path.rstrip("/").split("/")[-1]
+    stem = filename.rsplit(".", 1)[0] if "." in filename else filename
+    return re.sub(r"[^a-zA-Z0-9_-]", "", stem)
+
+
 # ---------------------------------------------------------------------------
 # Core logic
 # ---------------------------------------------------------------------------
@@ -153,27 +182,161 @@ def merge_hooks(new_hooks: dict, existing_hooks: dict, source: str) -> dict:
     return merged
 
 
+# ---------------------------------------------------------------------------
+# Codex propagation
+# ---------------------------------------------------------------------------
+
+def _codex_hooks_path(target_dir: str) -> Path:
+    """Return the global Codex hooks.json path."""
+    return Path(target_dir) / ".codex" / "hooks.json"
+
+
+def _filter_codex_events(hooks: dict) -> dict:
+    """Keep only events supported by Codex CLI."""
+    return {event: entries for event, entries in hooks.items()
+            if event in CODEX_EVENTS}
+
+
+def _inject_codex(tagged_hooks: dict, source: str, target_dir: str) -> None:
+    """Propagate hook entries to ~/.codex/hooks.json (Codex global layer).
+
+    Only events in CODEX_EVENTS are propagated. Non-Codex events are silently
+    skipped.
+    """
+    codex_hooks = _filter_codex_events(tagged_hooks)
+    if not codex_hooks:
+        return
+
+    codex_path = _codex_hooks_path(target_dir)
+    codex_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing: dict = {}
+    if codex_path.is_file():
+        try:
+            data = load_json(str(codex_path))
+            existing = data.get("hooks", {})
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+
+    merged = merge_hooks(codex_hooks, existing, source)
+    save_json(str(codex_path), {"hooks": merged})
+    events = ", ".join(sorted(codex_hooks.keys()))
+    print(f"Propagated to Codex: {codex_path} (events: {events})")
+
+
+def _remove_codex(source_name: str, target_dir: str) -> None:
+    """Remove hook entries from ~/.codex/hooks.json."""
+    codex_path = _codex_hooks_path(target_dir)
+    if not codex_path.is_file():
+        return
+
+    try:
+        data = load_json(str(codex_path))
+    except (json.JSONDecodeError, OSError):
+        return
+
+    existing = data.get("hooks", {})
+    cleaned = strip_source(existing, source_name)
+
+    if cleaned:
+        save_json(str(codex_path), {"hooks": cleaned})
+    else:
+        save_json(str(codex_path), {"hooks": {}})
+
+    print(f"Removed '{source_name}' from Codex: {codex_path}")
+
+
 # ---------------------------------------------------------------------------
 # CLI actions
 # ---------------------------------------------------------------------------
 
-def inject(hooks_file: str, target_dir: str) -> None:
-    """Inject hooks from *hooks_file* into the target settings.json.
+def _fetch_and_cache(url: str, source: str) -> str:
+    """Fetch hooks JSON from URL, cache locally, register source.
 
     Args:
-        hooks_file: Path to the external hooks JSON file.
-        target_dir: Directory containing ``.claude/settings.json``.
+        url: HTTPS URL to fetch.
+        source: Source name for caching and registry.
+
+    Returns:
+        Path to the cached hooks JSON file.
     """
-    # Derive source name from filename stem
-    source = Path(hooks_file).stem
-    if source == PROTECTED_SOURCE:
-        print(
-            f"Error: source name '{PROTECTED_SOURCE}' is reserved. "
-            "Rename your hooks file.",
-            file=sys.stderr,
-        )
+    from url_fetch import fetch_url
+    from hook_sources import register_url_source
+    from paths import EXTERNAL_HOOKS_DIR
+
+    EXTERNAL_HOOKS_DIR.mkdir(parents=True, exist_ok=True)
+
+    try:
+        data = fetch_url(url)
+    except Exception as exc:
+        print(f"Error fetching URL: {exc}", file=sys.stderr)
         sys.exit(1)
 
+    # Validate JSON before caching
+    try:
+        parsed = json.loads(data)
+    except json.JSONDecodeError as exc:
+        print(f"Error: URL returned invalid JSON: {exc}", file=sys.stderr)
+        sys.exit(2)
+
+    if "hooks" not in parsed:
+        print("Warning: no 'hooks' key found in URL response", file=sys.stderr)
+
+    cached_path = EXTERNAL_HOOKS_DIR / f"{source}.json"
+    cached_path.write_bytes(data)
+    register_url_source(None, source, url)
+
+    return str(cached_path)
+
+
+def inject(hooks_file: str, target_dir: str, source_override: str = "") -> None:
+    """Inject hooks from *hooks_file* (or URL) into the target settings.json.
+
+    Args:
+        hooks_file: Path to the external hooks JSON file, or an HTTPS URL.
+        target_dir: Directory containing ``.claude/settings.json``.
+        source_override: Explicit source name (overrides filename-derived name).
+    """
+    is_url = _is_url(hooks_file)
+
+    if is_url:
+        if hooks_file.startswith("http://"):
+            print(
+                "Error: only HTTPS URLs are supported. Use https:// for security.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        source = source_override or _name_from_url(hooks_file)
+        source = re.sub(r"[^a-zA-Z0-9_-]", "", source)
+        if not source:
+            print(
+                "Error: could not derive hook name from URL. "
+                "Provide one explicitly.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        if source == PROTECTED_SOURCE:
+            print(
+                f"Error: source name '{PROTECTED_SOURCE}' is reserved.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        hooks_file = _fetch_and_cache(hooks_file, source)
+        print(f"Fetched hooks from URL (source: '{source}')")
+    else:
+        # Derive source name from filename stem
+        source = source_override or Path(hooks_file).stem
+        if source == PROTECTED_SOURCE:
+            print(
+                f"Error: source name '{PROTECTED_SOURCE}' is reserved. "
+                "Rename your hooks file.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
     # Load the hooks file
     try:
         hooks_data = load_json(hooks_file)
@@ -214,10 +377,15 @@ def inject(hooks_file: str, target_dir: str) -> None:
     save_json(str(settings_path), settings)
     print(f"Injected hooks from '{source}' into {settings_path}")
 
+    # Propagate Codex-compatible events to ~/.codex/hooks.json
+    _inject_codex(tagged, source, target_dir)
+
 
 def remove(source_name: str, target_dir: str) -> None:
     """Remove all hook entries tagged with *source_name*.
 
+    Also unregisters the URL source if it was URL-sourced.
+
     Args:
         source_name: The ``_source`` tag to remove.
         target_dir: Directory containing ``.claude/settings.json``.
@@ -256,6 +424,24 @@ def remove(source_name: str, target_dir: str) -> None:
     save_json(str(settings_path), settings)
     print(f"Removed hooks with source '{source_name}' from {settings_path}")
 
+    # Remove from Codex global hooks
+    _remove_codex(source_name, target_dir)
+
+    # Unregister URL source if present
+    try:
+        from hook_sources import unregister_source
+        from paths import EXTERNAL_HOOKS_DIR
+
+        if unregister_source(None, source_name):
+            print(f"Unregistered URL source '{source_name}'")
+
+        # Remove cached file if exists
+        cached = EXTERNAL_HOOKS_DIR / f"{source_name}.json"
+        if cached.is_file():
+            cached.unlink()
+    except ImportError:
+        pass
+
 
 # ---------------------------------------------------------------------------
 # Argument parsing
@@ -265,16 +451,19 @@ def _parse_args(argv: list[str]) -> dict:
     """Parse CLI arguments.
 
     Returns:
-        Dict with keys: remove_mode, remove_name, source_file, target_dir.
+        Dict with keys: remove_mode, remove_name, source_file, hook_name,
+        target_dir.
     """
     result: dict = {
         "remove_mode": False,
         "remove_name": "",
         "source_file": "",
+        "hook_name": "",
         "target_dir": str(Path.home()),
     }
 
     i = 0
+    positional = 0
     while i < len(argv):
         arg = argv[i]
         if arg == "--remove":
@@ -287,10 +476,25 @@ def _parse_args(argv: list[str]) -> dict:
         elif arg.startswith("-"):
             print(f"Unknown option: {arg}", file=sys.stderr)
             sys.exit(1)
-        elif not result["source_file"] and not result["remove_mode"]:
-            result["source_file"] = arg
         else:
-            result["target_dir"] = arg
+            if positional == 0:
+                if not result["remove_mode"]:
+                    result["source_file"] = arg
+                else:
+                    result["target_dir"] = arg
+            elif positional == 1:
+                if _is_url(result["source_file"]):
+                    # Second positional after URL could be hook-name or target-dir
+                    # If it looks like a path (starts with / or ~ or .), it's target-dir
+                    if arg.startswith(("/", "~", ".")):
+                        result["target_dir"] = arg
+                    else:
+                        result["hook_name"] = arg
+                else:
+                    result["target_dir"] = arg
+            elif positional == 2:
+                result["target_dir"] = arg
+            positional += 1
         i += 1
 
     return result
@@ -309,7 +513,7 @@ def main() -> None:
     source_file = args["source_file"]
     if not source_file:
         print(
-            "Usage: inject_hook_cli.py <hooks-file.json> [target-dir]",
+            "Usage: inject_hook_cli.py <hooks-file-or-url> [hook-name] [target-dir]",
             file=sys.stderr,
         )
         print(
@@ -318,12 +522,13 @@ def main() -> None:
         )
         sys.exit(1)
 
-    source_path = Path(source_file)
-    if not source_path.is_file():
-        print(f"Hooks file not found: {source_path}", file=sys.stderr)
-        sys.exit(1)
+    if not _is_url(source_file):
+        source_path = Path(source_file)
+        if not source_path.is_file():
+            print(f"Hooks file not found: {source_path}", file=sys.stderr)
+            sys.exit(1)
 
-    inject(source_file, args["target_dir"])
+    inject(source_file, args["target_dir"], source_override=args["hook_name"])
 
 
 if __name__ == "__main__":

package/scripts/install.py

@@ -47,14 +47,17 @@ from emission import agent_count as count_agents, skill_count as count_skills
 # Step modules
 from install_steps.symlinks import install_agents, install_skills, clean_legacy_commands
 from install_steps.hooks import install_hooks
-from install_steps.markers import install_marker_files, inject_rules
+from install_steps.markers import install_marker_files, inject_rules, refresh_url_hooks
 from install_steps.ai_tools import install_ai_tools, install_local_project, run_script
 from install_steps.install_state import (
     load_state,
     record_install,
     get_installed_modules,
     get_installed_profile,
+    get_global_editors,
+    record_global_editors,
     print_status,
+    GLOBAL_CAPABLE_EDITORS,
 )
 from install_steps.detect_language import detect_languages
 from install_steps.project_registry import register_project
@@ -432,6 +435,9 @@ def install_claude_code(target_dir: Path, hooks_scripts_dir: Path,
     inject_rules(claude_dir, target_dir, rules_dir, only, skip, dry_run,
                  refresh_urls=True)
 
+    if not dry_run:
+        refresh_url_hooks(str(target_dir))
+
     _sync_mcp_templates(dry_run)
 
 
@@ -705,17 +711,31 @@ def main() -> None:
             profile = cfg["profile"]
 
         lang_modules = [m for m in (resolved_modules or []) if m.startswith("rules-")]
-        editors_arg: str = cfg["editors"]
+        local_editors_arg: str = cfg["editors"]
         install_local_project(rules_dir, dry_run, reset, lang_modules or None,
-                              editors=editors_arg,
+                              editors=local_editors_arg,
                               merged_config=merged_config)
+        installed_eds: list[str] = []  # local install doesn't track global editors
         install_strict_git_hooks(profile, local, dry_run)
     else:
         # Global install
         print_banner(target_dir, rules_dir, profile, only, skip, dry_run,
                      modules=resolved_modules)
         install_claude_code(target_dir, hooks_scripts_dir, rules_dir, only, skip, dry_run)
-        install_ai_tools(target_dir, rules_dir, only, skip, dry_run)
+
+        # Determine global editors: --editors flag > state > default (none)
+        editors_arg: str = cfg["editors"]
+        if editors_arg:
+            if editors_arg == "all":
+                global_eds = list(GLOBAL_CAPABLE_EDITORS)
+            else:
+                global_eds = [e.strip() for e in editors_arg.split(",") if e.strip()]
+        else:
+            # On update: use editors from state; on fresh install: none
+            global_eds = get_global_editors() or None
+
+        installed_eds = install_ai_tools(target_dir, rules_dir, dry_run,
+                                         editors=global_eds)
         install_persona(target_dir, persona, dry_run)
         install_strict_git_hooks(profile, local, dry_run)
 
@@ -746,6 +766,10 @@ def main() -> None:
             extends_info=extends_info,
         )
 
+        # Record global editors (only for global install, not --local)
+        if not local and installed_eds:
+            record_global_editors(installed_eds)
+
         # Register project in global registry (for `ai-toolkit update` propagation)
         # Skipped when called from update_projects.py (--skip-register) to avoid
         # concurrent writes to projects.json during parallel updates.
@@ -753,10 +777,20 @@ def main() -> None:
             extends_source = ""
             if extends_info:
                 extends_source = extends_info.get("source", "")
+            # Determine editors to record for this project
+            local_eds_for_registry: list[str] | None = None
+            if local and local_editors_arg:
+                if local_editors_arg == "all":
+                    from install_steps.ai_tools import ALL_EDITORS
+                    local_eds_for_registry = list(ALL_EDITORS)
+                else:
+                    local_eds_for_registry = [e.strip() for e in local_editors_arg.split(",") if e.strip()]
+
             is_new = register_project(
                 project_dir,
                 profile=profile or "standard",
                 extends=extends_source,
+                editors=local_eds_for_registry,
             )
             if is_new:
                 print(f"  Registered project in {TOOLKIT_DATA_DIR / 'projects.json'}")