feat(init): add Claude Code installation and version checks

CLAUDE.md

@@ -141,6 +141,35 @@ The context directory feature allows MCP servers to store data:
 - Servers can opt-in to git exposure via `exposeContextToGit: true`
 - See `docs/context-directory.md` for details
 
+### Basic Memory Conventions
+
+When using Basic Memory MCP for project notes and plans:
+
+**File Naming**:
+- Use kebab-case for filenames (e.g., `claude-code-checks.md`, `mcp-authentication-setup.md`)
+- Titles in frontmatter should use Title Case (e.g., `title: "Issue 1: Add Claude Code Installation and Version Checks"`)
+
+**Frontmatter Requirements**:
+```yaml
+---
+title: "Issue Title in Title Case"
+kind: Plan  # or Note, Guide, etc.
+created_at: 2025-10-16T15:00:00.000Z
+status: active  # draft, active, complete
+issue_permalink: https://github.com/org/repo/issues/1
+pr_permalink: https://github.com/org/repo/pull/10
+tags:
+  - kebab-case-tag
+  - another-tag
+---
+```
+
+**Plan Structure**:
+- Use status emojis: 📌 BACKLOG, ⏳ IN PROGRESS, ✅ COMPLETED
+- Include observations and relations sections
+- Reference source files and implementations
+- Update status as work progresses
+
 ## Distribution
 
 This project uses Homebrew for distribution:
@@ -160,10 +189,45 @@ This project uses Homebrew for distribution:
 
 ## Available Commands
 
-- `ftk init` - Interactive MCP server setup
+- `ftk init` - Interactive MCP server setup with automatic Claude Code installation/upgrade
 - `ftk --version` - Show version
 - `ftk --help` - Show help
 
+### Claude Code Installation Checking
+
+The `ftk init` command includes comprehensive Claude Code installation checking:
+
+**Scenarios Handled:**
+
+1. **Not Installed**: Offers automatic installation with command preview
+   - Uses official npm method: `npm install -g @anthropic-ai/claude-code`
+   - Alternative methods available (brew, winget)
+   - Requires user confirmation before executing
+   - Re-validates installation after completion
+
+2. **Outdated Version**: Offers automatic upgrade with command preview
+   - Auto-detects installation method (npm, brew, etc.)
+   - Shows appropriate upgrade command
+   - Displays changelog with changes between versions
+   - Requires user confirmation before executing
+   - Allows continuing with old version or cancelling
+
+3. **Upgrade Available**: Optionally offers upgrade to latest version
+   - Checks package manager for newer versions
+   - Shows available version and changelog
+   - Displays what's new between current and latest
+   - Non-blocking - setup continues regardless
+
+**Installation Method Detection:**
+- Automatically detects if Claude Code was installed via npm or brew
+- Uses npm commands for npm installations
+- Uses brew commands for Homebrew installations
+- Defaults to npm (official method) for new installations
+
+**Flags:**
+- `--skip-checks` - Skip Claude Code version checking entirely
+- `--no-prompt` - Show instructions but don't offer automatic install/upgrade
+
 ## Development Workflow
 
 ### Feature Branch Pattern
@@ -189,13 +253,25 @@ All features MUST be developed in dedicated feature branches following this nami
 
 ### Local Development
 
+**Using Justfile (Recommended):**
+```bash
+just dev init              # Run ftk in development mode
+just check                 # Type check
+just validate              # Type check + lint + format check
+just quick-test            # Validate + compile + unit tests
+just vm-setup              # Setup Tart VM for integration testing
+```
+
+**Using Deno directly:**
 1. **Local testing**: `deno task dev init`
 2. **Type checking**: `deno check src/main.ts`
 3. **Formatting**: `deno fmt`
 4. **Linting**: `deno lint`
 5. **Compile**: `deno task compile` or `deno task compile:all`
 6. **Check CI status**: `gh run list` or `gh run view`
 
+**See [docs/justfile.md](docs/justfile.md) for complete command reference.**
+
 ## Release Workflow
 
 1. Run `./scripts/release.sh <version>`

Justfile

