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

cycode/__init__.py

@@ -1 +1 @@
-__version__ = '3.15.3.dev8'  # DON'T TOUCH. Placeholder. Will be filled automatically on poetry build from Git Tag
+__version__ = '3.15.4.dev1'  # DON'T TOUCH. Placeholder. Will be filled automatically on poetry build from Git Tag

cycode/cli/apps/ai_guardrails/command_utils.py

@@ -7,46 +7,11 @@ from typing import Optional
 import typer
 from rich.console import Console
 
-from cycode.cli.apps.ai_guardrails.consts import AIIDEType
-
 console = Console()
 
 
-def validate_and_parse_ide(ide: str) -> Optional[AIIDEType]:
-    """Validate IDE parameter, returning None for 'all'.
-
-    Args:
-        ide: IDE name string (e.g., 'cursor', 'claude-code', 'all')
-
-    Returns:
-        AIIDEType enum value, or None if 'all' was specified
-
-    Raises:
-        typer.Exit: If IDE is invalid
-    """
-    if ide.lower() == 'all':
-        return None
-    try:
-        return AIIDEType(ide.lower())
-    except ValueError:
-        valid_ides = ', '.join([ide_type.value for ide_type in AIIDEType])
-        console.print(
-            f'[red]Error:[/] Invalid IDE "{ide}". Supported IDEs: {valid_ides}, all',
-            style='bold red',
-        )
-        raise typer.Exit(1) from None
-
-
 def validate_scope(scope: str, allowed_scopes: tuple[str, ...] = ('user', 'repo')) -> None:
-    """Validate scope parameter.
-
-    Args:
-        scope: Scope string to validate
-        allowed_scopes: Tuple of allowed scope values
-
-    Raises:
-        typer.Exit: If scope is invalid
-    """
+    """Validate scope parameter."""
     if scope not in allowed_scopes:
         scopes_list = ', '.join(f'"{s}"' for s in allowed_scopes)
         console.print(f'[red]Error:[/] Invalid scope. Use {scopes_list}.', style='bold red')
