@softspark/ai-toolkit 2.0.2 → 2.1.0

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

package/scripts/mcp_manager.py

@@ -1,10 +1,12 @@
 #!/usr/bin/env python3
-"""MCP template manager -- add, remove, list, and inspect MCP server configs.
+"""MCP template manager -- add, remove, inspect, and install MCP configs.
 
 Usage:
   mcp_manager.py list                           List available templates
+  mcp_manager.py editors                        List native editor MCP adapters
   mcp_manager.py show <name>                    Show template details
   mcp_manager.py add <name> [names..] [--target <path>]  Add to .mcp.json
+  mcp_manager.py install --editor <name[,..]> [--scope project|global] [--target <path>] [name..]
   mcp_manager.py remove <name>                  Remove from .mcp.json
 """
 from __future__ import annotations
@@ -13,6 +15,14 @@ import json
 import sys
 from pathlib import Path
 
+from mcp_editors import (
+    editor_rows,
+    install_servers,
+    load_project_mcp_servers,
+    remove_servers,
+    supported_editors,
+)
+
 TOOLKIT_DIR = Path(__file__).resolve().parent.parent
 TEMPLATES_DIR = TOOLKIT_DIR / "app" / "mcp-templates"
 MCP_CONFIG_NAME = ".mcp.json"
@@ -85,6 +95,20 @@ def cmd_list() -> None:
     print(f"Add with: ai-toolkit mcp add <name>")
 
 
+def cmd_editors() -> None:
+    """List editors with native MCP config adapters."""
+    rows = editor_rows()
+    print(f"{'Editor':<12} {'Scope':<18} {'Project Path':<28} {'Global Path'}")
+    print("-" * 110)
+    for row in rows:
+        print(
+            f"{row['name']:<12} {row['scope']:<18} "
+            f"{row['project_path']:<28} {row['global_path']}"
+        )
+    print()
+    print(f"{len(rows)} editors supported")
+
+
 def cmd_show(name: str) -> None:
     """Show details of a specific template."""
     data = load_template(name)
@@ -132,14 +156,84 @@ def cmd_add(names: list[str], target_dir: Path) -> None:
     print(f"Added: {', '.join(added)}")
 
 
-def cmd_remove(name: str, target_dir: Path) -> None:
+def cmd_install(
+    names: list[str],
+    editors: list[str],
+    *,
+    target_dir: Path | None,
+    scope: str | None,
+) -> None:
+    """Install MCP templates into native editor config files."""
+    if not editors:
+        print("Error: install requires --editor <name[,..]>", file=sys.stderr)
+        print(
+            f"Supported editors: {', '.join(supported_editors())}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    eff_scope = scope or ("project" if target_dir is not None or not names else "global")
+    if eff_scope == "project":
+        project_dir = target_dir or Path.cwd()
+        if names:
+            cmd_add(names, project_dir)
+            servers = {}
+            for name in names:
+                servers.update(load_template(name).get("mcpServers", {}))
+        else:
+            servers = load_project_mcp_servers(project_dir)
+        updated = install_servers(
+            editors,
+            servers,
+            scope="project",
+            project_dir=project_dir,
+        )
+    else:
+        if not names:
+            print(
+                "Error: global install requires at least one template name.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        servers = {}
+        for name in names:
+            servers.update(load_template(name).get("mcpServers", {}))
+        updated = install_servers(editors, servers, scope="global")
+
+    for path in updated:
+        print(f"Updated: {path}")
+
+
+def cmd_remove(name: str, target_dir: Path | None, *, editors: list[str], scope: str | None) -> None:
     """Remove an MCP server from .mcp.json."""
-    config_path = target_dir / MCP_CONFIG_NAME
+    if editors:
+        eff_scope = scope or ("project" if target_dir else "global")
+        if eff_scope == "project":
+            project_dir = target_dir or Path.cwd()
+            config_path = project_dir / MCP_CONFIG_NAME
+            if config_path.is_file():
+                config = load_mcp_config(project_dir)
+                config.get("mcpServers", {}).pop(name, None)
+                write_mcp_config(project_dir, config)
+            updated = remove_servers(
+                editors,
+                [name],
+                scope="project",
+                project_dir=project_dir,
+            )
+        else:
+            updated = remove_servers(editors, [name], scope="global")
+        for path in updated:
+            print(f"Updated: {path}")
+        print(f"Removed: {name}")
+        return
+
+    config_path = (target_dir or Path.cwd()) / MCP_CONFIG_NAME
     if not config_path.is_file():
         print(f"Error: {config_path} not found.", file=sys.stderr)
         sys.exit(1)
 
-    config = load_mcp_config(target_dir)
+    config = load_mcp_config(target_dir or Path.cwd())
     servers = config.get("mcpServers", {})
 
     if name not in servers:
@@ -148,7 +242,7 @@ def cmd_remove(name: str, target_dir: Path) -> None:
         sys.exit(1)
 
     del servers[name]
-    write_mcp_config(target_dir, config)
+    write_mcp_config(target_dir or Path.cwd(), config)
     print(f"Removed: {name}")
 
 
@@ -156,19 +250,27 @@ def cmd_remove(name: str, target_dir: Path) -> None:
 # Argument parsing
 # ---------------------------------------------------------------------------
 
-def parse_target(args: list[str]) -> tuple[list[str], Path]:
-    """Extract --target <path> from args, return (remaining_args, target_dir)."""
-    target_dir = Path.cwd()
+def parse_options(args: list[str]) -> tuple[list[str], Path | None, list[str], str | None]:
+    """Extract common MCP CLI options."""
+    target_dir: Path | None = None
+    editors: list[str] = []
+    scope: str | None = None
     remaining = []
     i = 0
     while i < len(args):
         if args[i] == "--target" and i + 1 < len(args):
             target_dir = Path(args[i + 1]).resolve()
             i += 2
+        elif args[i] == "--editor" and i + 1 < len(args):
+            editors = [e.strip() for e in args[i + 1].split(",") if e.strip()]
+            i += 2
+        elif args[i] == "--scope" and i + 1 < len(args):
+            scope = args[i + 1]
+            i += 2
         else:
             remaining.append(args[i])
             i += 1
-    return remaining, target_dir
+    return remaining, target_dir, editors, scope
 
 
 def main() -> None:
@@ -182,20 +284,30 @@ def main() -> None:
 
     if subcmd == "list":
         cmd_list()
+    elif subcmd == "editors":
+        cmd_editors()
     elif subcmd == "show":
         if not rest:
             print("Usage: ai-toolkit mcp show <name>", file=sys.stderr)
             sys.exit(1)
         cmd_show(rest[0])
     elif subcmd == "add":
-        names, target_dir = parse_target(rest)
-        cmd_add(names, target_dir)
+        names, target_dir, _editors, _scope = parse_options(rest)
+        cmd_add(names, target_dir or Path.cwd())
+    elif subcmd == "install":
+        names, target_dir, editors, scope = parse_options(rest)
+        cmd_install(names, editors, target_dir=target_dir, scope=scope)
     elif subcmd == "remove":
-        names, target_dir = parse_target(rest)
+        names, target_dir, editors, scope = parse_options(rest)
         if not names:
             print("Usage: ai-toolkit mcp remove <name>", file=sys.stderr)
             sys.exit(1)
-        cmd_remove(names[0], target_dir)
+        cmd_remove(
+            names[0],
+            target_dir if editors else (target_dir or Path.cwd()),
+            editors=editors,
+            scope=scope,
+        )
     else:
         print(f"Unknown subcommand: {subcmd}", file=sys.stderr)
         print(__doc__)