mirror of
https://github.com/alirezarezvani/ClaudeForge.git
synced 2026-07-04 02:43:15 -04:00
feat(v2.0.0): migrate to Claude Code v2.1.4+ architecture (#22)
This commit is contained in:
Alireza Rezvani
GitHub
@@ -0,0 +1,449 @@
|
||||
# Local Testing Guide for ClaudeForge v2.0.0
|
||||
|
||||
This guide walks you through testing the v2.1.4 migration on your local machine before creating a PR.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Claude Code 2.1.0+ installed
|
||||
- Current working directory: `/Users/rezarezvani/projects/ClaudeForge`
|
||||
- Feature branch checked out: `feature/migrate-v2.1.4-architecture`
|
||||
|
||||
---
|
||||
|
||||
## Testing Workflow
|
||||
|
||||
### Step 1: Backup Your Current ClaudeForge Installation
|
||||
|
||||
If you have ClaudeForge installed, back it up first:
|
||||
|
||||
```bash
|
||||
# Check if you have existing installation
|
||||
ls -la ~/.claude/skills/claudeforge-skill 2>/dev/null && echo "Found existing installation"
|
||||
|
||||
# Backup (if exists)
|
||||
cp -r ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill.pre-v2-test 2>/dev/null
|
||||
cp -r ~/.claude/commands/enhance-claude-md ~/.claude/commands/enhance-claude-md.pre-v2-test 2>/dev/null
|
||||
cp ~/.claude/agents/claude-md-guardian.md ~/.claude/agents/claude-md-guardian.md.pre-v2-test 2>/dev/null
|
||||
|
||||
echo "✓ Backup complete (if installation existed)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Test Fresh Installation
|
||||
|
||||
Test installing from scratch:
|
||||
|
||||
```bash
|
||||
# Remove any existing installation
|
||||
rm -rf ~/.claude/skills/claudeforge-skill
|
||||
rm -rf ~/.claude/commands/enhance-claude-md
|
||||
rm ~/.claude/agents/claude-md-guardian.md
|
||||
|
||||
# Run the new installer
|
||||
./install.sh
|
||||
|
||||
# Choose option 1 (user-level)
|
||||
# Press Y to confirm installation
|
||||
# Press N for quality hooks (we're just testing core features)
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
ℹ Checking Claude Code version...
|
||||
✓ Claude Code version 2.1.4 detected
|
||||
ℹ Where would you like to install ClaudeForge?
|
||||
...
|
||||
ℹ Validating v2.1.4 compatibility...
|
||||
✓ Guardian agent hooks configured
|
||||
✓ v2.1.4 compatibility validated
|
||||
✓ Installation completed successfully!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Run Validation Script
|
||||
|
||||
Verify the installation is correct:
|
||||
|
||||
```bash
|
||||
# Run automated validation
|
||||
./test/validate_migration.sh
|
||||
```
|
||||
|
||||
**Expected Output:**
|
||||
```
|
||||
=== ClaudeForge v2.1.4 Migration Validation ===
|
||||
|
||||
Test 1: File Existence
|
||||
----------------------
|
||||
✓ Skill file exists
|
||||
✓ Command file exists
|
||||
✓ Agent file exists
|
||||
|
||||
Test 2: v2.1.4 Syntax Validation
|
||||
---------------------------------
|
||||
✓ Skill uses permissions syntax
|
||||
✓ Command uses permissions syntax
|
||||
✓ Agent uses permissions syntax
|
||||
|
||||
Test 3: Hooks Configuration
|
||||
---------------------------
|
||||
✓ Agent has hooks configured
|
||||
✓ SessionStart hook present
|
||||
✓ PreToolUse hook present
|
||||
✓ PostToolUse hook present
|
||||
|
||||
Test 4: Fork-Safe Mode
|
||||
----------------------
|
||||
✓ Fork-safe mode enabled
|
||||
|
||||
Test 5: Python Modules Integrity
|
||||
--------------------------------
|
||||
✓ analyzer.py present
|
||||
✓ validator.py present
|
||||
✓ generator.py present
|
||||
✓ template_selector.py present
|
||||
✓ workflow.py present
|
||||
|
||||
Test 6: Legacy Syntax Cleanup
|
||||
-----------------------------
|
||||
✓ Agent has no legacy 'tools:' field
|
||||
✓ Command has no legacy 'allowed-tools:' field
|
||||
|
||||
Test 7: Documentation
|
||||
--------------------
|
||||
✓ Migration guide exists
|
||||
✓ CHANGELOG has v2.0.0 entry
|
||||
✓ README references v2.1.4
|
||||
|
||||
Test 8: Example Files Unchanged
|
||||
-------------------------------
|
||||
✓ Example files present
|
||||
|
||||
===================================
|
||||
Validation Complete
|
||||
===================================
|
||||
Passed: 18
|
||||
Failed: 0
|
||||
|
||||
✅ All tests passed! Migration successful.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Test Functionality
|
||||
|
||||
Test that the skill/command still works:
|
||||
|
||||
```bash
|
||||
# Start Claude Code
|
||||
claude
|
||||
|
||||
# Test the slash command
|
||||
/enhance-claude-md
|
||||
```
|
||||
|
||||
**What to expect:**
|
||||
1. Hook message appears: `"Starting CLAUDE.md enhancement workflow"`
|
||||
2. 3-phase workflow runs normally (Discovery → Analysis → Task)
|
||||
3. Skill is invoked and works correctly
|
||||
|
||||
**Exit Claude Code** when done testing:
|
||||
```
|
||||
exit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5: Test SessionStart Hook
|
||||
|
||||
Test that the guardian agent SessionStart hook fires:
|
||||
|
||||
```bash
|
||||
# Start a new Claude Code session
|
||||
claude
|
||||
```
|
||||
|
||||
**Expected on startup:**
|
||||
You should see:
|
||||
```
|
||||
Guardian: Checking for CLAUDE.md updates...
|
||||
```
|
||||
|
||||
This confirms the SessionStart hook is working.
|
||||
|
||||
**Exit when done:**
|
||||
```
|
||||
exit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 6: Manually Verify Files
|
||||
|
||||
Double-check the installed files have correct syntax:
|
||||
|
||||
```bash
|
||||
# Check skill frontmatter
|
||||
head -20 ~/.claude/skills/claudeforge-skill/SKILL.md
|
||||
|
||||
# Should see:
|
||||
# ---
|
||||
# name: claude-md-enhancer
|
||||
# permissions:
|
||||
# allow:
|
||||
# - Read
|
||||
# - Write
|
||||
# ...
|
||||
|
||||
# Check agent frontmatter
|
||||
head -30 ~/.claude/agents/claude-md-guardian.md
|
||||
|
||||
# Should see:
|
||||
# ---
|
||||
# name: claude-md-guardian
|
||||
# permissions:
|
||||
# allow:
|
||||
# - Bash
|
||||
# - Read
|
||||
# ...
|
||||
# hooks:
|
||||
# - event: SessionStart
|
||||
# ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 7: Test Migration from v1.x (Optional)
|
||||
|
||||
If you want to test the migration logic:
|
||||
|
||||
```bash
|
||||
# Create a mock v1.x installation
|
||||
mkdir -p ~/.claude/skills/claudeforge-skill-mock
|
||||
cat > ~/.claude/skills/claudeforge-skill-mock/SKILL.md <<'EOF'
|
||||
---
|
||||
name: claude-md-enhancer
|
||||
tools: Bash, Read, Write
|
||||
---
|
||||
Old v1.x syntax
|
||||
EOF
|
||||
|
||||
# Temporarily rename to simulate v1.x
|
||||
mv ~/.claude/skills/claudeforge-skill ~/.claude/skills/claudeforge-skill-real
|
||||
mv ~/.claude/skills/claudeforge-skill-mock ~/.claude/skills/claudeforge-skill
|
||||
|
||||
# Run installer (should detect and backup v1.x)
|
||||
./install.sh
|
||||
|
||||
# Check backup was created
|
||||
ls ~/.claude/skills/claudeforge-skill.v1_backup* || ls ~/.claude/skills/claudeforge-skill.backup.*
|
||||
|
||||
# Verify new syntax
|
||||
grep "permissions:" ~/.claude/skills/claudeforge-skill/SKILL.md
|
||||
|
||||
# Restore real installation
|
||||
rm -rf ~/.claude/skills/claudeforge-skill
|
||||
mv ~/.claude/skills/claudeforge-skill-real ~/.claude/skills/claudeforge-skill
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 8: Test Rollback Script
|
||||
|
||||
Test that rollback works (using the backup from Step 7):
|
||||
|
||||
```bash
|
||||
# If you have backups from Step 7
|
||||
./test/rollback.sh
|
||||
|
||||
# Verify it restored v1.x syntax
|
||||
head -10 ~/.claude/skills/claudeforge-skill/SKILL.md
|
||||
|
||||
# Then reinstall v2.0 for continued testing
|
||||
./install.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 9: Test Python Modules Still Work
|
||||
|
||||
Verify Python modules weren't accidentally broken:
|
||||
|
||||
```bash
|
||||
# Test Python compilation
|
||||
python3 -m py_compile skill/analyzer.py
|
||||
python3 -m py_compile skill/validator.py
|
||||
python3 -m py_compile skill/generator.py
|
||||
python3 -m py_compile skill/template_selector.py
|
||||
python3 -m py_compile skill/workflow.py
|
||||
|
||||
echo "✓ All Python modules compile successfully"
|
||||
|
||||
# Test imports (from skill directory)
|
||||
cd skill
|
||||
python3 -c "from analyzer import CLAUDEMDAnalyzer; print('✓ analyzer.py imports')"
|
||||
python3 -c "from validator import BestPracticesValidator; print('✓ validator.py imports')"
|
||||
python3 -c "from generator import ContentGenerator; print('✓ generator.py imports')"
|
||||
python3 -c "from template_selector import TemplateSelector; print('✓ template_selector.py imports')"
|
||||
python3 -c "from workflow import InitializationWorkflow; print('✓ workflow.py imports')"
|
||||
cd ..
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 10: Test in a Real Project
|
||||
|
||||
Test the skill on an actual project:
|
||||
|
||||
```bash
|
||||
# Create a test project
|
||||
mkdir -p /tmp/test-claude-project
|
||||
cd /tmp/test-claude-project
|
||||
git init
|
||||
npm init -y # Or create any project
|
||||
|
||||
# Start Claude Code
|
||||
claude
|
||||
|
||||
# Test the enhancement command
|
||||
/enhance-claude-md
|
||||
|
||||
# Follow the workflow and verify:
|
||||
# 1. Discovery phase works
|
||||
# 2. Analysis runs correctly
|
||||
# 3. CLAUDE.md is generated with correct format
|
||||
# 4. No errors or warnings
|
||||
|
||||
# Exit and clean up
|
||||
exit
|
||||
cd /Users/rezarezvani/projects/ClaudeForge
|
||||
rm -rf /tmp/test-claude-project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Test Checklist
|
||||
|
||||
Use this checklist for rapid validation:
|
||||
|
||||
- [ ] `./install.sh` runs without errors
|
||||
- [ ] Version detection works (shows your Claude Code version)
|
||||
- [ ] `./test/validate_migration.sh` shows all tests passing (18/18)
|
||||
- [ ] `/enhance-claude-md` command works in Claude Code
|
||||
- [ ] SessionStart hook fires (see "Guardian: Checking..." on startup)
|
||||
- [ ] Python modules compile without errors
|
||||
- [ ] `./test/rollback.sh` successfully restores backups
|
||||
- [ ] Documentation renders correctly (`docs/MIGRATION_V2.md`)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Local Tests
|
||||
|
||||
### "Command not found: claude"
|
||||
|
||||
```bash
|
||||
# Check if Claude Code is installed
|
||||
which claude
|
||||
|
||||
# If not found, install Claude Code first
|
||||
# Then retry testing
|
||||
```
|
||||
|
||||
### "Permission denied" when running scripts
|
||||
|
||||
```bash
|
||||
# Make scripts executable
|
||||
chmod +x test/validate_migration.sh
|
||||
chmod +x test/rollback.sh
|
||||
chmod +x install.sh
|
||||
```
|
||||
|
||||
### "Python module import failed"
|
||||
|
||||
```bash
|
||||
# Ensure you're in the skill directory
|
||||
cd skill
|
||||
python3 -c "import sys; print(sys.path)"
|
||||
cd ..
|
||||
```
|
||||
|
||||
### Hooks don't fire
|
||||
|
||||
- Hooks require Claude Code 2.1.0+
|
||||
- Check version: `claude --version`
|
||||
- Restart Claude Code completely (not just exit/claude)
|
||||
- Close terminal and open a new one
|
||||
|
||||
---
|
||||
|
||||
## After Testing Successfully
|
||||
|
||||
Once all tests pass:
|
||||
|
||||
1. **Restore your original installation** (if you want to keep using v1.x):
|
||||
```bash
|
||||
./test/rollback.sh
|
||||
# Or manually restore from .pre-v2-test backups
|
||||
```
|
||||
|
||||
2. **Keep v2.0 installed** (if you want to use the new version):
|
||||
```bash
|
||||
# Already installed, just use it!
|
||||
claude
|
||||
/enhance-claude-md
|
||||
```
|
||||
|
||||
3. **Create the PR**:
|
||||
```bash
|
||||
gh pr create --base dev --title "feat(v2.0.0): migrate to Claude Code v2.1.4+ architecture"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Test Results Log
|
||||
|
||||
Keep track of your test results:
|
||||
|
||||
| Test | Result | Notes |
|
||||
|------|--------|-------|
|
||||
| Fresh install | ☐ Pass ☐ Fail | |
|
||||
| Validation script | ☐ Pass ☐ Fail | |
|
||||
| /enhance-claude-md command | ☐ Pass ☐ Fail | |
|
||||
| SessionStart hook | ☐ Pass ☐ Fail | |
|
||||
| Python modules | ☐ Pass ☐ Fail | |
|
||||
| Real project test | ☐ Pass ☐ Fail | |
|
||||
| Rollback script | ☐ Pass ☐ Fail | |
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues during testing:
|
||||
|
||||
1. Check the validation script output for specific failures
|
||||
2. Review `docs/MIGRATION_V2.md` troubleshooting section
|
||||
3. Check Claude Code version: `claude --version`
|
||||
4. Verify branch: `git branch` (should show `feature/migrate-v2.1.4-architecture`)
|
||||
|
||||
---
|
||||
|
||||
## Pro Tip: Test in a Docker Container
|
||||
|
||||
For completely isolated testing:
|
||||
|
||||
```bash
|
||||
# Use a Docker container with Claude Code installed
|
||||
docker run -it -v $(pwd):/workspace ubuntu:latest bash
|
||||
|
||||
# Inside container:
|
||||
cd /workspace
|
||||
# Install Claude Code
|
||||
# Run ./install.sh
|
||||
# Run ./test/validate_migration.sh
|
||||
```
|
||||
|
||||
This ensures no interference from your existing setup.
|
||||
Reference in New Issue
Block a user