feat: add test fixture Neovim configurations with utility scripts

Change-Id: Ifb146a3a6212bfc75f4a9df6e8cdc1d50caece84
Signed-off-by: Thomas Kosiewski <tk@coder.com>

Author: ThomasK33

.envrc

@@ -7,3 +7,6 @@ fi
 nix_direnv_manual_reload
 
 use flake .
+
+# Add fixtures/bin to PATH for nvim config aliases
+PATH_add fixtures/bin

ARCHITECTURE.md

@@ -205,6 +205,8 @@ lua/claudecode/
 
 ## Testing
 
+### Automated Testing
+
 Three-layer testing strategy using busted:
 
 ```lua
@@ -234,6 +236,30 @@ describe("full flow", function()
 end)
 ```
 
+### Integration Testing with Fixtures
+
+Manual testing with real Neovim configurations in the `fixtures/` directory:
+
+```bash
+# Test with different file explorers
+source fixtures/nvim-aliases.sh
+vv nvim-tree  # Test with nvim-tree integration
+vv oil        # Test with oil.nvim integration
+vv netrw      # Test with built-in netrw
+
+# Each fixture provides:
+# - Complete Neovim configuration
+# - Plugin dependencies
+# - Development keybindings
+# - Integration-specific testing scenarios
+```
+
+**Fixture Architecture**:
+
+- `fixtures/bin/` - Helper scripts (`vv`, `vve`, `list-configs`)
+- `fixtures/[integration]/` - Complete Neovim configs for testing
+- `fixtures/nvim-aliases.sh` - Shell aliases for easy testing
+
 ## Performance & Security
 
 - **Debounced Updates**: 50ms delay on selection changes

CLAUDE.md

@@ -37,6 +37,22 @@ claudecode.nvim - A Neovim plugin that implements the same WebSocket-based MCP p
 - `nix develop` - Enter development shell with all dependencies
 - `nix fmt` - Format all files using nix formatter
 
+### Integration Testing with Fixtures
+
+The `fixtures/` directory contains test Neovim configurations for verifying plugin integrations:
+
+- `vv <config>` - Start Neovim with a specific fixture configuration
+- `vve <config>` - Start Neovim with a fixture config in edit mode
+- `list-configs` - Show available fixture configurations
+- Source `fixtures/nvim-aliases.sh` to enable these commands
+
+**Available Fixtures**:
+- `netrw` - Tests with Neovim's built-in file explorer
+- `nvim-tree` - Tests with nvim-tree.lua file explorer
+- `oil` - Tests with oil.nvim file explorer
+
+**Usage**: `source fixtures/nvim-aliases.sh && vv oil` starts Neovim with oil.nvim configuration
+
 ## Architecture Overview
 
 ### Core Components
@@ -342,6 +358,22 @@ rg "0\.1\.0" .  # Should only show CHANGELOG.md historical entries
 4. **Document Changes**: Update relevant documentation (this file, PROTOCOL.md, etc.)
 5. **Commit**: Only commit after successful `make` execution
 
+### Integration Development Guidelines
+
+**Adding New Integrations** (file explorers, terminals, etc.):
+
+1. **Implement Integration**: Add support in relevant modules (e.g., `lua/claudecode/tools/`)
+2. **Create Fixture Configuration**: **REQUIRED** - Add a complete Neovim config in `fixtures/[integration-name]/`
+3. **Test Integration**: Use fixture to verify functionality with `vv [integration-name]`
+4. **Update Documentation**: Add integration to fixtures list and relevant tool documentation
+5. **Run Full Test Suite**: Ensure `make` passes with new integration
+
+**Fixture Requirements**:
+- Complete Neovim configuration with plugin dependencies
+- Include `dev-claudecode.lua` with development keybindings
+- Test all relevant claudecode.nvim features with the integration
+- Document any integration-specific behaviors or limitations
+
 ### MCP Tool Development Guidelines
 
 **Adding New Tools**:

DEVELOPMENT.md

