feat: Major directory reorganization and cleanup
Reorganized project structure for better maintainability and reduced disk usage by 95.9% (11 GB -> 451 MB). Directory Reorganization (85% reduction in root files): - Created docs/ with subdirectories (deployment, testing, database, etc.) - Created infrastructure/vpn-configs/ for VPN scripts - Moved 90+ files from root to organized locations - Archived obsolete documentation (context system, offline mode, zombie debugging) - Moved all test files to tests/ directory - Root directory: 119 files -> 18 files Disk Cleanup (10.55 GB recovered): - Deleted Rust build artifacts: 9.6 GB (target/ directories) - Deleted Python virtual environments: 161 MB (venv/ directories) - Deleted Python cache: 50 KB (__pycache__/) New Structure: - docs/ - All documentation organized by category - docs/archives/ - Obsolete but preserved documentation - infrastructure/ - VPN configs and SSH setup - tests/ - All test files consolidated - logs/ - Ready for future logs Benefits: - Cleaner root directory (18 vs 119 files) - Logical organization of documentation - 95.9% disk space reduction - Faster navigation and discovery - Better portability (build artifacts excluded) Build artifacts can be regenerated: - Rust: cargo build --release (5-15 min per project) - Python: pip install -r requirements.txt (2-3 min) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,445 @@
|
||||
# Offline Mode Test Procedure
|
||||
|
||||
**Version:** 2.0
|
||||
**Date:** 2026-01-17
|
||||
**System Status:** ✅ All Components Installed and Ready
|
||||
|
||||
---
|
||||
|
||||
## Pre-Test Verification (COMPLETED)
|
||||
|
||||
### ✅ Infrastructure Check
|
||||
```bash
|
||||
# Verified directories exist
|
||||
ls -la .claude/context-cache/ # ✅ Exists
|
||||
ls -la .claude/context-queue/ # ✅ Exists (pending, uploaded, failed)
|
||||
|
||||
# Verified v2 hooks installed
|
||||
head -3 .claude/hooks/user-prompt-submit # ✅ v2 with offline support
|
||||
head -3 .claude/hooks/task-complete # ✅ v2 with offline support
|
||||
head -3 .claude/hooks/sync-contexts # ✅ Sync script ready
|
||||
|
||||
# Verified configuration
|
||||
grep CLAUDE_API_URL .claude/context-recall-config.env
|
||||
# ✅ Output: CLAUDE_API_URL=http://172.16.3.30:8001
|
||||
|
||||
# Verified gitignore
|
||||
grep context-cache .gitignore # ✅ Present
|
||||
grep context-queue .gitignore # ✅ Present
|
||||
```
|
||||
|
||||
### ✅ Current System Status
|
||||
- **API:** http://172.16.3.30:8001 (ONLINE)
|
||||
- **Database:** 172.16.3.30:3306 (ONLINE)
|
||||
- **Health Check:** {"status":"healthy","database":"connected"}
|
||||
- **Hooks:** V2 (offline-capable)
|
||||
- **Storage:** Ready
|
||||
|
||||
---
|
||||
|
||||
## Test Procedure
|
||||
|
||||
### Phase 1: Baseline Test (Online Mode)
|
||||
|
||||
**Purpose:** Verify normal operation before testing offline
|
||||
|
||||
```bash
|
||||
# 1. Open Claude Code in D:\ClaudeTools
|
||||
cd D:\ClaudeTools
|
||||
|
||||
# 2. Send a test message to Claude
|
||||
# Expected output should include:
|
||||
# <!-- Context Recall: Retrieved X relevant context(s) from API -->
|
||||
# ## 📚 Previous Context
|
||||
|
||||
# 3. Check that context was cached
|
||||
PROJECT_ID=$(git config --local claude.projectid 2>/dev/null || git config --get remote.origin.url | md5sum | cut -d' ' -f1)
|
||||
ls -la .claude/context-cache/$PROJECT_ID/
|
||||
# Expected: latest.json and last_updated files
|
||||
|
||||
# 4. Verify cache contents
|
||||
cat .claude/context-cache/$PROJECT_ID/latest.json | python -m json.tool
|
||||
# Expected: Array of context objects with titles, summaries, scores
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Context retrieved from API
|
||||
- ✅ Cache file created with timestamp
|
||||
- ✅ Context injected into conversation
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Offline Mode Test (Cache Fallback)
|
||||
|
||||
**Purpose:** Verify system uses cached context when API unavailable
|
||||
|
||||
```bash
|
||||
# 1. SSH to RMM server
|
||||
ssh guru@172.16.3.30
|
||||
|
||||
# 2. Stop the API service
|
||||
sudo systemctl stop claudetools-api
|
||||
|
||||
# 3. Verify API is stopped
|
||||
sudo systemctl status claudetools-api --no-pager
|
||||
# Expected: Active: inactive (dead)
|
||||
|
||||
# 4. Exit SSH
|
||||
exit
|
||||
|
||||
# 5. Back on Windows - test context recall
|
||||
# Open Claude Code and send a message
|
||||
|
||||
# Expected output:
|
||||
# <!-- Context Recall: Retrieved X relevant context(s) from LOCAL CACHE (offline mode) -->
|
||||
# ## 📚 Previous Context
|
||||
# ⚠️ **Offline Mode** - Using cached context (API unavailable)
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Hook detects API unavailable
|
||||
- ✅ Falls back to cached context
|
||||
- ✅ Clear "Offline Mode" warning displayed
|
||||
- ✅ Conversation continues with cached context
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Context Queuing Test (Save Fallback)
|
||||
|
||||
**Purpose:** Verify contexts queue locally when API unavailable
|
||||
|
||||
```bash
|
||||
# 1. API should still be stopped from Phase 2
|
||||
|
||||
# 2. Complete a task in Claude Code
|
||||
# (This triggers task-complete hook)
|
||||
|
||||
# Expected stderr output:
|
||||
# ⚠ Context queued locally (API unavailable) - will sync when online
|
||||
|
||||
# 3. Check queue directory
|
||||
ls -la .claude/context-queue/pending/
|
||||
# Expected: One or more .json files with timestamp names
|
||||
# Example: claudetools_20260117_143022_context.json
|
||||
|
||||
# 4. View queued context
|
||||
cat .claude/context-queue/pending/*.json | python -m json.tool
|
||||
# Expected: JSON with project_id, context_type, title, dense_summary, etc.
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Context save attempt fails gracefully
|
||||
- ✅ Context queued in pending/ directory
|
||||
- ✅ User warned about offline queuing
|
||||
- ✅ No data loss
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Automatic Sync Test
|
||||
|
||||
**Purpose:** Verify queued contexts sync when API restored
|
||||
|
||||
```bash
|
||||
# 1. SSH to RMM server
|
||||
ssh guru@172.16.3.30
|
||||
|
||||
# 2. Start the API service
|
||||
sudo systemctl start claudetools-api
|
||||
|
||||
# 3. Verify API is running
|
||||
sudo systemctl status claudetools-api --no-pager
|
||||
# Expected: Active: active (running)
|
||||
|
||||
# 4. Test API health
|
||||
curl http://localhost:8001/health
|
||||
# Expected: {"status":"healthy","database":"connected"}
|
||||
|
||||
# 5. Exit SSH
|
||||
exit
|
||||
|
||||
# 6. Back on Windows - trigger sync
|
||||
# Method A: Send any message in Claude Code (automatic background sync)
|
||||
# Method B: Manual sync command
|
||||
bash .claude/hooks/sync-contexts
|
||||
|
||||
# Expected output from manual sync:
|
||||
# ===================================
|
||||
# Syncing Queued Contexts
|
||||
# ===================================
|
||||
# Found X pending context(s)
|
||||
#
|
||||
# Processing: [filename].json
|
||||
# ✓ Uploaded successfully
|
||||
#
|
||||
# ===================================
|
||||
# Sync Complete
|
||||
# ===================================
|
||||
# Successful: X
|
||||
# Failed: 0
|
||||
|
||||
# 7. Verify queue cleared
|
||||
ls -la .claude/context-queue/pending/
|
||||
# Expected: Empty (or nearly empty)
|
||||
|
||||
ls -la .claude/context-queue/uploaded/
|
||||
# Expected: Previously pending files moved here
|
||||
|
||||
# 8. Verify contexts in database
|
||||
curl -s "http://172.16.3.30:8001/api/conversation-contexts?limit=5" \
|
||||
-H "Authorization: Bearer $JWT_TOKEN" | python -m json.tool
|
||||
# Expected: Recently synced contexts appear in results
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Background sync triggered automatically
|
||||
- ✅ Queued contexts uploaded successfully
|
||||
- ✅ Files moved from pending/ to uploaded/
|
||||
- ✅ Contexts visible in database
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Cache Refresh Test
|
||||
|
||||
**Purpose:** Verify cache updates when API available
|
||||
|
||||
```bash
|
||||
# 1. API should be running from Phase 4
|
||||
|
||||
# 2. Delete local cache to force fresh fetch
|
||||
PROJECT_ID=$(git config --local claude.projectid 2>/dev/null || git config --get remote.origin.url | md5sum | cut -d' ' -f1)
|
||||
rm -rf .claude/context-cache/$PROJECT_ID
|
||||
|
||||
# 3. Open Claude Code and send a message
|
||||
|
||||
# Expected:
|
||||
# - Hook fetches fresh context from API
|
||||
# - Cache recreated with new timestamp
|
||||
# - Online mode message (no offline warning)
|
||||
|
||||
# 4. Verify fresh cache
|
||||
ls -la .claude/context-cache/$PROJECT_ID/
|
||||
# Expected: latest.json with recent timestamp
|
||||
|
||||
cat .claude/context-cache/$PROJECT_ID/last_updated
|
||||
# Expected: Current timestamp (2026-01-17T...)
|
||||
```
|
||||
|
||||
**Success Criteria:**
|
||||
- ✅ Cache recreated from API
|
||||
- ✅ Fresh timestamp recorded
|
||||
- ✅ Online mode confirmed
|
||||
|
||||
---
|
||||
|
||||
## Test Results Template
|
||||
|
||||
```markdown
|
||||
## Offline Mode Test Results
|
||||
|
||||
**Date:** [DATE]
|
||||
**Tester:** [NAME]
|
||||
**System:** [OS/Machine]
|
||||
|
||||
### Phase 1: Baseline (Online Mode)
|
||||
- [ ] Context retrieved from API
|
||||
- [ ] Cache created successfully
|
||||
- [ ] Context injected correctly
|
||||
**Notes:**
|
||||
|
||||
### Phase 2: Offline Mode (Cache Fallback)
|
||||
- [ ] API stopped successfully
|
||||
- [ ] Offline warning displayed
|
||||
- [ ] Cached context used
|
||||
- [ ] No errors encountered
|
||||
**Notes:**
|
||||
|
||||
### Phase 3: Context Queuing
|
||||
- [ ] Context queued locally
|
||||
- [ ] Queue file created
|
||||
- [ ] Warning message shown
|
||||
**Notes:**
|
||||
|
||||
### Phase 4: Automatic Sync
|
||||
- [ ] API restarted successfully
|
||||
- [ ] Sync triggered automatically
|
||||
- [ ] All contexts uploaded
|
||||
- [ ] Queue cleared
|
||||
**Notes:**
|
||||
|
||||
### Phase 5: Cache Refresh
|
||||
- [ ] Old cache deleted
|
||||
- [ ] Fresh cache created
|
||||
- [ ] Online mode confirmed
|
||||
**Notes:**
|
||||
|
||||
### Overall Result
|
||||
- [ ] PASS - All phases successful
|
||||
- [ ] FAIL - Issues encountered (see notes)
|
||||
|
||||
### Issues Found
|
||||
[List any issues, errors, or unexpected behavior]
|
||||
|
||||
### Recommendations
|
||||
[Any suggestions for improvements]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: API Won't Stop
|
||||
|
||||
```bash
|
||||
# Force stop
|
||||
sudo systemctl kill claudetools-api
|
||||
|
||||
# Verify stopped
|
||||
sudo systemctl status claudetools-api
|
||||
```
|
||||
|
||||
### Issue: Cache Not Being Used
|
||||
|
||||
```bash
|
||||
# Check if cache exists
|
||||
PROJECT_ID=$(git config --local claude.projectid)
|
||||
ls -la .claude/context-cache/$PROJECT_ID/
|
||||
|
||||
# Check hook version
|
||||
head -3 .claude/hooks/user-prompt-submit
|
||||
# Should show: "v2 - with offline support"
|
||||
|
||||
# Check hook is executable
|
||||
ls -l .claude/hooks/user-prompt-submit
|
||||
# Should show: -rwxr-xr-x
|
||||
```
|
||||
|
||||
### Issue: Contexts Not Queuing
|
||||
|
||||
```bash
|
||||
# Check queue directory permissions
|
||||
ls -ld .claude/context-queue/pending/
|
||||
|
||||
# Check hook version
|
||||
head -3 .claude/hooks/task-complete
|
||||
# Should show: "v2 - with offline support"
|
||||
|
||||
# Check environment
|
||||
source .claude/context-recall-config.env
|
||||
echo $CLAUDE_API_URL
|
||||
# Should show: http://172.16.3.30:8001
|
||||
```
|
||||
|
||||
### Issue: Sync Not Working
|
||||
|
||||
```bash
|
||||
# Check JWT token
|
||||
source .claude/context-recall-config.env
|
||||
echo $JWT_TOKEN
|
||||
# Should show a long token string
|
||||
|
||||
# Manual sync with debug
|
||||
bash -x .claude/hooks/sync-contexts
|
||||
|
||||
# Check API is accessible
|
||||
curl http://172.16.3.30:8001/health
|
||||
```
|
||||
|
||||
### Issue: Contexts Moved to Failed/
|
||||
|
||||
```bash
|
||||
# View failed contexts
|
||||
ls -la .claude/context-queue/failed/
|
||||
|
||||
# Check specific failed context
|
||||
cat .claude/context-queue/failed/[filename].json | python -m json.tool
|
||||
|
||||
# Check API response
|
||||
curl -X POST http://172.16.3.30:8001/api/conversation-contexts \
|
||||
-H "Authorization: Bearer $JWT_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d @.claude/context-queue/failed/[filename].json
|
||||
|
||||
# Move back to pending for retry
|
||||
mv .claude/context-queue/failed/*.json .claude/context-queue/pending/
|
||||
bash .claude/hooks/sync-contexts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Expected Behavior Summary
|
||||
|
||||
| Scenario | Hook Action | User Experience |
|
||||
|----------|-------------|-----------------|
|
||||
| **API Online** | Fetch from API → Cache locally → Inject | Normal operation, no warnings |
|
||||
| **API Offline (Recall)** | Read from cache → Inject with warning | "⚠️ Offline Mode - Using cached context" |
|
||||
| **API Offline (Save)** | Queue locally → Trigger background sync | "⚠ Context queued locally - will sync when online" |
|
||||
| **API Restored** | Background sync uploads queue → Clear | Silent sync, contexts uploaded |
|
||||
| **Fresh Start** | No cache available → Skip injection | Silent (no context to inject) |
|
||||
|
||||
---
|
||||
|
||||
## Performance Expectations
|
||||
|
||||
| Operation | Expected Time | Notes |
|
||||
|-----------|--------------|-------|
|
||||
| API Fetch | < 3 seconds | Timeout configured at 3s |
|
||||
| Cache Read | < 100ms | Local file read |
|
||||
| Queue Write | < 100ms | Local file write |
|
||||
| Background Sync | 0.5s per context | Non-blocking |
|
||||
|
||||
---
|
||||
|
||||
## Security Notes
|
||||
|
||||
**What's Cached:**
|
||||
- Context summaries (dense_summary)
|
||||
- Titles, tags, scores
|
||||
- Project IDs (non-sensitive)
|
||||
|
||||
**What's NOT Cached:**
|
||||
- JWT tokens (in config file, gitignored)
|
||||
- Credentials or passwords
|
||||
- Full conversation transcripts
|
||||
|
||||
**Best Practices:**
|
||||
- Keep `.claude/context-cache/` in .gitignore
|
||||
- Keep `.claude/context-queue/` in .gitignore
|
||||
- Review queued contexts before manual sync if handling sensitive projects
|
||||
- Clear cache when switching machines: `rm -rf .claude/context-cache/`
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Commands
|
||||
|
||||
```bash
|
||||
# Stop API (simulate offline)
|
||||
ssh guru@172.16.3.30 "sudo systemctl stop claudetools-api"
|
||||
|
||||
# Start API (restore online)
|
||||
ssh guru@172.16.3.30 "sudo systemctl start claudetools-api"
|
||||
|
||||
# Check API status
|
||||
curl -s http://172.16.3.30:8001/health
|
||||
|
||||
# View cache
|
||||
PROJECT_ID=$(git config --local claude.projectid)
|
||||
cat .claude/context-cache/$PROJECT_ID/latest.json | python -m json.tool
|
||||
|
||||
# View queue
|
||||
ls -la .claude/context-queue/pending/
|
||||
|
||||
# Manual sync
|
||||
bash .claude/hooks/sync-contexts
|
||||
|
||||
# Clear cache (force refresh)
|
||||
rm -rf .claude/context-cache/$PROJECT_ID
|
||||
|
||||
# Clear queue (CAUTION: data loss!)
|
||||
rm -rf .claude/context-queue/pending/*.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-01-17
|
||||
**Status:** Ready for Testing
|
||||
**Documentation:** See .claude/OFFLINE_MODE.md for architecture details
|
||||
Reference in New Issue
Block a user