feat(dev): add symlink setup for testing dev version

Add dev:symlink and dev:unlink scripts to enable seamless testing of
development changes using the global 'ccs' command without needing to
pack/install globally each time.

- scripts/dev-symlink.sh: New script that safely creates symlinks from
  global ccs to dev dist/ccs.js with backup/restore functionality
- package.json: Added dev:symlink and dev:unlink npm scripts
- CONTRIBUTING.md: Updated development setup documentation with
  symlink workflow option

This improves developer experience by allowing immediate testing of
changes with 'ccs <command>' instead of './dist/ccs.js <command>'.

CLAUDE.md

@@ -268,7 +268,9 @@ bun run test:unit         # Unit tests
 ### Local Development
 ```bash
 bun run dev               # Build + start config server (http://localhost:3000)
-./scripts/dev-install.sh  # Build, pack, install globally
+bun run dev:symlink       # Symlink global 'ccs' → dev dist/ccs.js (fast iteration)
+bun run dev:unlink        # Restore original global ccs
+./scripts/dev-install.sh  # Build, pack, install globally (full install)
 rm -rf ~/.ccs             # Clean environment
 ```
 

CONTRIBUTING.md

@@ -265,8 +265,22 @@ cd ccs
 # Create feature branch
 git checkout -b your-feature-name
 
+# Option 1: Test with built binary
+# Test locally with ./dist/ccs.js
+
+# Option 2: Symlink for seamless testing (recommended)
+bun run build
+bun run dev:symlink  # Symlinks global 'ccs' to dev version
+# Now 'ccs' command uses your dev changes!
+
 # Make changes
-# Test locally with ./ccs
+# Test with: ccs <command>
+
+# When done developing:
+bun run dev:unlink   # Restores original global ccs
+
+# Run tests
+# Test with: ccs <command>
 
 # Run tests
 bun run test           # All tests

package.json

@@ -72,6 +72,8 @@
     "test:npm": "bun test tests/npm/",
     "test:native": "bash tests/native/unix/edge-cases.sh",
     "dev": "bun run build:server && bun dist/ccs.js config --dev",
+    "dev:symlink": "bash scripts/dev-symlink.sh",
+    "dev:unlink": "bash scripts/dev-symlink.sh --restore",
     "ui:build": "cd ui && bun run build",
     "ui:preview": "cd ui && bun run preview",
     "ui:validate": "cd ui && bun run validate",

scripts/dev-symlink.sh

@@ -0,0 +1,115 @@
+#!/bin/bash
+# CCS Dev Symlink Setup
+# Creates symlinks for testing dev version with 'ccs' command
+#
+# Usage: ./scripts/dev-symlink.sh [--restore]
+#
+# Without --restore: Creates symlink from global 'ccs' to dist/ccs.js
+# With --restore: Restores original global 'ccs' from backup
+
+set -euo pipefail
+
+RESTORE=false
+
+# Parse arguments
+for arg in "$@"; do
+    case $arg in
+        --restore) RESTORE=true ;;
+        -h|--help)
+            echo "Usage: $0 [--restore]"
+            echo ""
+            echo "Create symlink for dev testing:"
+            echo "  $0"
+            echo ""
+            echo "Restore original global ccs:"
+            echo "  $0 --restore"
+            exit 0
+            ;;
+        *)
+            echo "[X] Unknown option: $arg"
+            echo "Use --help for usage"
+            exit 1
+            ;;
+    esac
+done
+
+# Get to the right directory
+cd "$(dirname "$0")/.."
+
+# Check if dist/ccs.js exists
+if [ ! -f "dist/ccs.js" ]; then
+    echo "[X] ERROR: dist/ccs.js not found. Run 'bun run build' first."
+    exit 1
+fi
+
+# Get absolute path to dev ccs.js
+DEV_CCS_PATH="$(pwd)/dist/ccs.js"
+
+# Find global ccs installation
+GLOBAL_CCS_PATH=$(which ccs 2>/dev/null || true)
+
+if [ -z "$GLOBAL_CCS_PATH" ]; then
+    echo "[X] ERROR: No global 'ccs' installation found."
+    echo "Install CCS globally first: npm install -g @kaitranntt/ccs"
+    exit 1
+fi
+
+echo "[i] Found global ccs at: $GLOBAL_CCS_PATH"
+
+if [ "$RESTORE" = true ]; then
+    # Restore original ccs from backup
+    BACKUP_PATH="${GLOBAL_CCS_PATH}.backup-dev"
+
+    if [ ! -f "$BACKUP_PATH" ] && [ ! -L "$BACKUP_PATH" ]; then
+        echo "[X] ERROR: No backup found at $BACKUP_PATH"
+        echo "Cannot restore - backup may have been deleted"
+        exit 1
+    fi
+
+    echo "[i] Restoring original ccs from backup..."
+    rm -f "$GLOBAL_CCS_PATH"
+    if [ -L "$BACKUP_PATH" ]; then
+        # Restore symlink
+        cp -P "$BACKUP_PATH" "$GLOBAL_CCS_PATH"
+    else
+        # Restore regular file
+        cp "$BACKUP_PATH" "$GLOBAL_CCS_PATH"
+    fi
+    chmod +x "$GLOBAL_CCS_PATH"
+    rm -f "$BACKUP_PATH"
+
+    echo "[OK] Restored original global ccs"
+    echo "Run 'ccs --version' to verify"
+    exit 0
+fi
+
+# Check if already symlinked to our dev version
+if [ -L "$GLOBAL_CCS_PATH" ]; then
+    CURRENT_TARGET=$(readlink "$GLOBAL_CCS_PATH" 2>/dev/null || true)
+    if [ "$CURRENT_TARGET" = "$DEV_CCS_PATH" ]; then
+        echo "[OK] Already symlinked to dev version"
+        exit 0
+    fi
+fi
+
+# Create backup of current global ccs
+BACKUP_PATH="${GLOBAL_CCS_PATH}.backup-dev"
+if [ -f "$BACKUP_PATH" ] || [ -L "$BACKUP_PATH" ]; then
+    echo "[i] Backup already exists, skipping backup creation"
+else
+    echo "[i] Creating backup of current global ccs..."
+    cp -P "$GLOBAL_CCS_PATH" "$BACKUP_PATH"
+    echo "[OK] Backup created at: $BACKUP_PATH"
+fi
+
+# Create symlink
+echo "[i] Creating symlink to dev version..."
+rm -f "$GLOBAL_CCS_PATH"
+ln -s "$DEV_CCS_PATH" "$GLOBAL_CCS_PATH"
+
+echo "[OK] Symlinked global 'ccs' to dev version"
+echo ""
+echo "Now you can test dev changes with: ccs <command>"
+echo "To restore original: $0 --restore"
+echo ""
+echo "Test with: ccs --version"