d86f051955
Resolve pre-commit hook formatting failures for multiple files: **Files Fixed:** - .woodpecker/Dockerfile — Add missing final newline - .woodpecker/Dockerfile.cross — Add missing final newline - justfiles/ci.just — Remove trailing whitespace from recipe definitions - docs/setup/tracking-setup.md — Add missing final newline - crates/vapora-backend/src/api/provider_metrics.rs — Add missing final newline **Hooks Passing:** ✅ end-of-file-fixer — Files now have proper final newlines ✅ trailing-whitespace — Removed all trailing spaces ✅ mixed-line-ending — Line endings normalized These changes ensure the pre-commit framework can properly validate file formatting without blocking commits on infrastructure issues.
674 lines
13 KiB
Markdown
674 lines
13 KiB
Markdown
---
|
|
title: Vapora Tracking System - Complete Setup Guide
|
|
date: 2025-11-10
|
|
version: 1.0
|
|
---
|
|
|
|
# 🛠️ Vapora Tracking System - Complete Setup Guide
|
|
|
|
**This guide covers everything from zero to fully operational tracking system.**
|
|
|
|
---
|
|
|
|
## 📋 Table of Contents
|
|
|
|
1. [Prerequisites](#prerequisites)
|
|
2. [Installation](#installation)
|
|
3. [Configuration](#configuration)
|
|
4. [Verification](#verification)
|
|
5. [First Use](#first-use)
|
|
6. [Troubleshooting](#troubleshooting)
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
### System Requirements
|
|
|
|
| Requirement | Minimum | Recommended |
|
|
|------------|---------|-------------|
|
|
| OS | macOS 10.15+ | macOS 12+ |
|
|
| RAM | 2GB | 4GB+ |
|
|
| Disk | 1GB | 2GB+ |
|
|
| Internet | Required for install | Required |
|
|
|
|
### Software Requirements
|
|
|
|
```bash
|
|
# Check if installed
|
|
rustc --version # Need 1.70+
|
|
cargo --version # Comes with Rust
|
|
git --version # Need 2.20+
|
|
```
|
|
|
|
### Installation Check
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
echo "Checking prerequisites..."
|
|
|
|
# Check Rust
|
|
if ! command -v rustc &> /dev/null; then
|
|
echo "❌ Rust not found. Install from https://rustup.rs"
|
|
exit 1
|
|
fi
|
|
|
|
# Check Cargo
|
|
if ! command -v cargo &> /dev/null; then
|
|
echo "❌ Cargo not found. Install Rust from https://rustup.rs"
|
|
exit 1
|
|
fi
|
|
|
|
# Check Rust version
|
|
RUST_VERSION=$(rustc --version | awk '{print $2}')
|
|
echo "✅ Rust $RUST_VERSION found"
|
|
echo "✅ All prerequisites met!"
|
|
```
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Step 1: Install Rust (if needed)
|
|
|
|
```bash
|
|
# Download and install Rust
|
|
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
|
|
|
# Follow the prompts (default options are fine)
|
|
|
|
# Add Rust to PATH
|
|
source $HOME/.cargo/env
|
|
|
|
# Verify installation
|
|
rustc --version
|
|
cargo --version
|
|
```
|
|
|
|
**Expected output:**
|
|
```
|
|
rustc 1.XX.X (XXXXXXXXXXXX YYYY-MM-DD)
|
|
cargo 1.XX.X (XXXXXXXXXXXX YYYY-MM-DD)
|
|
```
|
|
|
|
### Step 2: Clone or Navigate to Vapora
|
|
|
|
```bash
|
|
# Option A: Clone (if you don't have it)
|
|
git clone https://github.com/yourusername/vapora.git
|
|
cd vapora
|
|
|
|
# Option B: Navigate (if you already have it)
|
|
cd vapora
|
|
|
|
# Verify structure
|
|
ls crates/vapora-tracking/
|
|
# Should show: Cargo.toml, README.md, src/, benches/
|
|
```
|
|
|
|
### Step 3: Build the Tracking System
|
|
|
|
```bash
|
|
# Build tracking crate
|
|
cargo build -p vapora-tracking
|
|
|
|
# Output should show:
|
|
# Compiling vapora-tracking v0.1.0
|
|
# Finished `dev` profile [unoptimized + debuginfo]
|
|
|
|
# For faster runtime (slower build):
|
|
cargo build -p vapora-tracking --release
|
|
|
|
# Output should show:
|
|
# Finished `release` profile [optimized]
|
|
```
|
|
|
|
**Build time:**
|
|
- Debug: 30-60 seconds (first time)
|
|
- Release: 2-5 minutes (first time)
|
|
- Subsequent: 1-10 seconds (incremental)
|
|
|
|
### Step 4: Verify Build
|
|
|
|
```bash
|
|
# List build artifacts
|
|
ls -lh target/debug/deps/ | grep vapora_tracking
|
|
|
|
# Should show several .rlib and other files
|
|
|
|
# Or with release build
|
|
ls -lh target/release/deps/ | grep vapora_tracking
|
|
```
|
|
|
|
### Step 5: Install CLI Components
|
|
|
|
```bash
|
|
# Create commands directory if it doesn't exist
|
|
mkdir -p ~/.claude/commands
|
|
mkdir -p ~/.claude/skills
|
|
|
|
# Copy tracking commands
|
|
cp ~/.claude/commands/log-change.md ~/.claude/commands/
|
|
cp ~/.claude/commands/add-todo.md ~/.claude/commands/
|
|
cp ~/.claude/commands/track-status.md ~/.claude/commands/
|
|
|
|
# Copy tracking skill
|
|
cp ~/.claude/skills/tracking.md ~/.claude/skills/
|
|
|
|
# Verify installation
|
|
ls -la ~/.claude/commands/ | grep -E "log-change|add-todo|track-status"
|
|
ls -la ~/.claude/skills/ | grep tracking
|
|
```
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
### Option 1: Default Configuration (Recommended)
|
|
|
|
The system works out of the box with defaults:
|
|
|
|
```bash
|
|
# Default database location
|
|
~/.tracking/database.sqlite
|
|
|
|
# Default watch directories
|
|
~/.coder/
|
|
~/.claude/todos/
|
|
|
|
# Default API port
|
|
3000
|
|
```
|
|
|
|
**No configuration needed! Skip to Verification.**
|
|
|
|
### Option 2: Custom Configuration
|
|
|
|
Create `~/.config/vapora-tracking.toml`:
|
|
|
|
```toml
|
|
[database]
|
|
# SQLite database path (use your home directory)
|
|
url = "sqlite://~/.tracking/database.sqlite"
|
|
|
|
# Max connections to database
|
|
max_connections = 5
|
|
|
|
# Connection timeout (seconds)
|
|
timeout = 5
|
|
|
|
[watcher]
|
|
# Directories to watch for changes (customize for your setup)
|
|
watch_dirs = [
|
|
"~/.coder",
|
|
"~/.claude/todos"
|
|
]
|
|
|
|
# Debounce time (milliseconds)
|
|
debounce_ms = 500
|
|
|
|
[api]
|
|
# API server port
|
|
port = 3000
|
|
|
|
# API host
|
|
host = "127.0.0.1"
|
|
|
|
[logging]
|
|
# Log level: trace, debug, info, warn, error
|
|
level = "info"
|
|
|
|
# Log file path
|
|
file = "/tmp/vapora-tracking.log"
|
|
```
|
|
|
|
### Option 3: Environment Variables
|
|
|
|
```bash
|
|
# Set database location (use your home directory)
|
|
export TRACKING_DATABASE_URL="sqlite://~/.tracking/database.sqlite"
|
|
|
|
# Set API port
|
|
export TRACKING_API_PORT=3000
|
|
|
|
# Set log level
|
|
export RUST_LOG=info
|
|
|
|
# These override config file values
|
|
```
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
### Test 1: Build Success
|
|
|
|
```bash
|
|
# Clean rebuild to verify
|
|
cargo clean -p vapora-tracking
|
|
cargo build -p vapora-tracking
|
|
|
|
# Check for success
|
|
if [ $? -eq 0 ]; then
|
|
echo "✅ Build successful"
|
|
else
|
|
echo "❌ Build failed"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
### Test 2: Tests Pass
|
|
|
|
```bash
|
|
# Run all unit tests
|
|
cargo test -p vapora-tracking --lib
|
|
|
|
# Expected output:
|
|
# running 20 tests
|
|
# ...
|
|
# test result: ok. 20 passed; 0 failed
|
|
```
|
|
|
|
**If not 20 tests:**
|
|
```bash
|
|
# Check what tests exist
|
|
cargo test -p vapora-tracking --lib -- --list
|
|
|
|
# Run with output for debugging
|
|
cargo test -p vapora-tracking --lib -- --nocapture
|
|
```
|
|
|
|
### Test 3: Code Quality
|
|
|
|
```bash
|
|
# Run clippy checks
|
|
cargo clippy -p vapora-tracking --lib -- -W clippy::all
|
|
|
|
# Should show minimal warnings (profile warning is expected)
|
|
```
|
|
|
|
### Test 4: CLI Commands
|
|
|
|
```bash
|
|
# Verify commands are installed
|
|
ls ~/.claude/commands/
|
|
|
|
# Output should include:
|
|
# add-todo.md
|
|
# log-change.md
|
|
# track-status.md
|
|
|
|
# Verify skill
|
|
ls ~/.claude/skills/tracking.md
|
|
```
|
|
|
|
### Test 5: API Health
|
|
|
|
```bash
|
|
# Start service
|
|
./scripts/start-tracking-service.nu
|
|
|
|
# Wait 2 seconds
|
|
sleep 2
|
|
|
|
# Check health endpoint
|
|
curl http://localhost:3000/api/v1/tracking/health
|
|
|
|
# Expected output:
|
|
# {"status":"ok","service":"vapora-tracking","timestamp":"2025-11-10T..."}
|
|
```
|
|
|
|
### Verification Checklist
|
|
|
|
```bash
|
|
# Run all verifications
|
|
echo "Running verification tests..."
|
|
|
|
# Test 1: Build
|
|
cargo build -p vapora-tracking 2>&1 | grep -q "Finished"
|
|
[ $? -eq 0 ] && echo "✅ Build" || echo "❌ Build"
|
|
|
|
# Test 2: Tests
|
|
cargo test -p vapora-tracking --lib 2>&1 | grep -q "20 passed"
|
|
[ $? -eq 0 ] && echo "✅ Tests" || echo "❌ Tests"
|
|
|
|
# Test 3: Clippy
|
|
cargo clippy -p vapora-tracking --lib 2>&1 | grep -q "error:" && echo "❌ Clippy" || echo "✅ Clippy"
|
|
|
|
# Test 4: Commands
|
|
[ -f ~/.claude/commands/log-change.md ] && echo "✅ Commands" || echo "❌ Commands"
|
|
|
|
# Test 5: Skills
|
|
[ -f ~/.claude/skills/tracking.md ] && echo "✅ Skills" || echo "❌ Skills"
|
|
|
|
echo "Verification complete!"
|
|
```
|
|
|
|
---
|
|
|
|
## First Use
|
|
|
|
### Your First Change Log
|
|
|
|
```bash
|
|
# Log your first change
|
|
/log-change "Set up Vapora tracking system" \
|
|
--impact infrastructure \
|
|
--files 1
|
|
|
|
# Expected response: Change logged successfully
|
|
```
|
|
|
|
### Your First TODO
|
|
|
|
```bash
|
|
# Create your first TODO
|
|
/add-todo "Review tracking system documentation" \
|
|
--priority M \
|
|
--estimate S \
|
|
--due 2025-11-12
|
|
|
|
# Expected response: TODO created successfully
|
|
```
|
|
|
|
### Your First Status Check
|
|
|
|
```bash
|
|
# Check current status
|
|
/track-status --limit 5
|
|
|
|
# Expected output shows your 1 change and 1 TODO
|
|
```
|
|
|
|
### Your First Export
|
|
|
|
```bash
|
|
# Export to JSON
|
|
./scripts/export-tracking.nu json --output tracking-report
|
|
|
|
# Export to Markdown
|
|
./scripts/export-tracking.nu markdown --project vapora > report.md
|
|
|
|
# Check results
|
|
ls -la tracking-report.json
|
|
cat report.md
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Build Issues
|
|
|
|
#### Issue: "error[E0433]: failed to resolve"
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Update Rust
|
|
rustup update
|
|
|
|
# Clean and rebuild
|
|
cargo clean -p vapora-tracking
|
|
cargo build -p vapora-tracking
|
|
```
|
|
|
|
#### Issue: "could not compile ... due to X previous errors"
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Check Rust version
|
|
rustc --version # Must be 1.70+
|
|
|
|
# Update if needed
|
|
rustup install stable
|
|
|
|
# Verify dependencies
|
|
cargo tree -p vapora-tracking
|
|
```
|
|
|
|
### Database Issues
|
|
|
|
#### Issue: "Database file not found"
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Create database directory
|
|
mkdir -p ~/.tracking
|
|
|
|
# Start service to initialize
|
|
./scripts/start-tracking-service.nu
|
|
|
|
# Check database was created
|
|
ls -la ~/.tracking/
|
|
```
|
|
|
|
#### Issue: "Failed to initialize database"
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Reset database
|
|
rm ~/.tracking/database.sqlite
|
|
|
|
# Service will recreate on next start
|
|
./scripts/start-tracking-service.nu
|
|
```
|
|
|
|
### CLI Issues
|
|
|
|
#### Issue: "/log-change not found" in Claude Code
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Verify commands are copied
|
|
ls ~/.claude/commands/log-change.md
|
|
|
|
# If missing, copy them
|
|
cp ~/.claude/commands/log-change.md ~/.claude/commands/
|
|
|
|
# Restart Claude Code
|
|
```
|
|
|
|
#### Issue: "Command not recognized"
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Check command format
|
|
/log-change --help
|
|
|
|
# Should show usage information
|
|
# If not, commands aren't properly installed
|
|
```
|
|
|
|
### API Issues
|
|
|
|
#### Issue: "Connection refused" when calling API
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Start the service
|
|
./scripts/start-tracking-service.nu --verbose
|
|
|
|
# Wait for startup
|
|
sleep 2
|
|
|
|
# Check health
|
|
curl -v http://localhost:3000/api/v1/tracking/health
|
|
|
|
# Check logs
|
|
tail -f /tmp/vapora-tracking.log
|
|
```
|
|
|
|
#### Issue: "Port 3000 already in use"
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Use different port
|
|
./scripts/start-tracking-service.nu --port 3001
|
|
|
|
# Or kill existing service
|
|
lsof -i :3000
|
|
kill -9 <PID>
|
|
```
|
|
|
|
### Performance Issues
|
|
|
|
#### Issue: Build is very slow
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Use incremental compilation
|
|
export CARGO_INCREMENTAL=1
|
|
|
|
# Use faster linker (if available)
|
|
export RUSTFLAGS="-C link-arg=-fuse-ld=lld"
|
|
|
|
# Or just use release build once
|
|
cargo build -p vapora-tracking --release
|
|
```
|
|
|
|
#### Issue: High memory usage
|
|
|
|
**Solution:**
|
|
```bash
|
|
# Limit parallel jobs during build
|
|
cargo build -p vapora-tracking -j 2
|
|
|
|
# Or reduce connection pool
|
|
# Edit storage.rs: max_connections = 2
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Troubleshooting Reference
|
|
|
|
| Problem | Quick Fix |
|
|
|---------|-----------|
|
|
| Build fails | `cargo clean && cargo build` |
|
|
| Tests fail | `rustup update` then rebuild |
|
|
| Commands missing | `cp ~/.claude/commands/*` |
|
|
| API won't start | `./scripts/start-tracking-service.nu --verbose` |
|
|
| Database errors | `rm ~/.tracking/database.sqlite` |
|
|
| Port in use | `./scripts/start-tracking-service.nu --port 3001` |
|
|
| Slow build | `export CARGO_INCREMENTAL=1` |
|
|
|
|
---
|
|
|
|
## System Validation Script
|
|
|
|
Save this as `validate-tracking.sh`:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
|
|
set -e
|
|
|
|
echo "🔍 Validating Vapora Tracking System Installation"
|
|
echo "=================================================="
|
|
|
|
# Check Rust
|
|
echo "Checking Rust..."
|
|
if ! command -v rustc &> /dev/null; then
|
|
echo "❌ Rust not found"
|
|
exit 1
|
|
fi
|
|
echo "✅ Rust $(rustc --version | awk '{print $2}')"
|
|
|
|
# Check build
|
|
echo "Building tracking crate..."
|
|
cargo build -p vapora-tracking 2>&1 | tail -3
|
|
echo "✅ Build successful"
|
|
|
|
# Check tests
|
|
echo "Running tests..."
|
|
TEST_OUTPUT=$(cargo test -p vapora-tracking --lib 2>&1)
|
|
if echo "$TEST_OUTPUT" | grep -q "test result: ok. 20 passed"; then
|
|
echo "✅ All 20 tests passed"
|
|
else
|
|
echo "❌ Tests failed"
|
|
exit 1
|
|
fi
|
|
|
|
# Check CLI
|
|
echo "Checking CLI components..."
|
|
[ -f ~/.claude/commands/log-change.md ] && echo "✅ Commands installed" || echo "⚠️ Commands not found"
|
|
[ -f ~/.claude/skills/tracking.md ] && echo "✅ Skill installed" || echo "⚠️ Skill not found"
|
|
|
|
# Check scripts
|
|
echo "Checking scripts..."
|
|
[ -f ./scripts/start-tracking-service.nu ] && echo "✅ Scripts available" || echo "⚠️ Scripts not found"
|
|
|
|
echo ""
|
|
echo "=================================================="
|
|
echo "✅ Validation Complete - System Ready!"
|
|
echo "=================================================="
|
|
|
|
echo ""
|
|
echo "Next steps:"
|
|
echo "1. /log-change \"Your first change\""
|
|
echo "2. /add-todo \"Your first task\""
|
|
echo "3. /track-status"
|
|
```
|
|
|
|
Run it:
|
|
```bash
|
|
chmod +x validate-tracking.sh
|
|
./validate-tracking.sh
|
|
```
|
|
|
|
---
|
|
|
|
## What's Next After Setup?
|
|
|
|
### Immediate (Today)
|
|
- [ ] Complete all verification tests
|
|
- [ ] Create your first change log
|
|
- [ ] Create your first TODO
|
|
- [ ] Run your first status check
|
|
|
|
### Short Term (This Week)
|
|
- [ ] Use `/log-change` for actual changes
|
|
- [ ] Use `/add-todo` for tasks
|
|
- [ ] Explore `/track-status` filters
|
|
- [ ] Try exporting to different formats
|
|
|
|
### Medium Term (This Month)
|
|
- [ ] Set up automated syncing
|
|
- [ ] Create custom dashboard queries
|
|
- [ ] Integrate with your workflows
|
|
- [ ] Set up reports
|
|
|
|
---
|
|
|
|
## Getting Help
|
|
|
|
**Issue not listed above?**
|
|
|
|
1. Check the [TROUBLESHOOTING section](../crates/vapora-tracking/INTEGRATION.md#troubleshooting) in INTEGRATION.md
|
|
2. Review [TRACKING_SYSTEM_STATUS.md](./TRACKING_SYSTEM_STATUS.md)
|
|
3. Check logs: `tail -f /tmp/vapora-tracking.log`
|
|
4. Read inline code documentation: `cargo doc -p vapora-tracking --open`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
You've successfully set up the Vapora tracking system!
|
|
|
|
### What you now have:
|
|
|
|
✅ **Built:** vapora-tracking crate compiled and tested
|
|
✅ **Verified:** All 20 tests passing
|
|
✅ **Installed:** CLI commands and skill
|
|
✅ **Running:** Tracking service ready
|
|
✅ **Configured:** Database and API ready
|
|
|
|
### Start using it:
|
|
|
|
```bash
|
|
/log-change "Example change" --impact backend
|
|
/add-todo "Example task" --priority H
|
|
/track-status
|
|
```
|
|
|
|
**Happy tracking! 🚀**
|