@@ -7,6 +7,12 @@ Quick guide for contributors to the claudecode.nvim project.
 ```none
 claudecode.nvim/
 ├── .github/workflows/       # CI workflow definitions
+├── fixtures/                # Test Neovim configurations for integration testing
+│   ├── bin/                 # Helper scripts (vv, vve, list-configs)
+│   ├── netrw/               # Neovim config testing with built-in file explorer
+│   ├── nvim-tree/           # Neovim config testing with nvim-tree.lua
+│   ├── oil/                 # Neovim config testing with oil.nvim
+│   └── nvim-aliases.sh      # Shell aliases for fixture testing
 ├── lua/claudecode/          # Plugin implementation
 │   ├── server/              # WebSocket server implementation
 │   ├── tools/               # MCP tool implementations and schema management
@@ -118,7 +124,46 @@ make format
 2. Create a feature branch
 3. Implement your changes with tests
 4. Run the test suite to ensure all tests pass
-5. Submit a pull request
+5. **For integrations**: Create a fixture configuration for testing
+6. Submit a pull request
+
+### Integration Testing with Fixtures
+
+When adding support for new integrations (file explorers, terminals, etc.), you **must** provide a fixture configuration for testing:
+
+**Requirements**:
+- Complete Neovim configuration in `fixtures/[integration-name]/`
+- Include plugin dependencies and proper setup
+- Add `dev-claudecode.lua` with development keybindings
+- Test all relevant claudecode.nvim features with the integration
+
+**Usage**:
+```bash
+# Source fixture aliases
+source fixtures/nvim-aliases.sh
+
+# Test with specific integration
+vv nvim-tree  # Start Neovim with nvim-tree configuration
+vv oil        # Start Neovim with oil.nvim configuration
+vv netrw      # Start Neovim with built-in netrw configuration
+
+# List available configurations
+list-configs
+```
+
+**Example fixture structure** (`fixtures/my-integration/`):
+```
+my-integration/
+├── init.lua                    # Main Neovim config
+├── lua/
+│   ├── config/
+│   │   └── lazy.lua           # Plugin manager setup
+│   └── plugins/
+│       ├── dev-claudecode.lua # claudecode.nvim development config
+│       ├── init.lua           # Base plugins
+│       └── my-integration.lua # Integration-specific plugin config
+└── lazy-lock.json             # Plugin lockfile (if using lazy.nvim)
+```
 
 ## Implementation Details
 

fixtures/bin/common.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# common.sh - Shared functions for fixture scripts
+
+# Get available configurations
+get_configs() {
+  local fixtures_dir="$1"
+  find "$fixtures_dir" -maxdepth 1 -type d \
+    ! -name ".*" \
+    ! -name "fixtures" \
+    ! -name "bin" \
+    ! -path "$fixtures_dir" \
+    -printf "%f\n" | sort
+}
+
+# Validate config exists
+validate_config() {
+  local fixtures_dir="$1"
+  local config="$2"
+
+  if [[ ! -d "$fixtures_dir/$config" ]]; then
+    echo "Error: Configuration '$config' not found in fixtures/"
+    echo "Available configs:"
+    get_configs "$fixtures_dir" | while read -r c; do
+      echo "  • $c"
+    done
+    return 1
+  fi
+  return 0
+}
+
+# Interactive config selection
+select_config() {
+  local fixtures_dir="$1"
+
+  if command -v fzf >/dev/null 2>&1; then
+    get_configs "$fixtures_dir" | fzf --prompt="Neovim Configs > " --height=~50% --layout=reverse --border --exit-0
+  else
+    echo "Available configs:"
+    get_configs "$fixtures_dir" | while read -r config; do
+      echo "  • $config"
+    done
+    echo -n "Select config: "
+    read -r config
+    echo "$config"
+  fi
+}
+

fixtures/bin/list-configs

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# list-configs - Show available Neovim configurations
+
+FIXTURES_DIR="$(cd "$(dirname "$(dirname "${BASH_SOURCE[0]}")")" && pwd)"
+
+# Source common functions
+source "$FIXTURES_DIR/bin/common.sh"
+
+echo "Available Neovim test configurations:"
+get_configs "$FIXTURES_DIR" | while read -r config; do
+  if [[ -d "$FIXTURES_DIR/$config" ]]; then
+    echo "  ✓ $config"
+  else
+    echo "  ✗ $config (missing)"
+  fi
+done

fixtures/bin/vv

@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# vv - Start Neovim with fixture configuration
+
+FIXTURES_DIR="$(cd "$(dirname "$(dirname "${BASH_SOURCE[0]}")")" && pwd)"
+
+# Source common functions
+source "$FIXTURES_DIR/bin/common.sh"
+
+# Main logic
+if [[ $# -eq 0 ]]; then
+  config="$(select_config "$FIXTURES_DIR")"
+  [[ -z $config ]] && echo "No config selected" && exit 0
+else
+  config="$1"
+fi
+
+if ! validate_config "$FIXTURES_DIR" "$config"; then
+  exit 1
+fi
+
+# Set environment to use the config directory as if it were ~/.config/nvim
+config_dir="$FIXTURES_DIR/$config"
+init_file="$config_dir/init.lua"
+
+if [[ -f "$init_file" ]]; then
+  echo "Loading config from: $config_dir"
+  (cd "$FIXTURES_DIR" && NVIM_APPNAME="$config" XDG_CONFIG_HOME="$FIXTURES_DIR" nvim "${@:2}")
+else
+  echo "Error: $init_file not found"
+  exit 1
+fi

fixtures/bin/vve

@@ -0,0 +1,44 @@
+#!/bin/bash
+
+# vve - Edit Neovim configuration for a given fixture
+
+FIXTURES_DIR="$(cd "$(dirname "$(dirname "${BASH_SOURCE[0]}")")" && pwd)"
+
+# Source common functions
+source "$FIXTURES_DIR/bin/common.sh"
+
+# Main logic
+if [[ $# -eq 0 ]]; then
+  config="$(select_config "$FIXTURES_DIR")"
+  [[ -z $config ]] && echo "No config selected" && exit 0
+  # Open the config directory for editing
+  config_path="$FIXTURES_DIR/$config"
+else
+  config="$1"
+  # Validate that config is not empty when provided as argument
+  if [[ -z "$config" ]]; then
+    echo "Error: Config name cannot be empty"
+    echo "Usage: vve [config] [file]"
+    echo "Available configs:"
+    get_configs "$FIXTURES_DIR" | while read -r c; do
+      echo "  • $c"
+    done
+    exit 1
+  fi
+  if [[ $# -gt 1 ]]; then
+    # Specific file provided - open that file in the config directory
+    config_path="$FIXTURES_DIR/$config/$2"
+  else
+    # No specific file - open the config directory
+    config_path="$FIXTURES_DIR/$config"
+  fi
+fi
+
+if ! validate_config "$FIXTURES_DIR" "$config"; then
+  exit 1
+fi
+
+echo "Editing config: $config_path"
+
+# Use Neovim to edit the configuration files
+nvim "$config_path"

fixtures/netrw/init.lua

@@ -0,0 +1 @@
+require("config.lazy")

fixtures/netrw/lazy-lock.json

@@ -0,0 +1,4 @@
+{
+  "lazy.nvim": { "branch": "main", "commit": "6c3bda4aca61a13a9c63f1c1d1b16b9d3be90d7a" },
+  "tokyonight.nvim": { "branch": "main", "commit": "057ef5d260c1931f1dffd0f052c685dcd14100a3" }
+}