cycode 3.15.3.dev8__py3-none-any.whl → 3.15.4.dev2__py3-none-any.whl

cycode/cli/apps/ai_guardrails/ides/codex.py

@@ -0,0 +1,310 @@
+"""Codex CLI IDE integration for AI guardrails."""
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import ClassVar, Optional
+
+import tomli_w
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:  # pragma: no cover - py<3.11 fallback
+    import tomli as tomllib
+
+from cycode.cli.apps.ai_guardrails.consts import CYCODE_SCAN_PROMPT_COMMAND, CYCODE_SESSION_START_COMMAND
+from cycode.cli.apps.ai_guardrails.ides._plugin_utils import load_plugin_json, walk_enabled_plugins
+from cycode.cli.apps.ai_guardrails.ides.base import IDE, DecisionAction, HookDecision
+from cycode.cli.apps.ai_guardrails.scan.payload import AIHookPayload
+from cycode.cli.apps.ai_guardrails.scan.types import AiHookEventType
+from cycode.cli.utils.jwt_utils import decode_jwt_unverified
+from cycode.logger import get_logger
+
+logger = get_logger('AI Guardrails Codex')
+
+_CONFIG_DIR_NAME = '.codex'
+_HOOKS_FILE_NAME = 'hooks.json'
+_CONFIG_TOML_NAME = 'config.toml'
+_AUTH_JSON_NAME = 'auth.json'
+_CODEX_HOME_ENV_VAR = 'CODEX_HOME'
+
+_HOOK_EVENTS = ('UserPromptSubmit', 'PreToolUse:mcp')
+_CODEX_EVENT_NAMES = frozenset(e.split(':', 1)[0] for e in _HOOK_EVENTS)
+
+_SCAN_COMMAND = f'{CYCODE_SCAN_PROMPT_COMMAND} --ide codex'
+_SESSION_START_COMMAND = f'{CYCODE_SESSION_START_COMMAND} --ide codex'
+
+
+def _codex_home() -> Path:
+    """Resolve Codex's user-scope home directory.
+
+    Honors ``$CODEX_HOME`` per Codex's documented override; falls back to
+    ``~/.codex``.
+    """
+    override = os.environ.get(_CODEX_HOME_ENV_VAR)
+    if override:
+        return Path(override)
+    return Path.home() / _CONFIG_DIR_NAME
+
+
+def _codex_config_toml_path(scope: str, repo_path: Optional[Path] = None) -> Path:
+    """Return the Codex ``config.toml`` path for the given scope."""
+    if scope == 'repo' and repo_path:
+        return repo_path / _CONFIG_DIR_NAME / _CONFIG_TOML_NAME
+    return _codex_home() / _CONFIG_TOML_NAME
+
+
+def _load_codex_config(config_path: Optional[Path] = None) -> Optional[dict]:
+    """Load and parse Codex's ``config.toml``. Returns None on missing/invalid."""
+    path = config_path or (_codex_home() / _CONFIG_TOML_NAME)
+    if not path.exists():
+        logger.debug('Codex config file not found, %s', {'path': str(path)})
+        return None
+    try:
+        with path.open('rb') as f:
+            return tomllib.load(f)
+    except Exception as e:
+        logger.debug('Failed to load Codex config file, %s', {'path': str(path)}, exc_info=e)
+        return None
+
+
+def _email_from_auth(auth_path: Optional[Path] = None) -> Optional[str]:
+    """Best-effort extraction of the signed-in Codex user's email.
+
+    Reads ``~/.codex/auth.json`` and decodes the JWT in ``tokens.id_token``
+    to pull the ``email`` claim. Returns None if auth.json is missing
+    (``OPENAI_API_KEY``-only setups, OS keychain credentials) or unreadable.
+    """
+    path = auth_path or (_codex_home() / _AUTH_JSON_NAME)
+    if not path.exists():
+        logger.debug('Codex auth file not found, %s', {'path': str(path)})
+        return None
+    try:
+        auth = json.loads(path.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError) as e:
+        logger.debug('Failed to load Codex auth file, %s', {'path': str(path)}, exc_info=e)
+        return None
+
+    token = (auth.get('tokens') or {}).get('id_token')
+    if not token:
+        return None
+    claims = decode_jwt_unverified(token)
+    if not claims:
+        return None
+    return claims.get('email')
+
+
+def _resolve_codex_plugin_dir(plugin_name: str, marketplace: str) -> Optional[Path]:
+    """Find ``~/.codex/plugins/cache/<marketplace>/<plugin>/<hash>/``.
+
+    The trailing segment is a content hash. If multiple are cached, pick the
+    most recently modified.
+    """
+    base = _codex_home() / 'plugins' / 'cache' / marketplace / plugin_name
+    if not base.is_dir():
+        return None
+    candidates = [d for d in base.iterdir() if d.is_dir()]
+    if not candidates:
+        return None
+    return max(candidates, key=lambda d: d.stat().st_mtime)
+
+
+def _read_codex_plugin(plugin_dir: Path) -> tuple[dict, dict]:
+    """Read one Codex plugin's manifest + MCP servers.
+
+    Codex's manifest references the MCP file via a path string in the
+    ``mcpServers`` field (default ``./.mcp.json``); the target file is either
+    a bare ``{name: cfg}`` map or wrapped in ``{"mcpServers": {...}}``.
+    """
+    manifest = load_plugin_json(plugin_dir / '.codex-plugin' / 'plugin.json')
+    entry: dict = {}
+    if not manifest:
+        return entry, {}
+
+    for field in ('name', 'version', 'description'):
+        if field in manifest:
+            entry[field] = manifest[field]
+
+    mcp_ref = manifest.get('mcpServers')
+    if not mcp_ref:
+        return entry, {}
+    mcp_doc = load_plugin_json(plugin_dir / mcp_ref) or {}
+    servers = mcp_doc.get('mcpServers', mcp_doc)
+    if not isinstance(servers, dict):
+        servers = {}
+    if servers:
+        entry['mcp_server_names'] = list(servers.keys())
+    return entry, servers
+
+
+def _resolve_codex_plugins(config: dict) -> tuple[dict, dict]:
+    """Walk enabled ``[plugins."<plugin>@<marketplace>"]`` entries."""
+    return walk_enabled_plugins(
+        plugin_entries=config.get('plugins') or {},
+        is_enabled=lambda s: isinstance(s, dict) and bool(s.get('enabled')),
+        locate_dir=_resolve_codex_plugin_dir,
+        read_plugin=_read_codex_plugin,
+    )
+
+
+def _enable_codex_hooks_feature(scope: str, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+    """Set ``[features] hooks = true`` in Codex's ``config.toml``.
+
+    Codex's hook scripts are gated behind this feature flag. We preserve any
+    existing keys and create the file (+ parent dir) when missing.
+    """
+    config_path = _codex_config_toml_path(scope, repo_path)
+
+    config: dict = {}
+    if config_path.exists():
+        try:
+            with config_path.open('rb') as f:
+                config = tomllib.load(f)
+        except Exception as e:
+            logger.error('Failed to parse Codex config.toml, %s', {'path': str(config_path)}, exc_info=e)
+            return False, f'Failed to parse existing Codex config at {config_path}'
+
+    features = config.get('features')
+    if not isinstance(features, dict):
+        features = {}
+    features['hooks'] = True
+    config['features'] = features
+
+    try:
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        with config_path.open('wb') as f:
+            tomli_w.dump(config, f)
+        return True, f'Enabled hooks feature in {config_path}'
+    except Exception as e:
+        logger.error('Failed to write Codex config.toml, %s', {'path': str(config_path)}, exc_info=e)
+        return False, f'Failed to write Codex config at {config_path}'
+
+
+class Codex(IDE):
+    name: ClassVar[str] = 'codex'
+    display_name: ClassVar[str] = 'Codex'
+    hook_events: ClassVar[list[str]] = list(_HOOK_EVENTS)
+
+    def settings_path(self, scope: str, repo_path: Optional[Path] = None) -> Path:
+        if scope == 'repo' and repo_path:
+            return repo_path / _CONFIG_DIR_NAME / _HOOKS_FILE_NAME
+        return _codex_home() / _HOOKS_FILE_NAME
+
+    def render_hooks_config(self, async_mode: bool = False) -> dict:
+        # Codex's TOML `async: true` flag is unimplemented; shell-background via
+        # `&` is the working mechanism. SessionStart stays sync so the
+        # conversation context is registered before any scan hook fires.
+        bg = ' &' if async_mode else ''
+        scan_cmd = f'{_SCAN_COMMAND}{bg}'
+        return {
+            'hooks': {
+                'SessionStart': [
+                    {
+                        'matcher': 'startup|clear',
+                        'hooks': [{'type': 'command', 'command': _SESSION_START_COMMAND}],
+                    }
+                ],
+                'UserPromptSubmit': [
+                    {
+                        'hooks': [{'type': 'command', 'command': scan_cmd}],
+                    }
+                ],
+                'PreToolUse': [
+                    {
+                        'matcher': 'mcp__.*',
+                        'hooks': [{'type': 'command', 'command': scan_cmd}],
+                    },
+                ],
+            },
+        }
+
+    def post_install(self, scope: str, repo_path: Optional[Path] = None) -> tuple[bool, str]:
+        return _enable_codex_hooks_feature(scope, repo_path)
+
+    def matches_payload(self, raw_payload: dict) -> bool:
+        return raw_payload.get('hook_event_name', '') in _CODEX_EVENT_NAMES
+
+    def parse_hook_payload(self, raw_payload: dict) -> AIHookPayload:
+        hook_event_name = raw_payload.get('hook_event_name', '')
+        tool_name = raw_payload.get('tool_name', '')
+        tool_input = raw_payload.get('tool_input')
+
+        if hook_event_name == 'UserPromptSubmit':
+            canonical_event: AiHookEventType | str = AiHookEventType.PROMPT
+        elif hook_event_name == 'PreToolUse' and tool_name.startswith('mcp__'):
+            canonical_event = AiHookEventType.MCP_EXECUTION
+        else:
+            canonical_event = hook_event_name
+
+        mcp_server_name = None
+        mcp_tool_name = None
+        mcp_arguments = None
+        if tool_name.startswith('mcp__'):
+            parts = tool_name.split('__')
+            if len(parts) >= 2:
+                mcp_server_name = parts[1]
+            if len(parts) >= 3:
+                mcp_tool_name = parts[2]
+            mcp_arguments = tool_input
+
+        return AIHookPayload(
+            event_name=canonical_event,
+            conversation_id=raw_payload.get('session_id'),
+            generation_id=raw_payload.get('turn_id'),
+            ide_user_email=_email_from_auth(),
+            model=raw_payload.get('model'),
+            ide_provider=self.name,
+            prompt=raw_payload.get('prompt', ''),
+            mcp_server_name=mcp_server_name,
+            mcp_tool_name=mcp_tool_name,
+            mcp_arguments=mcp_arguments,
+        )
+
+    def build_hook_response(self, decision: HookDecision) -> dict:
+        # Codex accepts the same hook response shapes as Claude Code:
+        #  - PROMPT: empty for allow, {"decision": "block", "reason": ...} for deny
+        #  - PreToolUse: hookSpecificOutput.permissionDecision
+        if decision.event_type == AiHookEventType.PROMPT:
+            if decision.action == DecisionAction.ALLOW:
+                return {}
+            return {'decision': 'block', 'reason': decision.user_message or ''}
+
+        if decision.action == DecisionAction.ALLOW:
+            return {
+                'hookSpecificOutput': {
+                    'hookEventName': 'PreToolUse',
+                    'permissionDecision': 'allow',
+                }
+            }
+        return {
+            'hookSpecificOutput': {
+                'hookEventName': 'PreToolUse',
+                'permissionDecision': decision.action.value,  # 'deny' or 'ask'
+                'permissionDecisionReason': decision.user_message or '',
+            }
+        }
+
+    def build_session_payload(self, raw_payload: dict) -> AIHookPayload:
+        return AIHookPayload(
+            conversation_id=raw_payload.get('session_id'),
+            ide_user_email=_email_from_auth(),
+            model=raw_payload.get('model'),
+            ide_provider=self.name,
+            ide_version=raw_payload.get('codex_version'),
+            source=raw_payload.get('source'),
+        )
+
+    def get_user_email(self) -> Optional[str]:
+        return _email_from_auth()
+
+    def get_session_context(self) -> tuple[dict, dict]:
+        config = _load_codex_config()
+        if not config:
+            return {}, {}
+        # Codex stores MCP servers under `[mcp_servers.<name>]`. Plugin-contributed
+        # servers (via `[plugins."<plugin>@<marketplace>"]`) merge on top.
+        mcp_servers: dict = dict(config.get('mcp_servers') or {})
+        plugin_mcp, enriched_plugins = _resolve_codex_plugins(config)
+        mcp_servers.update(plugin_mcp)
+        return mcp_servers, enriched_plugins

cycode/cli/apps/ai_guardrails/ides/cursor.py

@@ -0,0 +1,119 @@
+"""Cursor IDE integration for AI guardrails."""
+
+import json
+import platform
+from pathlib import Path
+from typing import ClassVar, Optional
+
+from cycode.cli.apps.ai_guardrails.consts import CYCODE_SCAN_PROMPT_COMMAND, CYCODE_SESSION_START_COMMAND
+from cycode.cli.apps.ai_guardrails.ides.base import IDE, DecisionAction, HookDecision
+from cycode.cli.apps.ai_guardrails.scan.payload import AIHookPayload
+from cycode.cli.apps.ai_guardrails.scan.types import AiHookEventType
+from cycode.logger import get_logger
+
+logger = get_logger('AI Guardrails Cursor')
+
+_CURSOR_EVENT_MAPPING: dict[str, AiHookEventType] = {
+    'beforeSubmitPrompt': AiHookEventType.PROMPT,
+    'beforeReadFile': AiHookEventType.FILE_READ,
+    'beforeMCPExecution': AiHookEventType.MCP_EXECUTION,
+}
+
+_HOOKS_FILE_NAME = 'hooks.json'
+_REPO_SUBDIR = '.cursor'
+_MCP_CONFIG_FILENAME = 'mcp.json'
+
+# Cursor was the original default IDE — its scan command omits --ide to stay
+# byte-identical with already-installed hooks.json files. Session-start is
+# always explicit because it was introduced after Claude Code support.
+_SCAN_COMMAND = CYCODE_SCAN_PROMPT_COMMAND
+_SESSION_START_COMMAND = f'{CYCODE_SESSION_START_COMMAND} --ide cursor'
+
+
+def _user_hooks_dir() -> Path:
+    """Per-platform Cursor user-scope settings directory."""
+    if platform.system() == 'Darwin':
+        return Path.home() / '.cursor'
+    if platform.system() == 'Windows':
+        return Path.home() / 'AppData' / 'Roaming' / 'Cursor'
+    return Path.home() / '.config' / 'Cursor'
+
+
+def _load_cursor_mcp_config(config_path: Optional[Path] = None) -> Optional[dict]:
+    """Load and parse `~/.cursor/mcp.json`. Returns None if missing/invalid."""
+    path = config_path or (Path.home() / '.cursor' / _MCP_CONFIG_FILENAME)
+    if not path.exists():
+        logger.debug('Cursor MCP config file not found, %s', {'path': str(path)})
+        return None
+    try:
+        return json.loads(path.read_text(encoding='utf-8'))
+    except Exception as e:
+        logger.debug('Failed to load Cursor MCP config file', exc_info=e)
+        return None
+
+
+class Cursor(IDE):
+    name: ClassVar[str] = 'cursor'
+    display_name: ClassVar[str] = 'Cursor'
+    hook_events: ClassVar[list[str]] = list(_CURSOR_EVENT_MAPPING)
+
+    def settings_path(self, scope: str, repo_path: Optional[Path] = None) -> Path:
+        if scope == 'repo' and repo_path:
+            return repo_path / _REPO_SUBDIR / _HOOKS_FILE_NAME
+        return _user_hooks_dir() / _HOOKS_FILE_NAME
+
+    def render_hooks_config(self, async_mode: bool = False) -> dict:
+        command = f'{_SCAN_COMMAND} &' if async_mode else _SCAN_COMMAND
+        hooks = {event: [{'command': command}] for event in self.hook_events}
+        hooks['sessionStart'] = [{'command': _SESSION_START_COMMAND}]
+        return {'version': 1, 'hooks': hooks}
+
+    def matches_payload(self, raw_payload: dict) -> bool:
+        return raw_payload.get('hook_event_name', '') in _CURSOR_EVENT_MAPPING
+
+    def parse_hook_payload(self, raw_payload: dict) -> AIHookPayload:
+        cursor_event_name = raw_payload.get('hook_event_name', '')
+        canonical_event = _CURSOR_EVENT_MAPPING.get(cursor_event_name, cursor_event_name)
+        return AIHookPayload(
+            event_name=canonical_event,
+            conversation_id=raw_payload.get('conversation_id'),
+            generation_id=raw_payload.get('generation_id'),
+            ide_user_email=raw_payload.get('user_email'),
+            model=raw_payload.get('model'),
+            ide_provider=self.name,
+            ide_version=raw_payload.get('cursor_version'),
+            prompt=raw_payload.get('prompt', ''),
+            file_path=raw_payload.get('file_path') or raw_payload.get('path'),
+            mcp_server_name=raw_payload.get('command'),
+            mcp_tool_name=raw_payload.get('tool_name') or raw_payload.get('tool'),
+            mcp_arguments=(raw_payload.get('arguments') or raw_payload.get('tool_input') or raw_payload.get('input')),
+        )
+
+    def build_hook_response(self, decision: HookDecision) -> dict:
+        if decision.event_type == AiHookEventType.PROMPT:
+            if decision.action == DecisionAction.ALLOW:
+                return {'continue': True}
+            return {'continue': False, 'user_message': decision.user_message or ''}
+
+        # FILE_READ / MCP_EXECUTION → permission shape
+        if decision.action == DecisionAction.ALLOW:
+            return {'permission': 'allow'}
+        return {
+            'permission': decision.action.value,  # 'deny' or 'ask'
+            'user_message': decision.user_message or '',
+            'agent_message': decision.agent_message or '',
+        }
+
+    def build_session_payload(self, raw_payload: dict) -> AIHookPayload:
+        return AIHookPayload(
+            conversation_id=raw_payload.get('conversation_id'),
+            ide_user_email=raw_payload.get('user_email'),
+            model=raw_payload.get('model'),
+            ide_provider=self.name,
+            ide_version=raw_payload.get('cursor_version'),
+        )
+
+    def get_session_context(self) -> tuple[dict, dict]:
+        config = _load_cursor_mcp_config()
+        mcp_servers = dict((config or {}).get('mcpServers') or {}) if config else {}
+        return mcp_servers, {}

cycode/cli/apps/ai_guardrails/install_command.py

@@ -5,14 +5,10 @@ from typing import Annotated, Optional
 
 import typer
 
-from cycode.cli.apps.ai_guardrails.command_utils import (
-    console,
-    resolve_repo_path,
-    validate_and_parse_ide,
-    validate_scope,
-)
-from cycode.cli.apps.ai_guardrails.consts import IDE_CONFIGS, AIIDEType, InstallMode, PolicyMode
+from cycode.cli.apps.ai_guardrails.command_utils import console, resolve_repo_path, validate_scope
+from cycode.cli.apps.ai_guardrails.consts import InstallMode, PolicyMode
 from cycode.cli.apps.ai_guardrails.hooks_manager import create_policy_file, install_hooks
+from cycode.cli.apps.ai_guardrails.ides import DEFAULT_IDE_NAME, IDES, resolve_ides
 
 
 def install_command(
@@ -29,9 +25,9 @@ def install_command(
         str,
         typer.Option(
             '--ide',
-            help='IDE to install hooks for (e.g., "cursor", "claude-code", or "all" for all IDEs). Defaults to cursor.',
+            help=f'IDE to install hooks for ({", ".join(IDES)}, or "all" for every supported IDE).',
         ),
-    ] = AIIDEType.CURSOR.value,
+    ] = DEFAULT_IDE_NAME,
     repo_path: Annotated[
         Optional[Path],
         typer.Option(
@@ -55,35 +51,30 @@ def install_command(
 ) -> None:
     """Install AI guardrails hooks for supported IDEs.
 
-    This command configures the specified IDE to use Cycode for scanning prompts, file reads,
-    and MCP tool calls for secrets before they are sent to AI models.
+    Configures the specified IDE to use Cycode for scanning prompts, file reads,
+    and MCP tool calls for secrets before they reach the AI model.
 
     Examples:
         cycode ai-guardrails install                    # Install in report mode (default)
         cycode ai-guardrails install --mode block       # Install in block mode
         cycode ai-guardrails install --scope repo       # Install for current repo only
-        cycode ai-guardrails install --ide cursor       # Install for Cursor IDE
-        cycode ai-guardrails install --ide all          # Install for all supported IDEs
-        cycode ai-guardrails install --scope repo --repo-path /path/to/repo
+        cycode ai-guardrails install --ide claude-code  # Install for a specific IDE
+        cycode ai-guardrails install --ide all          # Install for every supported IDE
     """
-    # Validate inputs
     validate_scope(scope)
     repo_path = resolve_repo_path(scope, repo_path)
-    ide_type = validate_and_parse_ide(ide)
+    ides_to_install = resolve_ides(ide)
 
-    ides_to_install: list[AIIDEType] = list(AIIDEType) if ide_type is None else [ide_type]
+    report_mode = mode == InstallMode.REPORT
 
     results: list[tuple[str, bool, str]] = []
     for current_ide in ides_to_install:
-        ide_name = IDE_CONFIGS[current_ide].name
-        report_mode = mode == InstallMode.REPORT
-        success, message = install_hooks(scope, repo_path, ide=current_ide, report_mode=report_mode)
-        results.append((ide_name, success, message))
+        success, message = install_hooks(current_ide, scope, repo_path, report_mode=report_mode)
+        results.append((current_ide.display_name, success, message))
 
-    # Report results for each IDE
     any_success = False
     all_success = True
-    for _ide_name, success, message in results:
+    for _name, success, message in results:
         if success:
             console.print(f'[green]✓[/] {message}')
             any_success = True