@@ -0,0 +1,238 @@
+# Fluent Toolkit Development Tasks
+# https://github.com/casey/just
+
+# Default recipe to display help
+default:
+    @just --list
+
+# Development Tasks
+# ==================
+
+# Run ftk init in development mode
+dev *ARGS:
+    deno run --allow-all --unstable-raw-imports src/main.ts {{ARGS}}
+
+# Type check the project
+check:
+    deno check --unstable-raw-imports src/main.ts
+
+# Format code
+fmt:
+    deno fmt
+
+# Lint code
+lint:
+    deno lint
+
+# Run all checks (type, lint, format)
+validate: check lint
+    deno fmt --check
+
+# Compile binaries
+compile:
+    deno task compile
+
+# Compile for all platforms
+compile-all:
+    deno task compile:all
+
+# Testing
+# ==================
+
+# Run unit tests
+test-unit:
+    deno run --allow-all tests/unit/**/*.test.ts
+
+# Run Claude Code check unit tests
+test-claude-checks:
+    @echo "Running version scenarios..."
+    @deno run --allow-all tests/unit/claude-code-checks/claude-version-scenarios.test.ts
+    @echo "\nRunning changelog tests..."
+    @deno run --allow-net tests/unit/claude-code-checks/changelog.test.ts
+    @echo "\nRunning install method detection..."
+    @deno run --allow-all tests/unit/claude-code-checks/install-method-detection.test.ts
+
+# Run integration tests (requires Tart VM setup)
+test-integration:
+    deno task test:integration
+
+# Run server validation tests (requires Tart VM with Claude Code installed)
+test-server-validation:
+    deno test --allow-all tests/integration/scenarios/server-validation/
+
+# Run specific server validation test
+test-server SERVER:
+    deno test --allow-all tests/integration/scenarios/server-validation/{{SERVER}}.test.ts
+
+# VM Management (Tart)
+# ==================
+
+# Install Tart (macOS only)
+install-tart:
+    @echo "Installing Tart..."
+    brew install tart
+
+# Pull base macOS image
+vm-pull-base:
+    @echo "Pulling macOS Sequoia base image..."
+    tart clone ghcr.io/cirruslabs/macos-sequoia-base:latest sequoia-base
+
+# Create and configure FTK test VM
+vm-setup VM_NAME="FTK-test": vm-pull-base
+    @echo "Creating VM: {{VM_NAME}}"
+    @if tart list | grep -q "{{VM_NAME}}"; then \
+        echo "VM {{VM_NAME}} already exists. Deleting..."; \
+        tart delete {{VM_NAME}}; \
+    fi
+    tart clone sequoia-base {{VM_NAME}}
+    @echo "\nStarting VM..."
+    tart run --no-graphics {{VM_NAME}} &
+    @sleep 10
+    @echo "\nConfiguring Homebrew PATH..."
+    tart exec {{VM_NAME}} /bin/zsh -c "echo 'eval \"\$$(/opt/homebrew/bin/brew shellenv)\"' >> ~/.zshrc"
+    @echo "\nInstalling dependencies (node, python, uv)..."
+    tart exec {{VM_NAME}} /bin/zsh -c "source ~/.zshrc && brew install node python uv"
+    @echo "\n✅ VM {{VM_NAME}} is ready for testing"
+    @echo "\nVM IP: $$(tart ip {{VM_NAME}})"
+    @echo "\nTo connect: ssh admin@$$(tart ip {{VM_NAME}})"
+    @echo "To stop: tart stop {{VM_NAME}}"
+
+# Start test VM
+vm-start VM_NAME="FTK-test":
+    @echo "Starting VM: {{VM_NAME}}"
+    tart run --no-graphics {{VM_NAME}} &
+    @sleep 5
+    @echo "VM IP: $$(tart ip {{VM_NAME}})"
+
+# Stop test VM
+vm-stop VM_NAME="FTK-test":
+    @echo "Stopping VM: {{VM_NAME}}"
+    tart stop {{VM_NAME}}
+
+# Get VM IP address
+vm-ip VM_NAME="FTK-test":
+    @tart ip {{VM_NAME}}
+
+# SSH into test VM
+vm-ssh VM_NAME="FTK-test":
+    @ssh admin@$$(tart ip {{VM_NAME}})
+
+# Delete test VM
+vm-delete VM_NAME="FTK-test":
+    @echo "Deleting VM: {{VM_NAME}}"
+    @if tart list | grep -q "{{VM_NAME}}"; then \
+        tart stop {{VM_NAME}} 2>/dev/null || true; \
+        tart delete {{VM_NAME}}; \
+        echo "✅ VM {{VM_NAME}} deleted"; \
+    else \
+        echo "VM {{VM_NAME}} does not exist"; \
+    fi
+
+# List all VMs
+vm-list:
+    @tart list
+
+# Clean up all test VMs (dangerous!)
+vm-clean:
+    @echo "⚠️  This will delete ALL VMs starting with 'FTK-'"
+    @read -p "Are you sure? [y/N] " -n 1 -r; \
+    if [[ $$REPLY =~ ^[Yy]$$ ]]; then \
+        echo "\nCleaning up test VMs..."; \
+        tart list | grep "FTK-" | awk '{print $$1}' | xargs -I {} just vm-delete {}; \
+    else \
+        echo "\nCancelled"; \
+    fi
+
+# Install ftk in VM from local build
+vm-install-ftk VM_NAME="FTK-test": compile
+    #!/usr/bin/env bash
+    set -euo pipefail
+    echo "Installing ftk in VM: {{VM_NAME}}"
+    VM_IP=$(tart ip {{VM_NAME}})
+    scp -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+        bin/ftk admin@$VM_IP:/tmp/ftk
+    ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+        admin@$VM_IP "sudo mv /tmp/ftk /usr/local/bin/ftk && sudo chmod +x /usr/local/bin/ftk"
+    echo "✅ ftk installed in VM"
+
+# Test ftk in VM
+vm-test-ftk VM_NAME="FTK-test" WORKDIR="/tmp/ftk-test":
+    @echo "Testing ftk in VM: {{VM_NAME}}"
+    @ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+        admin@$$(tart ip {{VM_NAME}}) \
+        "rm -rf {{WORKDIR}} && mkdir -p {{WORKDIR}} && cd {{WORKDIR}} && ftk init --no-prompt"
+
+# Setup VM with all prerequisites for server validation tests
+vm-test-setup VM_NAME="FTK-test": vm-start vm-install-ftk
+    #!/usr/bin/env bash
+    set -euo pipefail
+    echo "Installing Claude Code in VM..."
+    VM_IP=$(tart ip {{VM_NAME}})
+    ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+        admin@$VM_IP \
+        "source ~/.zshrc && npm install -g @anthropic-ai/claude-code"
+    echo ""
+    echo "✅ VM ready for server validation tests"
+    echo ""
+    echo "VM IP: $VM_IP"
+    echo "To run tests: TEST_VM_IP=$VM_IP just test-server-validation"
+
+# Release Tasks
+# ==================
+
+# Create a new release
+release VERSION:
+    @echo "Creating release {{VERSION}}"
+    ./scripts/release.sh {{VERSION}}
+
+# Update Homebrew formula checksums
+update-formula:
+    @echo "Updating Homebrew formula checksums..."
+    @echo "Run this after creating GitHub release with binaries"
+    @echo "1. Download artifacts from GitHub release"
+    @echo "2. Run: shasum -a 256 ftk-*"
+    @echo "3. Update Formula/fluent-toolkit.rb"
+
+# Documentation
+# ==================
+
+# Format markdown files with prettier
+fmt-docs:
+    npx prettier --write "**/*.md"
+
+# Format Basic Memory notes
+fmt-memory:
+    npx prettier --write "context/basic-memory/**/*.md"
+
+# Utility Tasks
+# ==================
+
+# Clean build artifacts
+clean:
+    rm -f ftk ftk-*
+    rm -rf .ftk/
+
+# Show project info
+info:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    echo "Fluent Toolkit Development Environment"
+    echo "======================================"
+    echo ""
+    echo "Deno version: $(deno --version | head -1)"
+    echo "Node version: $(node --version 2>/dev/null || echo 'not installed')"
+    echo "Tart version: $(tart --version 2>/dev/null || echo 'not installed')"
+    echo ""
+    echo "Run 'just' to see available commands"
+
+# Open project in editor
+edit:
+    code .
+
+# Quick test workflow: validate, compile, and test
+quick-test: validate compile test-claude-checks
+    @echo "\n✅ Quick test completed successfully"
+
+# Full test workflow: validate, compile, unit tests, integration tests
+full-test: validate compile test-unit test-integration
+    @echo "\n✅ Full test completed successfully"