@@ -54,15 +19,7 @@ def validate_scope(scope: str, allowed_scopes: tuple[str, ...] = ('user', 'repo'
 
 
 def resolve_repo_path(scope: str, repo_path: Optional[Path]) -> Optional[Path]:
-    """Resolve repository path, defaulting to current directory for repo scope.
-
-    Args:
-        scope: The command scope ('user' or 'repo')
-        repo_path: Provided repo path or None
-
-    Returns:
-        Resolved Path for repo scope, None for user scope
-    """
+    """Default repo_path to cwd for 'repo' scope; leave None for 'user' scope."""
     if scope == 'repo' and repo_path is None:
         return Path(os.getcwd())
     return repo_path

cycode/cli/apps/ai_guardrails/consts.py

@@ -1,22 +1,6 @@
-"""Constants for AI guardrails hooks management.
+"""Shared constants and policy/mode enums for AI guardrails."""
 
-Currently supports:
-- Cursor
-- Claude Code
-"""
-
-import platform
-from copy import deepcopy
 from enum import Enum
-from pathlib import Path
-from typing import NamedTuple
-
-
-class AIIDEType(str, Enum):
-    """Supported AI IDE types."""
-
-    CURSOR = 'cursor'
-    CLAUDE_CODE = 'claude-code'
 
 
 class PolicyMode(str, Enum):
@@ -33,123 +17,7 @@ class InstallMode(str, Enum):
     BLOCK = 'block'
 
 
-class IDEConfig(NamedTuple):
-    """Configuration for an AI IDE."""
-
-    name: str
-    hooks_dir: Path
-    repo_hooks_subdir: str  # Subdirectory in repo for hooks (e.g., '.cursor')
-    hooks_file_name: str
-    hook_events: list[str]  # List of supported hook event names for this IDE
-
-
-def _get_cursor_hooks_dir() -> Path:
-    """Get Cursor hooks directory based on platform."""
-    if platform.system() == 'Darwin':
-        return Path.home() / '.cursor'
-    if platform.system() == 'Windows':
-        return Path.home() / 'AppData' / 'Roaming' / 'Cursor'
-    # Linux
-    return Path.home() / '.config' / 'Cursor'
-
-
-def _get_claude_code_hooks_dir() -> Path:
-    """Get Claude Code hooks directory.
-
-    Claude Code uses ~/.claude on all platforms.
-    """
-    return Path.home() / '.claude'
-
-
-# IDE-specific configurations
-IDE_CONFIGS: dict[AIIDEType, IDEConfig] = {
-    AIIDEType.CURSOR: IDEConfig(
-        name='Cursor',
-        hooks_dir=_get_cursor_hooks_dir(),
-        repo_hooks_subdir='.cursor',
-        hooks_file_name='hooks.json',
-        hook_events=['beforeSubmitPrompt', 'beforeReadFile', 'beforeMCPExecution'],
-    ),
-    AIIDEType.CLAUDE_CODE: IDEConfig(
-        name='Claude Code',
-        hooks_dir=_get_claude_code_hooks_dir(),
-        repo_hooks_subdir='.claude',
-        hooks_file_name='settings.json',
-        hook_events=['UserPromptSubmit', 'PreToolUse:Read', 'PreToolUse:mcp'],
-    ),
-}
-
-# Default IDE
-DEFAULT_IDE = AIIDEType.CURSOR
-
-# Command used in hooks
+# Base CLI commands invoked from installed hooks. IDE classes append --ide flags
+# (and any other suffix) on top of these.
 CYCODE_SCAN_PROMPT_COMMAND = 'cycode ai-guardrails scan'
 CYCODE_SESSION_START_COMMAND = 'cycode ai-guardrails session-start'
-
-
-def _get_cursor_hooks_config(async_mode: bool = False) -> dict:
-    """Get Cursor-specific hooks configuration."""
-    config = IDE_CONFIGS[AIIDEType.CURSOR]
-    command = f'{CYCODE_SCAN_PROMPT_COMMAND} &' if async_mode else CYCODE_SCAN_PROMPT_COMMAND
-    hooks = {event: [{'command': command}] for event in config.hook_events}
-    hooks['sessionStart'] = [{'command': f'{CYCODE_SESSION_START_COMMAND} --ide cursor'}]
-
-    return {
-        'version': 1,
-        'hooks': hooks,
-    }
-
-
-def _get_claude_code_hooks_config(async_mode: bool = False) -> dict:
-    """Get Claude Code-specific hooks configuration.
-
-    Claude Code uses a different hook format with nested structure:
-    - hooks are arrays of objects with 'hooks' containing command arrays
-    - PreToolUse uses 'matcher' field to specify which tools to intercept
-    """
-    command = f'{CYCODE_SCAN_PROMPT_COMMAND} --ide claude-code'
-
-    hook_entry = {'type': 'command', 'command': command}
-    if async_mode:
-        hook_entry['async'] = True
-        hook_entry['timeout'] = 20
-
-    return {
-        'hooks': {
-            'SessionStart': [
-                {
-                    'hooks': [{'type': 'command', 'command': f'{CYCODE_SESSION_START_COMMAND} --ide claude-code'}],
-                }
-            ],
-            'UserPromptSubmit': [
-                {
-                    'hooks': [deepcopy(hook_entry)],
-                }
-            ],
-            'PreToolUse': [
-                {
-                    'matcher': 'Read',
-                    'hooks': [deepcopy(hook_entry)],
-                },
-                {
-                    'matcher': 'mcp__.*',
-                    'hooks': [deepcopy(hook_entry)],
-                },
-            ],
-        },
-    }
-
-
-def get_hooks_config(ide: AIIDEType, async_mode: bool = False) -> dict:
-    """Get the hooks configuration for a specific IDE.
-
-    Args:
-        ide: The AI IDE type
-        async_mode: If True, hooks run asynchronously (non-blocking)
-
-    Returns:
-        Dict with hooks configuration for the specified IDE
-    """
-    if ide == AIIDEType.CLAUDE_CODE:
-        return _get_claude_code_hooks_config(async_mode=async_mode)
-    return _get_cursor_hooks_config(async_mode=async_mode)

cycode/cli/apps/ai_guardrails/hooks_manager.py

@@ -1,8 +1,8 @@
-"""
-Hooks manager for AI guardrails.
+"""Hooks manager for AI guardrails.
 
-Handles installation, removal, and status checking of AI IDE hooks.
-Supports multiple IDEs: Cursor, Claude Code (future).
+Generic install/uninstall/status logic. All IDE-specific concerns (settings
+paths, hooks template shape) live on the `IDE` instance; this module is
+agent-agnostic.
 """
 
 import copy
@@ -12,47 +12,45 @@ from typing import Optional
 
 import yaml
 
-from cycode.cli.apps.ai_guardrails.consts import (
-    DEFAULT_IDE,
-    IDE_CONFIGS,
-    AIIDEType,
-    PolicyMode,
-    get_hooks_config,
-)
+from cycode.cli.apps.ai_guardrails.consts import PolicyMode
+from cycode.cli.apps.ai_guardrails.ides.base import IDE
 from cycode.cli.apps.ai_guardrails.scan.consts import DEFAULT_POLICY, POLICY_FILE_NAME
 from cycode.logger import get_logger
 
 logger = get_logger('AI Guardrails Hooks')
 
 
-def get_hooks_path(scope: str, repo_path: Optional[Path] = None, ide: AIIDEType = DEFAULT_IDE) -> Path:
-    """Get the hooks.json path for the given scope and IDE.
+_CYCODE_COMMAND_MARKERS = ('cycode ai-guardrails',)
+
 
-    Args:
-        scope: 'user' for user-level hooks, 'repo' for repository-level hooks
-        repo_path: Repository path (required if scope is 'repo')
-        ide: The AI IDE type (default: Cursor)
-    """
-    config = IDE_CONFIGS[ide]
-    if scope == 'repo' and repo_path:
-        return repo_path / config.repo_hooks_subdir / config.hooks_file_name
-    return config.hooks_dir / config.hooks_file_name
+def _is_cycode_command(command: str) -> bool:
+    return any(marker in command for marker in _CYCODE_COMMAND_MARKERS)
+
+
+def is_cycode_hook_entry(entry: dict) -> bool:
+    """Detect Cycode hook entries in both Cursor (flat) and Claude Code (nested) shapes."""
+    command = entry.get('command', '')
+    if _is_cycode_command(command):
+        return True
+
+    for hook in entry.get('hooks', []):
+        if isinstance(hook, dict) and _is_cycode_command(hook.get('command', '')):
+            return True
+
+    return False
 
 
-def load_hooks_file(hooks_path: Path) -> Optional[dict]:
-    """Load existing hooks.json file."""
+def _load_hooks_file(hooks_path: Path) -> Optional[dict]:
     if not hooks_path.exists():
         return None
     try:
-        content = hooks_path.read_text(encoding='utf-8')
-        return json.loads(content)
+        return json.loads(hooks_path.read_text(encoding='utf-8'))
     except Exception as e:
         logger.debug('Failed to load hooks file', exc_info=e)
         return None
 
 
-def save_hooks_file(hooks_path: Path, hooks_config: dict) -> bool:
-    """Save hooks.json file."""
+def _save_hooks_file(hooks_path: Path, hooks_config: dict) -> bool:
     try:
         hooks_path.parent.mkdir(parents=True, exist_ok=True)
         hooks_path.write_text(json.dumps(hooks_config, indent=2), encoding='utf-8')
@@ -62,39 +60,7 @@ def save_hooks_file(hooks_path: Path, hooks_config: dict) -> bool:
         return False
 
 
-_CYCODE_COMMAND_MARKERS = ('cycode ai-guardrails',)
-
-
-def _is_cycode_command(command: str) -> bool:
-    return any(marker in command for marker in _CYCODE_COMMAND_MARKERS)
-
-
-def is_cycode_hook_entry(entry: dict) -> bool:
-    """Check if a hook entry is from cycode-cli.
-
-    Handles both Cursor format (flat) and Claude Code format (nested).
-
-    Cursor format: {"command": "cycode ai-guardrails scan"}
-    Claude Code format: {"hooks": [{"type": "command", "command": "cycode ai-guardrails scan --ide claude-code"}]}
-    """
-    # Check Cursor format (flat command)
-    command = entry.get('command', '')
-    if _is_cycode_command(command):
-        return True
-
-    # Check Claude Code format (nested hooks array)
-    hooks = entry.get('hooks', [])
-    for hook in hooks:
-        if isinstance(hook, dict):
-            hook_command = hook.get('command', '')
-            if _is_cycode_command(hook_command):
-                return True
-
-    return False
-
-
-def _load_policy(policy_path: Path) -> dict:
-    """Load existing policy file merged with defaults, or return defaults if not found."""
+def _load_policy_dict(policy_path: Path) -> dict:
     if not policy_path.exists():
         return copy.deepcopy(DEFAULT_POLICY)
     try:
@@ -107,22 +73,13 @@ def _load_policy(policy_path: Path) -> dict:
 def create_policy_file(scope: str, mode: PolicyMode, repo_path: Optional[Path] = None) -> tuple[bool, str]:
     """Create or update the ai-guardrails.yaml policy file.
 
-    If the file already exists, only the mode field is updated.
-    If it doesn't exist, a new file is created from the default policy.
-
-    Args:
-        scope: 'user' for user-level, 'repo' for repository-level
-        mode: The policy mode to set
-        repo_path: Repository path (required if scope is 'repo')
-
-    Returns:
-        Tuple of (success, message)
+    If the file already exists, only the mode field is updated; otherwise a new
+    file is created from the default policy.
     """
     config_dir = repo_path / '.cycode' if scope == 'repo' and repo_path else Path.home() / '.cycode'
     policy_path = config_dir / POLICY_FILE_NAME
 
-    policy = _load_policy(policy_path)
-
+    policy = _load_policy_dict(policy_path)
     policy['mode'] = mode.value
 
     try:
@@ -135,35 +92,21 @@ def create_policy_file(scope: str, mode: PolicyMode, repo_path: Optional[Path] =
 
 
 def install_hooks(
+    ide: IDE,
     scope: str = 'user',
     repo_path: Optional[Path] = None,
-    ide: AIIDEType = DEFAULT_IDE,
     report_mode: bool = False,
 ) -> tuple[bool, str]:
-    """
-    Install Cycode AI guardrails hooks.
-
-    Args:
-        scope: 'user' for user-level hooks, 'repo' for repository-level hooks
-        repo_path: Repository path (required if scope is 'repo')
-        ide: The AI IDE type (default: Cursor)
-        report_mode: If True, install hooks in async mode (non-blocking)
+    """Install Cycode AI guardrails hooks for ``ide``."""
+    hooks_path = ide.settings_path(scope, repo_path)
 
-    Returns:
-        Tuple of (success, message)
-    """
-    hooks_path = get_hooks_path(scope, repo_path, ide)
-
-    # Load existing hooks or create new
-    existing = load_hooks_file(hooks_path) or {'version': 1, 'hooks': {}}
+    existing = _load_hooks_file(hooks_path) or {'version': 1, 'hooks': {}}
     existing.setdefault('version', 1)
     existing.setdefault('hooks', {})
 
-    # Get IDE-specific hooks configuration
-    hooks_config = get_hooks_config(ide, async_mode=report_mode)
+    rendered = ide.render_hooks_config(async_mode=report_mode)
 
-    # Add/update Cycode hooks
-    for event, entries in hooks_config['hooks'].items():
+    for event, entries in rendered['hooks'].items():
         existing['hooks'].setdefault(event, [])
 
         # Remove any existing Cycode entries for this event
@@ -173,47 +116,31 @@ def install_hooks(
         for entry in entries:
             existing['hooks'][event].append(entry)
 
-    # Save
-    if save_hooks_file(hooks_path, existing):
+    if _save_hooks_file(hooks_path, existing):
         return True, f'AI guardrails hooks installed: {hooks_path}'
     return False, f'Failed to install hooks to {hooks_path}'
 
 
-def uninstall_hooks(
-    scope: str = 'user', repo_path: Optional[Path] = None, ide: AIIDEType = DEFAULT_IDE
-) -> tuple[bool, str]:
-    """
-    Remove Cycode AI guardrails hooks.
-
-    Args:
-        scope: 'user' for user-level hooks, 'repo' for repository-level hooks
-        repo_path: Repository path (required if scope is 'repo')
-        ide: The AI IDE type (default: Cursor)
-
-    Returns:
-        Tuple of (success, message)
-    """
-    hooks_path = get_hooks_path(scope, repo_path, ide)
+def uninstall_hooks(ide: IDE, scope: str = 'user', repo_path: Optional[Path] = None) -> tuple[bool, str]:
+    """Remove Cycode AI guardrails hooks for ``ide``."""
+    hooks_path = ide.settings_path(scope, repo_path)
 
-    existing = load_hooks_file(hooks_path)
+    existing = _load_hooks_file(hooks_path)
     if existing is None:
         return True, f'No hooks file found at {hooks_path}'
 
-    # Remove Cycode entries from all events
     modified = False
     for event in list(existing.get('hooks', {}).keys()):
         original_count = len(existing['hooks'][event])
         existing['hooks'][event] = [e for e in existing['hooks'][event] if not is_cycode_hook_entry(e)]
         if len(existing['hooks'][event]) != original_count:
             modified = True
-        # Remove empty event lists
         if not existing['hooks'][event]:
             del existing['hooks'][event]
 
     if not modified:
         return True, 'No Cycode hooks found to remove'
 
-    # Save or delete if empty
     if not existing.get('hooks'):
         try:
             hooks_path.unlink()
@@ -222,48 +149,35 @@ def uninstall_hooks(
             logger.debug('Failed to delete hooks file', exc_info=e)
             return False, f'Failed to remove hooks file: {hooks_path}'
 
-    if save_hooks_file(hooks_path, existing):
+    if _save_hooks_file(hooks_path, existing):
         return True, f'Cycode hooks removed from: {hooks_path}'
     return False, f'Failed to update hooks file: {hooks_path}'
 
 
-def get_hooks_status(scope: str = 'user', repo_path: Optional[Path] = None, ide: AIIDEType = DEFAULT_IDE) -> dict:
-    """
-    Get the status of AI guardrails hooks.
-
-    Args:
-        scope: 'user' for user-level hooks, 'repo' for repository-level hooks
-        repo_path: Repository path (required if scope is 'repo')
-        ide: The AI IDE type (default: Cursor)
-
-    Returns:
-        Dict with status information
-    """
-    hooks_path = get_hooks_path(scope, repo_path, ide)
+def get_hooks_status(ide: IDE, scope: str = 'user', repo_path: Optional[Path] = None) -> dict:
+    """Return installation status of Cycode hooks for ``ide``."""
+    hooks_path = ide.settings_path(scope, repo_path)
 
-    status = {
+    status: dict = {
         'scope': scope,
-        'ide': ide.value,
-        'ide_name': IDE_CONFIGS[ide].name,
+        'ide': ide.name,
+        'ide_name': ide.display_name,
         'hooks_path': str(hooks_path),
         'file_exists': hooks_path.exists(),
         'cycode_installed': False,
         'hooks': {},
     }
 
-    existing = load_hooks_file(hooks_path)
+    existing = _load_hooks_file(hooks_path)
     if existing is None:
         return status
 
-    # Check each hook event for this IDE
-    ide_config = IDE_CONFIGS[ide]
     has_cycode_hooks = False
-    for event in ide_config.hook_events:
-        # Handle event:matcher format
+    for event in ide.hook_events:
+        # '<event>:<matcher>' filters entries to a specific tool/matcher.
         if ':' in event:
             actual_event, matcher_prefix = event.split(':', 1)
             all_entries = existing.get('hooks', {}).get(actual_event, [])
-            # Filter entries by matcher
             entries = [e for e in all_entries if e.get('matcher', '').startswith(matcher_prefix)]
         else:
             entries = existing.get('hooks', {}).get(event, [])
@@ -278,5 +192,4 @@ def get_hooks_status(scope: str = 'user', repo_path: Optional[Path] = None, ide:
         }
 
     status['cycode_installed'] = has_cycode_hooks
-
     return status

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

@@ -0,0 +1,44 @@
+"""Registry of supported AI guardrails IDE integrations.
+
+Adding a new IDE: create `ides/<name>.py` with a subclass of `IDE`, import it
+here, and include an instance in the `IDES` tuple. Nothing else in the package
+needs to change.
+"""
+
+import typer
+
+from cycode.cli.apps.ai_guardrails.ides.base import IDE
+from cycode.cli.apps.ai_guardrails.ides.claude_code import ClaudeCode
+from cycode.cli.apps.ai_guardrails.ides.cursor import Cursor
+
+# Single source of truth: name → singleton instance.
+# `--ide` choices and install/uninstall/status iteration both derive from this.
+IDES: dict[str, IDE] = {ide.name: ide for ide in (Cursor(), ClaudeCode())}
+
+# Default IDE used when `--ide` is omitted. Kept here so the value is colocated
+# with the registry; no module outside `ides/` needs to know which IDE wins.
+DEFAULT_IDE_NAME = 'cursor'
+
+
+def get_ide(name: str) -> IDE:
+    """Look up the IDE integration registered under ``name``.
+
+    Raises ``typer.BadParameter`` when the name is unknown — surfaces as a
+    user-friendly CLI error rather than a KeyError stack trace.
+    """
+    ide = IDES.get(name.lower())
+    if ide is None:
+        valid = ', '.join(IDES.keys())
+        raise typer.BadParameter(f'Unknown IDE "{name}". Supported: {valid}.')
+    return ide
+
+
+def resolve_ides(name: str) -> list[IDE]:
+    """Resolve an ``--ide`` argument to one or all IDE instances.
+
+    ``"all"`` returns every registered IDE; anything else returns a single
+    matching IDE (raising ``typer.BadParameter`` for unknown names).
+    """
+    if name.lower() == 'all':
+        return list(IDES.values())
+    return [get_ide(name)]