@softspark/ai-toolkit 2.3.1 → 2.4.1

package/scripts/install_steps/ai_tools.py

@@ -19,50 +19,113 @@ from injection import (
 
 
 def install_ai_tools(target_dir: Path, rules_dir: Path,
-                     only: str, skip: str, dry_run: bool) -> None:
-    """Install Cursor, Windsurf, Gemini global configs."""
+                     dry_run: bool,
+                     editors: list[str] | None = None) -> list[str]:
+    """Install global editor configs.
+
+    Args:
+        editors: Explicit list of editors to install globally. If None,
+                 uses DEFAULT_GLOBAL_EDITORS (empty = Claude only).
+
+    Returns:
+        List of editors that were actually installed (for state tracking).
+    """
+    from install_steps.install_state import DEFAULT_GLOBAL_EDITORS, GLOBAL_CAPABLE_EDITORS
+
+    if editors is None:
+        eds = set(DEFAULT_GLOBAL_EDITORS)
+    else:
+        eds = set(editors)
+
+    # Filter to only globally-capable editors
+    eds = eds & set(GLOBAL_CAPABLE_EDITORS)
+
+    if not eds:
+        return []
+
     print()
     print("## Other AI Tools (global)")
     print()
 
-    if should_install("cursor", only, skip):
+    installed: list[str] = []
+
+    # Editors are opt-in via --editors, not filtered by --only/--skip (those
+    # control Claude components like agents, hooks, rules).  If an editor is
+    # in the requested set, install it unconditionally.
+
+    if "cursor" in eds:
         cursor_file = target_dir / ".cursor" / "rules"
         if dry_run:
             print("  Would inject: ~/.cursor/rules")
         else:
             inject_with_rules("generate-cursor-rules.sh", cursor_file, rules_dir)
-    else:
-        print("  Skipped: cursor")
+        installed.append("cursor")
 
-    if should_install("windsurf", only, skip):
+    if "windsurf" in eds:
         windsurf_file = target_dir / ".codeium" / "windsurf" / "memories" / "global_rules.md"
         if dry_run:
             print("  Would inject: ~/.codeium/windsurf/memories/global_rules.md")
         else:
             inject_with_rules("generate-windsurf.sh", windsurf_file, rules_dir)
-    else:
-        print("  Skipped: windsurf")
+        installed.append("windsurf")
 
-    if should_install("gemini", only, skip):
+    if "gemini" in eds:
         gemini_file = target_dir / ".gemini" / "GEMINI.md"
         if dry_run:
             print("  Would inject: ~/.gemini/GEMINI.md")
         else:
             inject_with_rules("generate-gemini.sh", gemini_file, rules_dir)
-    else:
-        print("  Skipped: gemini")
+        installed.append("gemini")
 
-    if should_install("augment", only, skip):
+    if "augment" in eds:
         augment_file = target_dir / ".augment" / "rules" / "ai-toolkit.md"
         if dry_run:
             print("  Would inject: ~/.augment/rules/ai-toolkit.md")
         else:
             inject_with_rules("generate-augment.sh", augment_file, rules_dir)
-    else:
-        print("  Skipped: augment")
+        installed.append("augment")
+
+    if "codex" in eds:
+        if dry_run:
+            print("  Would inject: ~/AGENTS.md, ~/.agents/, ~/.codex/hooks.json")
+        else:
+            _install_codex_global(target_dir, rules_dir)
+        installed.append("codex")
 
     print()
