@softspark/ai-toolkit 2.0.2 → 2.1.1

package/scripts/generate_codex_hooks.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python3
+"""Generate .codex/hooks.json for OpenAI Codex CLI.
+
+Maps compatible ai-toolkit hooks to Codex lifecycle events.
+Hook scripts are shared with Claude Code (stored in ~/.softspark/ai-toolkit/hooks/).
+
+Codex supports 5 events: SessionStart, PreToolUse, PostToolUse,
+UserPromptSubmit, Stop. PreToolUse/PostToolUse only support Bash matcher.
+
+Usage:
+  python3 scripts/generate_codex_hooks.py [target-dir]
+
+Writes .codex/hooks.json to target-dir.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+
+HOOKS_PREFIX = '"$HOME/.softspark/ai-toolkit/hooks/'
+
+# Hooks compatible with Codex, grouped by event.
+# Format: (matcher, script_name)
+CODEX_HOOKS: dict[str, list[tuple[str, str]]] = {
+    "SessionStart": [
+        ("startup|resume", "session-start.sh"),
+        ("startup|resume", "mcp-health.sh"),
+        ("startup|resume", "session-context.sh"),
+    ],
+    "PreToolUse": [
+        ("Bash", "guard-destructive.sh"),
+        ("Bash", "commit-quality.sh"),
+    ],
+    "UserPromptSubmit": [
+        ("", "user-prompt-submit.sh"),
+        ("", "track-usage.sh"),
+    ],
+    "Stop": [
+        ("", "quality-check.sh"),
+        ("", "save-session.sh"),
+    ],
+}
+
+
+def build_hooks_json() -> dict:
+    """Build the hooks.json structure for Codex."""
+    hooks: dict[str, list] = {}
+    for event, entries in CODEX_HOOKS.items():
+        hooks[event] = []
+        for matcher, script in entries:
+            entry: dict = {"hooks": [{"type": "command", "command": f"{HOOKS_PREFIX}{script}\""}]}
+            if matcher:
+                entry["matcher"] = matcher
+            hooks[event].append(entry)
+    return {"hooks": hooks}
+
+
+def generate(target_dir: Path) -> None:
+    """Write .codex/hooks.json to target_dir."""
+    codex_dir = target_dir / ".codex"
+    codex_dir.mkdir(parents=True, exist_ok=True)
+    hooks_path = codex_dir / "hooks.json"
+    data = build_hooks_json()
+    with open(hooks_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=4, ensure_ascii=False)
+        f.write("\n")
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    generate(target)
+    print(f"Generated: .codex/hooks.json ({sum(len(v) for v in CODEX_HOOKS.values())} hooks)")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_codex_rules.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Generate Codex CLI .agents/rules/ files.
+
+Codex discovers rules in .agents/rules/ at the project root.
+This generator follows the same pattern as generate_antigravity.py.
+
+Usage:
+  python3 scripts/generate_codex_rules.py [target-dir]
+
+Writes files directly to target-dir/.agents/rules/.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from dir_rules_shared import (
+    STANDARD_RULES,
+    STANDARD_SCOPE,
+    build_language_rules,
+    build_registered_rules,
+    write_rules,
+)
+
+
+def generate(target_dir: Path, *,
+             language_modules: list[str] | None = None,
+             rules_dir: Path | None = None,
+             cleanup: bool = True,
+             managed_scopes: tuple[str, ...] = (STANDARD_SCOPE,)) -> None:
+    """Write .agents/rules/ files to target_dir."""
+    rules = dict(STANDARD_RULES)
+    rules.update(build_language_rules(language_modules))
+    rules.update(build_registered_rules(rules_dir))
+    write_rules(
+        target_dir,
+        rules,
+        ".agents/rules",
+        cleanup=cleanup,
+        managed_scopes=managed_scopes,
+    )
+
+
+def main() -> None:
+    target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/generate_cursor_mdc.py

@@ -149,7 +149,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generate_roo_rules.py

@@ -33,7 +33,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generate_windsurf_rules.py

@@ -34,7 +34,8 @@ def generate(target_dir: Path, *,
 
 def main() -> None:
     target = Path(sys.argv[1]) if len(sys.argv) > 1 else Path.cwd()
-    generate(target)
+    from paths import RULES_DIR
+    generate(target, rules_dir=RULES_DIR)
 
 
 if __name__ == "__main__":

package/scripts/generator_base.py

@@ -27,6 +27,9 @@ Usage::
 from __future__ import annotations
 
 import sys
+from pathlib import Path
+
+from paths import RULES_DIR
 
 from emission import (
     count_agents_and_skills,
@@ -138,3 +141,15 @@ def render_generator(config: dict) -> None:
     if config.get("use_markers", True):
         print()
         print_toolkit_end()
+
+    # Registered custom rules from ~/.softspark/ai-toolkit/rules/
+    if RULES_DIR.is_dir():
+        for rule_file in sorted(RULES_DIR.glob("*.md")):
+            rule_name = rule_file.stem
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} START -->")
+            print("<!-- Auto-injected by ai-toolkit. Re-run to update. -->")
+            print()
+            print(rule_file.read_text(encoding="utf-8").rstrip())
+            print()
+            print(f"<!-- TOOLKIT:{rule_name} END -->")

package/scripts/install_steps/ai_tools.py

@@ -1,4 +1,4 @@
-"""Install AI tool configs (Cursor, Windsurf, Gemini, Augment) and local project setup."""
+"""Install AI tool configs (Cursor, Windsurf, Gemini, Augment, Codex) and local project setup."""
 from __future__ import annotations
 
 import shutil
@@ -6,6 +6,11 @@ import subprocess
 from pathlib import Path
 
 from _common import app_dir, inject_section, should_install, toolkit_dir
+from codex_skill_adapter import (
+    cleanup_codex_skills,
+    sync_codex_skill,
+)
+from mcp_editors import sync_project_mcp_to_editors
 from injection import (
     collapse_blank_runs as _collapse_blank_runs,
     strip_section as _strip_section,
@@ -125,7 +130,7 @@ def run_script(script_name: str, *args: str, capture: bool = False) -> str:
 # All known editor identifiers for --editors flag
 ALL_EDITORS = [
     "copilot", "cursor", "windsurf", "cline", "roo",
-    "aider", "augment", "antigravity",
+    "aider", "augment", "antigravity", "codex",
 ]
 
 # Map of project files/dirs → editor names for auto-detection
@@ -142,6 +147,9 @@ _EDITOR_MARKERS: dict[str, str] = {
     "CONVENTIONS.md": "aider",
     ".augment/rules": "augment",
     ".agent/rules": "antigravity",
+    ".agents/skills": "codex",
+    ".codex": "codex",
+    "AGENTS.md": "codex",
 }
 
 
@@ -495,6 +503,46 @@ def _create_local_settings(cwd: Path, reset: bool) -> None:
         print("  Kept: .claude/settings.local.json (already exists)")
 
 
+def _install_codex_skills(cwd: Path) -> None:
+    """Install all skills to `.agents/skills/` for Codex.
+
+    Native Codex-compatible skills are symlinked directly. Skills that rely on
+    Claude-only orchestration primitives are rendered into generated wrappers
+    with Codex-native delegation guidance.
+    """
+    skills_src = app_dir / "skills"
+    if not skills_src.is_dir():
+        return
+
+    skills_dst = cwd / ".agents" / "skills"
+    skills_dst.mkdir(parents=True, exist_ok=True)
+
+    linked = 0
+    adapted = 0
+    skipped = 0
+    for skill_dir in sorted(skills_src.iterdir()):
+        if not skill_dir.is_dir() or skill_dir.name.startswith("_"):
+            continue
+        skill_md = skill_dir / "SKILL.md"
+        if not skill_md.is_file():
+            continue
+
+        mode = sync_codex_skill(skill_dir, skills_dst)
+        if mode == "linked":
+            linked += 1
+        elif mode == "adapted":
+            adapted += 1
+        else:
+            skipped += 1
+
+    cleanup_codex_skills(skills_dst, skills_src)
+
+    print(
+        f"  Installed: {linked + adapted} skills to .agents/skills/"
+        f" ({linked} linked, {adapted} adapted, {skipped} skipped)"
+    )
+
+
 def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
                                    editors: list[str],
                                    language_modules: list[str] | None = None) -> None:
@@ -534,8 +582,12 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
             legacy_clinerules.unlink()
             print("  Migrated: .clinerules file → .clinerules/ directory")
         from generate_cline_rules import generate as gen_cline_rules
-        gen_cline_rules(cwd, language_modules=language_modules,
-                        rules_dir=rules_dir)
+        gen_cline_rules(
+            cwd,
+            language_modules=language_modules,
+            rules_dir=rules_dir,
+            managed_scopes=("standard", "lang", "custom"),
+        )
 
     if "roo" in eds:
         roo_output = run_script("generate-roo-modes.sh", capture=True)
@@ -561,4 +613,31 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         gen_antigravity(cwd, language_modules=language_modules,
                         rules_dir=rules_dir)
 
+    if "codex" in eds:
+        # AGENTS.md — marker injection (like CLAUDE.md)
+        inject_with_rules(
+            "generate_codex.py",
+            cwd / "AGENTS.md",
+            rules_dir,
+        )
+        # .agents/rules/ — directory-based rules
+        from generate_codex_rules import generate as gen_codex_rules
+        gen_codex_rules(
+            cwd,
+            language_modules=language_modules,
+            rules_dir=rules_dir,
+            managed_scopes=("standard", "lang", "custom"),
+        )
+        # .codex/hooks.json — Codex lifecycle hooks
+        from generate_codex_hooks import generate as gen_codex_hooks
+        gen_codex_hooks(cwd)
+        print("  Created: .codex/hooks.json")
+        # .agents/skills/ — filtered symlinks (Codex-compatible skills only)
+        _install_codex_skills(cwd)
+
+    synced_paths = sync_project_mcp_to_editors(cwd, sorted(eds))
+    for path in synced_paths:
+        rel = path.relative_to(cwd)
+        print(f"  Synced: {rel} (from .mcp.json)")
+
     run_script("install-git-hooks.sh", str(cwd))

package/scripts/mcp_editors.py

@@ -0,0 +1,340 @@
+#!/usr/bin/env python3
+"""Editor-specific MCP config adapters for ai-toolkit."""
+from __future__ import annotations
+
+import copy
+import json
+from pathlib import Path
+
+try:
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python 3.11+ should have tomllib
+    tomllib = None
+
+
+EDITOR_SPECS: dict[str, dict[str, str | None]] = {
+    "claude": {
+        "label": "Claude Code",
+        "project_path": ".claude/settings.local.json",
+        "global_path": ".claude/settings.json",
+        "format": "json",
+        "doc_scope": "project + global",
+    },
+    "cursor": {
+        "label": "Cursor",
+        "project_path": ".cursor/mcp.json",
+        "global_path": ".cursor/mcp.json",
+        "format": "json",
+        "doc_scope": "project + global",
+    },
+    "copilot": {
+        "label": "GitHub Copilot",
+        "project_path": ".github/mcp.json",
+        "global_path": ".copilot/mcp-config.json",
+        "format": "json",
+        "doc_scope": "project + global",
+    },
+    "gemini": {
+        "label": "Gemini CLI",
+        "project_path": ".gemini/settings.json",
+        "global_path": ".gemini/settings.json",
+        "format": "json",
+        "doc_scope": "project + global",
+    },
+    "windsurf": {
+        "label": "Windsurf",
+        "project_path": None,
+        "global_path": ".codeium/windsurf/mcp_config.json",
+        "format": "json",
+        "doc_scope": "global",
+    },
+    "cline": {
+        "label": "Cline",
+        "project_path": None,
+        "global_path": ".cline/data/settings/cline_mcp_settings.json",
+        "format": "json",
+        "doc_scope": "global",
+    },
+    "augment": {
+        "label": "Augment",
+        "project_path": None,
+        "global_path": ".augment/settings.json",
+        "format": "json",
+        "doc_scope": "global",
+    },
+    "codex": {
+        "label": "Codex CLI",
+        "project_path": None,
+        "global_path": ".codex/config.toml",
+        "format": "toml",
+        "doc_scope": "global",
+    },
+}
+
+
+PROJECT_SCOPED_EDITORS = {
+    name for name, spec in EDITOR_SPECS.items() if spec.get("project_path")
+}
+
+
+def supported_editors() -> list[str]:
+    """Return all editor ids with native MCP adapters."""
+    return sorted(EDITOR_SPECS)
+
+
+def editor_rows() -> list[dict[str, str]]:
+    """Return display metadata for `ai-toolkit mcp editors`."""
+    rows: list[dict[str, str]] = []
+    for name in supported_editors():
+        spec = EDITOR_SPECS[name]
+        rows.append({
+            "name": name,
+            "label": str(spec["label"]),
+            "scope": str(spec["doc_scope"]),
+            "project_path": str(spec.get("project_path") or "—"),
+            "global_path": str(spec.get("global_path") or "—"),
+            "format": str(spec["format"]),
+        })
+    return rows
+
+
+def resolve_editor_path(
+    editor: str,
+    scope: str,
+    *,
+    project_dir: Path | None = None,
+    home: Path | None = None,
+) -> Path:
+    """Resolve the native config path for an editor + scope."""
+    if editor not in EDITOR_SPECS:
+        raise ValueError(f"Unsupported editor: {editor}")
+    spec = EDITOR_SPECS[editor]
+    if scope == "project":
+        rel = spec.get("project_path")
+        if not rel:
+            raise ValueError(f"Editor '{editor}' does not support project-scoped MCP config")
+        base = project_dir or Path.cwd()
+        return base / str(rel)
+    if scope == "global":
+        rel = spec.get("global_path")
+        if not rel:
+            raise ValueError(f"Editor '{editor}' does not support global MCP config")
+        return (home or Path.home()) / str(rel)
+    raise ValueError(f"Unsupported scope: {scope}")
+
+
+def load_project_mcp_servers(project_dir: Path) -> dict:
+    """Load `.mcp.json` servers from a project directory."""
+    config_path = project_dir / ".mcp.json"
+    if not config_path.is_file():
+        raise FileNotFoundError(f"{config_path} not found")
+    with open(config_path, encoding="utf-8") as f:
+        data = json.load(f)
+    servers = data.get("mcpServers", {})
+    if not isinstance(servers, dict):
+        raise ValueError(f"{config_path} has invalid mcpServers data")
+    return servers
+
+
+def install_servers(
+    editors: list[str],
+    servers: dict,
+    *,
+    scope: str,
+    project_dir: Path | None = None,
+    home: Path | None = None,
+) -> list[Path]:
+    """Merge servers into native editor config files."""
+    updated: list[Path] = []
+    for editor in editors:
+        path = resolve_editor_path(
+            editor,
+            scope,
+            project_dir=project_dir,
+            home=home,
+        )
+        if EDITOR_SPECS[editor]["format"] == "toml":
+            _merge_toml_servers(path, servers)
+        else:
+            _merge_json_servers(path, editor, servers)
+        updated.append(path)
+    return updated
+
+
+def remove_servers(
+    editors: list[str],
+    server_names: list[str],
+    *,
+    scope: str,
+    project_dir: Path | None = None,
+    home: Path | None = None,
+) -> list[Path]:
+    """Remove servers from native editor config files."""
+    updated: list[Path] = []
+    for editor in editors:
+        path = resolve_editor_path(
+            editor,
+            scope,
+            project_dir=project_dir,
+            home=home,
+        )
+        if EDITOR_SPECS[editor]["format"] == "toml":
+            _remove_toml_servers(path, server_names)
+        else:
+            _remove_json_servers(path, server_names)
+        updated.append(path)
+    return updated
+
+
+def sync_project_mcp_to_editors(project_dir: Path, editors: list[str]) -> list[Path]:
+    """Mirror `.mcp.json` into project-scoped editor configs.
+
+    Claude project settings are always synced when `.mcp.json` exists.
+    """
+    config_path = project_dir / ".mcp.json"
+    if not config_path.is_file():
+        return []
+
+    servers = load_project_mcp_servers(project_dir)
+    selected = {"claude"}
+    selected.update(e for e in editors if e in PROJECT_SCOPED_EDITORS)
+    return install_servers(
+        sorted(selected),
+        servers,
+        scope="project",
+        project_dir=project_dir,
+    )
+
+
+def _load_json_file(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} must contain a JSON object")
+    return data
+
+
+def _write_json_file(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+
+
+def _normalize_server(editor: str, server: dict) -> dict:
+    data = copy.deepcopy(server)
+    if editor == "copilot":
+        if "url" in data:
+            data.setdefault("type", "http")
+        elif "command" in data:
+            data.setdefault("type", "local")
+        data.setdefault("tools", ["*"])
+    return data
+
+
+def _merge_json_servers(path: Path, editor: str, servers: dict) -> None:
+    data = _load_json_file(path)
+    bucket = data.setdefault("mcpServers", {})
+    if not isinstance(bucket, dict):
+        raise ValueError(f"{path} has invalid mcpServers data")
+    for key, value in servers.items():
+        bucket[key] = _normalize_server(editor, value)
+    _write_json_file(path, data)
+
+
+def _remove_json_servers(path: Path, server_names: list[str]) -> None:
+    if not path.is_file():
+        return
+    data = _load_json_file(path)
+    bucket = data.get("mcpServers", {})
+    if not isinstance(bucket, dict):
+        raise ValueError(f"{path} has invalid mcpServers data")
+    for name in server_names:
+        bucket.pop(name, None)
+    data["mcpServers"] = bucket
+    _write_json_file(path, data)
+
+
+def _load_toml_file(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    if tomllib is None:  # pragma: no cover
+        raise RuntimeError("tomllib is unavailable")
+    return tomllib.loads(path.read_text(encoding="utf-8"))
+
+
+def _merge_toml_servers(path: Path, servers: dict) -> None:
+    data = _load_toml_file(path)
+    bucket = data.setdefault("mcp_servers", {})
+    if not isinstance(bucket, dict):
+        raise ValueError(f"{path} has invalid mcp_servers data")
+    for key, value in servers.items():
+        bucket[key] = _normalize_toml_server(value)
+    _write_toml_file(path, data)
+
+
+def _remove_toml_servers(path: Path, server_names: list[str]) -> None:
+    if not path.is_file():
+        return
+    data = _load_toml_file(path)
+    bucket = data.get("mcp_servers", {})
+    if not isinstance(bucket, dict):
+        raise ValueError(f"{path} has invalid mcp_servers data")
+    for name in server_names:
+        bucket.pop(name, None)
+    data["mcp_servers"] = bucket
+    _write_toml_file(path, data)
+
+
+def _normalize_toml_server(server: dict) -> dict:
+    data: dict = {}
+    for key, value in copy.deepcopy(server).items():
+        if value in (None, {}, []):
+            continue
+        data[key] = value
+    return data
+
+
+def _format_toml_value(value) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return str(value)
+    if isinstance(value, str):
+        return json.dumps(value)
+    if isinstance(value, list):
+        return "[" + ", ".join(_format_toml_value(v) for v in value) + "]"
+    raise TypeError(f"Unsupported TOML value: {value!r}")
+
+
+def _format_toml_key(key: str) -> str:
+    if key.replace("-", "").replace("_", "").isalnum():
+        return key
+    return json.dumps(key)
+
+
+def _render_toml_table(prefix: str, data: dict, lines: list[str]) -> None:
+    scalars = [(k, v) for k, v in data.items() if not isinstance(v, dict)]
+    tables = [(k, v) for k, v in data.items() if isinstance(v, dict) and v]
+
+    if prefix:
+        lines.append(f"[{prefix}]")
+    for key, value in scalars:
+        lines.append(f"{_format_toml_key(key)} = {_format_toml_value(value)}")
+
+    for key, value in tables:
+        if lines and lines[-1] != "":
+            lines.append("")
+        child_key = _format_toml_key(key)
+        child_prefix = f"{prefix}.{child_key}" if prefix else child_key
+        _render_toml_table(child_prefix, value, lines)
+
+
+def _write_toml_file(path: Path, data: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines: list[str] = []
+    _render_toml_table("", data, lines)
+    text = "\n".join(lines).rstrip() + "\n"
+    path.write_text(text, encoding="utf-8")