README.md

@@ -4,6 +4,13 @@
 
 MCP server setup toolkit for Claude Code. Simplifies the installation and configuration of Model Context Protocol servers.
 
+## Prerequisites
+
+- **Claude Code 1.0.0+** - [Installation Guide](https://docs.claude.com/claude-code/install)
+- Node.js or Python (depending on which MCP servers you install)
+
+The `ftk init` command will automatically check for Claude Code and guide you through installation if needed.
+
 ## Installation
 
 ### Homebrew (macOS/Linux)
@@ -27,17 +34,34 @@ ftk init
 
 The interactive wizard will:
 
+- Verify Claude Code is installed and up to date
 - Let you select which MCP servers to install
 - Check for required system dependencies
 - Prompt for API keys and secrets
 - Generate `.mcp.json` configuration
 - Update `CLAUDE.md` with usage instructions
 - Create optional context directory for AI resources
 
+### Command Options
+
+```bash
+ftk init [options]
+
+Options:
+  -f, --force              Force re-initialization even if already configured
+  --skip-validation        Skip dependency validation checks
+  --skip-checks           Skip Claude Code installation and version checks
+  -s, --servers <list>     Specify servers to install (comma-separated)
+  --no-prompt             Accept all defaults without prompting
+```
+
+Use `--skip-checks` to bypass the Claude Code version check (useful for CI/CD or advanced users).
+
 ## Features
 
 ### Currently Implemented
 
+- ✅ **Claude Code version checking** - Ensures compatible version is installed
 - ✅ **Interactive setup wizard** - Guided MCP server installation
 - ✅ **Modular server architecture** - Easy to add new servers
 - ✅ **Dependency checking** - Validates system requirements before installation