-    print("  Note: Copilot, Cline, Roo Code, and Aider have no global config -- use 'ai-toolkit install --local' per project")
+    print(f"  Available: {', '.join(GLOBAL_CAPABLE_EDITORS)}")
+    print("  Note: Copilot, Cline, Roo Code, Aider, Antigravity have no global config -- use 'ai-toolkit install --local' per project")
+
+    return installed
+
+
+def _install_codex_global(target_dir: Path, rules_dir: Path) -> None:
+    """Install Codex at the global level (~/ layer).
+
+    Creates:
+      - ~/AGENTS.md (marker injection with rules)
+      - ~/.agents/rules/*.md (directory-based rules)
+      - ~/.agents/skills/* (skill symlinks)
+      - ~/.codex/hooks.json (lifecycle hooks)
+    """
+    inject_with_rules(
+        "generate_codex.py",
+        target_dir / "AGENTS.md",
+        rules_dir,
+    )
+
+    from generate_codex_rules import generate as gen_codex_rules
+    gen_codex_rules(
+        target_dir,
+        rules_dir=rules_dir,
+        managed_scopes=("standard", "custom"),
+    )
+
+    from generate_codex_hooks import generate as gen_codex_hooks
+    gen_codex_hooks(target_dir)
+    print("  Created: ~/.codex/hooks.json")
+
+    _install_codex_skills(target_dir)
 
 
 def inject_with_rules(

package/scripts/install_steps/install_state.py

@@ -85,6 +85,27 @@ def remove_mcp_template(name: str) -> None:
     save_state(state)
 
 
+# Default global install: Claude only — no other editors unless --editors is used
+DEFAULT_GLOBAL_EDITORS: list[str] = []
+
+# All editors that support global install (opt-in via --editors)
+GLOBAL_CAPABLE_EDITORS = ["augment", "codex", "cursor", "gemini", "windsurf"]
+
+
+def get_global_editors() -> list[str]:
+    """Return list of globally installed editor names from state."""
+    state = load_state()
+    editors = state.get("global_editors", [])
+    return editors if isinstance(editors, list) else []
+
+
+def record_global_editors(editors: list[str]) -> None:
+    """Record which editors are installed globally in state.json."""
+    state = load_state()
+    state["global_editors"] = sorted(set(editors))
+    save_state(state)
+
+
 def _now_iso() -> str:
     """Return current UTC time in ISO 8601 format."""
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -163,6 +184,10 @@ def print_status() -> None:
         langs = [m.replace("rules-", "") for m in detected]
         print(f"  Detected:   {', '.join(langs)}")
 
+    editors = state.get("global_editors", [])
+    if editors:
+        print(f"  Editors:    {', '.join(editors)}")
+
     mcp = state.get("mcp_templates", [])
     if mcp:
         print(f"  MCP:        {', '.join(mcp)}")

package/scripts/install_steps/markers.py

@@ -99,6 +99,48 @@ def _refresh_url_rules(rules_dir: Path) -> None:
                 print(f"           No cached version — rule will be skipped.")
 
 
+def refresh_url_hooks(target_dir: str | None = None) -> None:
+    """Re-fetch all URL-sourced hooks and re-inject them.
+
+    Called during ``ai-toolkit update`` to keep URL-sourced hooks current.
+    On fetch failure, warns and keeps the cached version.
+    """
+    from hook_sources import get_url_hooks, register_url_source
+    from paths import EXTERNAL_HOOKS_DIR
+    from url_fetch import fetch_url
+    import json
+
+    url_hooks = get_url_hooks()
+    if not url_hooks:
+        return
+
+    print("  Refreshing URL-sourced hooks...")
+    target = target_dir or str(Path.home())
+
+    for hook_name, url in url_hooks.items():
+        cached_file = EXTERNAL_HOOKS_DIR / f"{hook_name}.json"
+        try:
+            data = fetch_url(url)
+            # Validate JSON before caching
+            json.loads(data)
+            cached_file.write_bytes(data)
+            register_url_source(None, hook_name, url)
+            print(f"  Refreshed: {hook_name} (from {url})")
+        except Exception as exc:
+            if cached_file.is_file():
+                print(f"  Warning: could not refresh '{hook_name}' from {url}: {exc}")
+                print(f"           Using cached version.")
+            else:
+                print(f"  Warning: could not fetch '{hook_name}' from {url}: {exc}")
+                print(f"           No cached version — hook will be skipped.")
+                continue
+
+        # Re-inject from cached file
+        if cached_file.is_file():
+            from inject_hook_cli import inject
+            inject(str(cached_file), target, source_override=hook_name)
+
+
 def _inject_rules_dry_run(rules_dir: Path) -> None:
     rules_src = app_dir / "rules"
     rule_names = " ".join(

package/scripts/install_steps/project_registry.py

@@ -130,11 +130,17 @@ def register_project(
     project_path: str | Path,
     profile: str = "",
     extends: str = "",
+    editors: list[str] | None = None,
 ) -> bool:
     """Register a project directory. Returns True if newly added, False if updated.
 
     Idempotent — updates existing entry if path already registered.
     Uses file lock to prevent concurrent read-modify-write races.
+
+    Args:
+        editors: List of editors installed locally (e.g. ["codex", "cursor"]).
+                 If provided, replaces the stored editors list. If None, keeps
+                 existing editors (or empty for new projects).
     """
     project_path = str(Path(project_path).resolve())
 
@@ -153,6 +159,8 @@ def register_project(
                 elif "extends" in p and not extends:
                     # Clear extends if project no longer uses it
                     pass
+                if editors is not None:
+                    p["editors"] = sorted(set(editors))
                 save_registry(projects)
                 return False
 
@@ -163,6 +171,7 @@ def register_project(
             "last_updated": now,
             "profile": profile or "standard",
             "extends": extends or "",
+            "editors": sorted(set(editors)) if editors else [],
         })
         save_registry(projects)
         return True

package/scripts/paths.py

@@ -25,6 +25,7 @@ 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"
 RULES_DIR = TOOLKIT_DATA_DIR / "rules"
 SESSIONS_DIR = TOOLKIT_DATA_DIR / "sessions"
 COMPACTIONS_DIR = TOOLKIT_DATA_DIR / "compactions"

package/scripts/propagate_global.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Propagate rules, hooks, and MCP configs to all globally installed editors.
+
+Called automatically after inject-rule, inject-hook, add-rule, remove-rule,
+and mcp add to keep global editor configs in sync.
+
+Usage:
+    propagate_global.py [--rules] [--hooks] [--mcp]
+
+Flags (can combine):
+    --rules   Re-inject registered rules into global editor configs
+    --hooks   Re-inject external hooks into Codex global hooks.json
+    --mcp     Sync MCP templates to global editor MCP configs
+
+With no flags, propagates rules (the most common case).
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+
+def propagate_rules() -> None:
+    """Re-inject registered rules into all global editors from state."""
+    from paths import RULES_DIR
+    from install_steps.install_state import get_global_editors
+
+    editors = get_global_editors()
+    if not editors:
+        return
+
+    target_dir = Path.home()
+    rules_dir = RULES_DIR
+
+    from install_steps.ai_tools import install_ai_tools
+    print("Propagating rules to global editors...")
+    install_ai_tools(target_dir, rules_dir, dry_run=False, editors=editors)
+
+
+def propagate_hooks() -> None:
+    """Re-inject URL-sourced hooks into Codex global hooks.json."""
+    from install_steps.install_state import get_global_editors
+
+    editors = get_global_editors()
+    if "codex" not in editors:
+        return
+
+    # Hooks are already propagated to Codex by inject_hook_cli.py
+    # This is a no-op — kept for completeness and future editors with hooks
+    pass
+
+
+def propagate_mcp() -> None:
+    """Sync globally tracked MCP templates to global editor MCP configs."""
+    from install_steps.install_state import get_global_editors, get_mcp_templates
+
+    editors = get_global_editors()
+    templates = get_mcp_templates()
+    if not editors or not templates:
+        return
+
+    # MCP editor sync is handled by mcp_manager.py install --editor --scope global
+    import subprocess
+    scripts_dir = Path(__file__).resolve().parent
+
+    for editor in editors:
+        try:
+            subprocess.run(
+                ["python3", str(scripts_dir / "mcp_manager.py"),
+                 "install", "--editor", editor, "--scope", "global"] + templates,
+                capture_output=True, text=True, timeout=30,
+            )
+            print(f"  MCP synced to {editor} (global)")
+        except Exception as exc:
+            print(f"  Warning: MCP sync to {editor} failed: {exc}")
+
+
+def main() -> None:
+    args = set(sys.argv[1:])
+
+    if not args or "--rules" in args:
+        propagate_rules()
+    if "--hooks" in args:
+        propagate_hooks()
+    if "--mcp" in args:
+        propagate_mcp()
+
+
+if __name__ == "__main__":
+    main()

package/scripts/rule_sources.py

@@ -12,21 +12,17 @@ from __future__ import annotations
 
 import json
 import os
-import ssl
 import sys
 import tempfile
-import urllib.request
-import urllib.error
 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 RULES_DIR
+from url_fetch import fetch_url as fetch_url  # noqa: F811 — re-export
 
 _SOURCES_FILENAME = "sources.json"
-_FETCH_TIMEOUT = 30  # seconds
-_FETCH_MAX_BYTES = 10 * 1024 * 1024  # 10MB
 
 
 # ---------------------------------------------------------------------------
@@ -85,6 +81,9 @@ def save_sources(rules_dir: Path | None = None,
 
 def register_url_source(rules_dir: Path | None, rule_name: str, url: str) -> None:
     """Add or update a URL source entry."""
+    import re
+    if not rule_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", rule_name):
+        raise ValueError(f"Invalid rule name: {rule_name!r}")
     rules_dir = rules_dir or RULES_DIR
     sources = load_sources(rules_dir)
     sources[rule_name] = {
@@ -112,27 +111,5 @@ def get_url_rules(rules_dir: Path | None = None) -> dict[str, str]:
 
 
 # ---------------------------------------------------------------------------
-# Fetch
+# Fetch — delegated to shared url_fetch module (re-exported above)
 # ---------------------------------------------------------------------------
-
-def fetch_url(url: str) -> bytes:
-    """Fetch URL content. HTTPS only, 30s timeout, 10MB cap.
-
-    Raises:
-        ValueError: if URL is not HTTPS
-        urllib.error.URLError: on network failure
-    """
-    if not url.startswith("https://"):
-        raise ValueError(
-            f"Only HTTPS URLs are supported (got: {url.split('://')[0]}://)"
-        )
-
-    ctx = ssl.create_default_context()
-    with urllib.request.urlopen(url, timeout=_FETCH_TIMEOUT, context=ctx) as resp:
-        data = resp.read(_FETCH_MAX_BYTES)
-
-    # Basic binary detection — reject if null bytes present
-    if b"\x00" in data:
-        raise ValueError(f"URL returned binary content, expected markdown: {url}")
-
-    return data

package/scripts/update_projects.py

@@ -25,9 +25,15 @@ def _update_project(project: dict[str, Any], install_script: str, extra_args: li
     project_path = project["path"]
     start = time.monotonic()
 
+    # Pass saved editors from registry so update re-installs the same editors
+    cmd_args = ["python3", install_script, "--local"] + extra_args
+    project_editors = project.get("editors", [])
+    if project_editors:
+        cmd_args.extend(["--editors", ",".join(project_editors)])
+
     try:
         proc = subprocess.run(
-            ["python3", install_script, "--local"] + extra_args,
+            cmd_args,
             cwd=project_path,
             capture_output=True,
             text=True,

package/scripts/url_fetch.py

@@ -0,0 +1,50 @@
+#!/usr/bin/env python3
+"""Shared URL fetch utility for ai-toolkit.
+
+HTTPS-only, timeout-capped, size-limited fetcher used by both
+rule_sources and hook_sources.
+
+Stdlib-only — no external dependencies.
+"""
+from __future__ import annotations
+
+import ssl
+import urllib.error
+import urllib.request
+
+_FETCH_TIMEOUT = 30  # seconds
+_FETCH_MAX_BYTES = 10 * 1024 * 1024  # 10MB
+
+
+def fetch_url(url: str) -> bytes:
+    """Fetch URL content. HTTPS only, 30s timeout, 10MB cap.
+
+    Args:
+        url: The HTTPS URL to fetch.
+
+    Returns:
+        Raw bytes of the response body.
+
+    Raises:
+        ValueError: if URL is not HTTPS or returns binary content.
+        urllib.error.URLError: on network failure.
+    """
+    if not url.startswith("https://"):
+        raise ValueError(
+            f"Only HTTPS URLs are supported (got: {url.split('://')[0]}://)"
+        )
+
+    ctx = ssl.create_default_context()
+    with urllib.request.urlopen(url, timeout=_FETCH_TIMEOUT, context=ctx) as resp:
+        data = resp.read(_FETCH_MAX_BYTES)
+        # Detect truncation — if there's more data, the response exceeds the limit
+        if resp.read(1):
+            raise ValueError(
+                f"Response exceeds {_FETCH_MAX_BYTES} byte limit: {url}"
+            )
+
+    # Basic binary detection — reject if null bytes present
+    if b"\x00" in data:
+        raise ValueError(f"URL returned binary content: {url}")
+
+    return data