CxIDE/docs/DEVELOPER.md

# CxIDE — Developer Guide

## Getting Started

```bash
# Clone and enter project
git clone <repo-url> CxIDE && cd CxIDE

# Run first-time setup
./scripts/setup.sh
```

Setup validates your toolchain, installs git hooks, and builds the agent CLI.

## Project Structure

```text
CxIDE/
├── SwiftIDEApp.swift         # @main entry point
├── EngineFactory.swift       # Engine selection factory
├── SwiftCodeEngine.swift     # Full Swift execution engine
├── SandboxedSwiftEngine.swift # Safe interpreter
├── Core/                     # C++ analysis engine
│   ├── CodeEngine.hpp/cpp    # Tokenizer, metrics, analysis
│   ├── SwiftEngineWrapper.*  # ObjC++ bridge
│   ├── CodeEngine.swift      # CppEngineController facade
│   └── FileItem.swift        # File model
├── Agent/                    # Embedded MCP agent (56 tools)
│   ├── MCPServer.swift       # JSON-RPC server
│   ├── MCPTypes.swift        # Protocol types
│   ├── AgentConfig.swift     # Configuration
│   ├── AgentMemory.swift     # Session memory
│   └── Tools/                # 8 tool modules
├── Models/                   # Data models
├── Views/                    # SwiftUI views
├── ViewModels/               # View models
├── Services/                 # AgentService
├── CxSwiftAgent/             # Standalone SPM agent package
├── scripts/                  # Build & dev scripts
├── hooks/                    # Git hooks
└── docs/                     # Documentation
```

## Daily Workflow

### Build & Run

```bash
# Compile C++ engine + ObjC++ bridge
./scripts/build.sh

# Release build
./scripts/build.sh release

# Open in Xcode for SwiftUI development
open CxIDE.xcodeproj   # or create one if needed
```

### Testing

```bash
# Run full test suite (C++ validation + agent tests + structure check)
./scripts/test.sh

# Agent tests only
cd CxSwiftAgent && swift test

# Lint check
./scripts/lint.sh
```

### Clean Build

```bash
./scripts/clean.sh
```

## Adding Features

### Adding a new View

1. Create `Views/YourView.swift`
2. Add any new model types to `Models/Models.swift`
3. Wire into `IDEContainerView.swift` (sidebar or panel)
4. Add state to `EditorViewModel.swift` if needed

### Adding an Agent Tool

1. Choose the appropriate module in `Agent/Tools/` (or create a new one)
2. Add tool registration in the module's `register()` function:

```swift
server.registerTool(MCPToolDefinition(
    name: "your_tool_name",
    description: "What it does",
    inputSchema: ["type": "object", "properties": [...]],
    annotations: ToolAnnotations(readOnlyHint: true)
) { params in
    // Implementation
    return ["content": [["type": "text", "text": "result"]]]
})
```

3. If it's a new module, register it in `Services/AgentService.swift`:

```swift
YourModule.register(on: server, config: config, memory: memory)
```

4. Add the tool name to `AgentService.toolCategories` and optionally `readOnlyTools`
5. Add a routing keyword in `AgentService.routeMessage()` if applicable

### Modifying the C++ Engine

1. Add declaration to `Core/CodeEngine.hpp`
2. Implement in `Core/CodeEngine.cpp`
3. Add ObjC wrapper method in `Core/SwiftEngineWrapper.h` and `.mm`
4. Add Swift facade method in `Core/CodeEngine.swift` (`CppEngineController`)
5. Rebuild: `./scripts/build.sh`

## Commit Conventions

This project uses [Conventional Commits](https://www.conventionalcommits.org/):

```text
type(scope): description

Types:  feat, fix, refactor, docs, test, build, ci, chore, perf, style, agent
Scopes: core, agent, views, models, services, vm, engine, tools
```

Examples:

```text
feat(agent): add workspace analysis tool
fix(core): handle nested block comments in tokenizer
refactor(views): extract agent chat into separate component
docs: update architecture diagram
test(agent): add integration tests for file operations
build: add release optimization flags
```

The `commit-msg` hook enforces this format automatically.

## Git Hooks

Installed automatically by `./scripts/setup.sh` or manually:

```bash
cp hooks/* .git/hooks/ && chmod +x .git/hooks/*
```

| Hook | What It Does |
| ---- | ------------ |
| `pre-commit` | Validates C++ syntax, scans for secrets and merge markers |
| `commit-msg` | Enforces conventional commit format |
| `pre-push` | Compiles C++ engine, runs agent tests, scans for sensitive data |

## Agent Commands

Available from the Command Palette (Cmd+Shift+P) or the Agent sidebar:

| Command | Shortcut | Description |
| ------- | -------- | ----------- |
| Agent: Explain Code | Cmd+Shift+E | Explain the current editor content |
| Agent: Review Code | Cmd+Shift+R | Review code for issues and improvements |
| Agent: Fix Issues | — | Auto-fix detected issues |
| Agent: Generate Tests | — | Generate unit tests for current code |
| Agent: Analyze Workspace | — | Full workspace analysis |
| Agent: Run Diagnostics | — | Lint, complexity, and health checks |
| Agent: Security Audit | — | Scan for security vulnerabilities |
| Agent: List Tools | — | Show all 56 available tools |

### Direct Tool Invocation

In the Agent chat panel, prefix with `/` to call a tool directly:

```text
/file_list {"path": "."}
/git_status {}
/diag_complexity {"path": "Core/CodeEngine.cpp"}
```

## Environment Variables (Agent)

| Variable | Default | Description |
| -------- | ------- | ----------- |
| `CX_WORKSPACE` | cwd | Workspace root path |
| `CX_LOG_LEVEL` | info | Logging: debug, info, warn, error |
| `CX_PROFILE` | development | Profile: development, staging, production |
| `CX_SANDBOX` | false | Restrict to read-only tools |
| `CX_AUTH_TOKEN` | — | API authentication token |
| `CX_HOST` | 127.0.0.1 | HTTP server bind address |
| `CX_PORT` | 3001 | HTTP server port |

## Troubleshooting

**C++ bridge not linking:** Ensure the bridging header `Core/SwiftEngineWrapper.h` is
set in Xcode Build Settings → "Objective-C Bridging Header".

**Agent tools not registering:** Check `Services/AgentService.swift` `initialize()` —
all 8 tool modules must be registered.

**Swift execution fails:** `SwiftCodeEngine` needs `/usr/bin/swift` — macOS only.
On other platforms, the sandbox engine is used automatically.

**Sandbox mode blocks writes:** Toggle `agentService.sandboxMode` or unset `CX_SANDBOX`.