navidocs/REMEDIATION_COMMANDS.md

NaviDocs Remediation - Complete Command Reference

Generated by Agent 3 ("Electrician") - Search Module & PDF Export Enablement

---

Quick Start Commands

Verify All Components Are Wired

# From NaviDocs root directory
bash test_search_wiring.sh

Start Services for Full Testing

# Terminal 1: Start Meilisearch
docker run -d -p 7700:7700 --name meilisearch getmeili/meilisearch:latest

# Terminal 2: Start API Server
cd server
npm install  # if needed
npm run dev

# Terminal 3: Run Tests
bash test_search_wiring.sh

# Terminal 3: Test Endpoint
curl "http://localhost:3001/api/v1/search?q=yacht"

---

Dockerfile - PDF Export (wkhtmltopdf)

Verification Commands

Check if wkhtmltopdf is in Dockerfile:

grep "wkhtmltopdf" Dockerfile

Check if NOT commented out:

grep "^[^#]*wkhtmltopdf" Dockerfile

View complete Dockerfile system dependencies section:

grep -A 7 "Install system dependencies" Dockerfile

Build Docker Image

Build with tag:

docker build -t navidocs:latest .

Build with progress output:

docker build --progress=plain -t navidocs:latest .

Build without cache (force rebuild):

docker build --no-cache -t navidocs:latest .

Run Docker Container

Basic run:

docker run -p 3001:3001 navidocs:latest

With Meilisearch link:

docker run -d \
  --name navidocs \
  -p 3001:3001 \
  -e MEILI_HOST=http://meilisearch:7700 \
  -e MEILI_KEY=your-api-key \
  --link meilisearch:meilisearch \
  navidocs:latest

With environment file:

docker run -d \
  --name navidocs \
  -p 3001:3001 \
  --env-file server/.env \
  navidocs:latest

With volume mounts:

docker run -d \
  --name navidocs \
  -p 3001:3001 \
  -v $(pwd)/server/uploads:/app/uploads \
  -v $(pwd)/server/db:/app/db \
  -e MEILI_HOST=http://meilisearch:7700 \
  -e MEILI_KEY=your-key \
  --link meilisearch \
  navidocs:latest

Test PDF Export Capability

In Docker container:

docker exec navidocs which wkhtmltopdf
docker exec navidocs wkhtmltopdf --version

Test conversion:

docker exec navidocs wkhtmltopdf /path/to/input.html /path/to/output.pdf

---

Search API Route - /api/v1/search

Verification Commands

Check if route file exists:

ls -lah server/routes/api_search.js

Check if route is imported in server.js:

grep "api_search" server/index.js

Check if route is mounted:

grep "/api/v1/search" server/index.js

View import statement:

grep -n "import apiSearchRoutes" server/index.js

View mount statement:

grep -n "app.use.*api/v1/search" server/index.js

API Testing Commands

Start API server (development):

cd server
npm run dev

Basic search (missing query - should return 400):

curl "http://localhost:3001/api/v1/search"

Search with query:

curl "http://localhost:3001/api/v1/search?q=yacht"

Search with pagination:

curl "http://localhost:3001/api/v1/search?q=maintenance&limit=10&offset=0"

Search with filters:

curl "http://localhost:3001/api/v1/search?q=engine&type=log&entity=vessel-001"

With language filter:

curl "http://localhost:3001/api/v1/search?q=propeller&language=en"

Health check endpoint:

curl "http://localhost:3001/api/v1/search/health"

Pretty print JSON response:

curl -s "http://localhost:3001/api/v1/search?q=test" | jq .

Check response time:

curl -w "\nTime: %{time_total}s\n" "http://localhost:3001/api/v1/search?q=test"

Test error handling (empty query):

curl "http://localhost:3001/api/v1/search?q="

Test long query (over 200 chars):

curl "http://localhost:3001/api/v1/search?q=$(python3 -c 'print("x"*300)')"

Monitor requests with verbose output:

curl -v "http://localhost:3001/api/v1/search?q=test"

---

Environment Variables

Display Current Configuration

Show all Meilisearch variables:

grep -i meilisearch server/.env.example

Show all search variables:

grep -i "meili\|search" server/.env.example

View current .env (if exists):

cat server/.env | grep -i meili

Create .env File

Copy from example:

cp server/.env.example server/.env

Edit for local development:

# Edit server/.env with your values:
MEILI_HOST=http://127.0.0.1:7700
MEILI_KEY=your-development-key
MEILI_INDEX=navidocs-pages

Edit for Docker:

# Inside docker-compose or Docker run:
MEILI_HOST=http://meilisearch:7700
MEILI_KEY=your-docker-key
MEILI_INDEX=navidocs-pages

Validate environment file:

# Check if all required variables are set
grep "^MEILI\|^MEILISEARCH" server/.env.example | while read line; do
  var=$(echo $line | cut -d= -f1)
  grep -q "^$var=" server/.env && echo "✓ $var" || echo "✗ $var MISSING"
done

---

Testing Scripts

Run Complete Test Suite

From NaviDocs root:

bash test_search_wiring.sh

With output capture:

bash test_search_wiring.sh 2>&1 | tee test_results.log

Count pass/fail:

bash test_search_wiring.sh 2>&1 | grep -E "\[PASS\]|\[FAIL\]" | sort | uniq -c

Individual Test Commands

Test Dockerfile:

grep -q "wkhtmltopdf" Dockerfile && echo "PASS: wkhtmltopdf found" || echo "FAIL: wkhtmltopdf not found"

Test Route Registration:

grep -q "apiSearchRoutes" server/index.js && echo "PASS: Route imported" || echo "FAIL: Route not imported"

Test Environment Variables:

for var in MEILI_HOST MEILI_KEY MEILI_INDEX; do
  grep -q "^$var=" server/.env.example && echo "PASS: $var configured" || echo "FAIL: $var missing"
done

Test API Endpoint (if running):

response=$(curl -s -w "\n%{http_code}" "http://localhost:3001/api/v1/search?q=test" 2>&1 | tail -1)
[ "$response" != "000" ] && echo "PASS: API responding (HTTP $response)" || echo "FAIL: API not responding"

Debug Tests

Verbose test run:

bash -x test_search_wiring.sh

Test with custom API host:

API_HOST=http://my-server:3001 bash test_search_wiring.sh

Test with custom Meilisearch host:

MEILI_HOST=http://search.example.com bash test_search_wiring.sh

Test with both custom hosts:

API_HOST=http://api.example.com:3001 MEILI_HOST=http://search.example.com bash test_search_wiring.sh

---

Meilisearch Setup

Start Meilisearch Container

Basic start:

docker run -p 7700:7700 getmeili/meilisearch:latest

With master key:

docker run -p 7700:7700 \
  -e MEILI_MASTER_KEY=your-secure-key \
  getmeili/meilisearch:latest

Background with name:

docker run -d \
  --name meilisearch \
  -p 7700:7700 \
  -e MEILI_MASTER_KEY=your-key \
  getmeili/meilisearch:latest

With persistent data:

docker run -d \
  --name meilisearch \
  -p 7700:7700 \
  -v meilisearch_data:/meili_data \
  -e MEILI_MASTER_KEY=your-key \
  getmeili/meilisearch:latest

Test Meilisearch

Health check:

curl http://127.0.0.1:7700/health

Get keys:

curl -H "Authorization: Bearer your-master-key" \
  http://127.0.0.1:7700/keys

Search endpoint:

curl -X POST http://127.0.0.1:7700/indexes/navidocs-pages/search \
  -H "Authorization: Bearer your-master-key" \
  -H "Content-Type: application/json" \
  -d '{"q":"test"}'

Stop Meilisearch

Stop container:

docker stop meilisearch

Remove container:

docker rm meilisearch

Clean up volume:

docker volume rm meilisearch_data

---

Git Integration

Commit Changes

Stage all deliverables:

git add Dockerfile server/routes/api_search.js server/index.js server/.env.example test_search_wiring.sh ELECTRICIAN_REMEDIATION_GUIDE.md REMEDIATION_COMMANDS.md

Commit with message:

git commit -m "feat: Enable PDF export and wire search API endpoints

- Add Dockerfile with wkhtmltopdf and tesseract-ocr support
- Create production-ready /api/v1/search endpoint with Meilisearch integration
- Integrate search route into Express server
- Document environment variables for search configuration
- Add comprehensive test suite for wiring validation
- Includes query sanitization, error handling, and rate limiting"

Verify commit:

git show --name-only

Review Changes

Diff Dockerfile:

git diff Dockerfile

Diff server.js:

git diff server/index.js

View file history:

git log --oneline -- Dockerfile server/routes/api_search.js

---

Debugging

Check Logs

API Server Logs (if running):

# With npm dev (shows real-time)
npm run dev

# From Docker container:
docker logs navidocs
docker logs -f navidocs  # Follow logs

Meilisearch Logs:

docker logs meilisearch
docker logs -f meilisearch

Verify File Contents

Check Dockerfile syntax:

docker build --dry-run .

Verify JavaScript syntax:

node --check server/routes/api_search.js

Validate JSON in .env.example:

grep "^[A-Z]" server/.env.example | head -5

Network Debugging

Check if ports are open:

# Meilisearch
netstat -an | grep 7700 || echo "Port 7700 not listening"

# API Server
netstat -an | grep 3001 || echo "Port 3001 not listening"

Test connectivity:

curl -v http://127.0.0.1:7700/health
curl -v http://localhost:3001/api/v1/search?q=test

Using nc (netcat):

nc -zv 127.0.0.1 7700
nc -zv localhost 3001

---

Production Deployment

Pre-deployment Checklist

# 1. Verify all tests pass
bash test_search_wiring.sh

# 2. Build Docker image
docker build -t navidocs:prod .

# 3. Test image runs
docker run -p 3001:3001 navidocs:prod

# 4. Verify endpoints
curl http://localhost:3001/health
curl http://localhost:3001/api/v1/search?q=test

# 5. Check logs for errors
docker logs <container-id>

Deploy with Docker Compose

Create docker-compose.yml:

version: '3.8'

services:
  meilisearch:
    image: getmeili/meilisearch:latest
    ports:
      - "7700:7700"
    environment:
      MEILI_MASTER_KEY: ${MEILI_KEY}
    volumes:
      - meilisearch_data:/meili_data

  api:
    build: .
    ports:
      - "3001:3001"
    environment:
      NODE_ENV: production
      MEILI_HOST: http://meilisearch:7700
      MEILI_KEY: ${MEILI_KEY}
      MEILI_INDEX: navidocs-pages
    depends_on:
      - meilisearch

volumes:
  meilisearch_data:

Deploy:

docker-compose up -d
docker-compose logs -f

Production Environment File

Create server/.env.production:

NODE_ENV=production
PORT=3001
MEILI_HOST=https://search.yourdomain.com
MEILI_KEY=your-production-key
MEILI_INDEX=navidocs-pages-prod
DATABASE_PATH=/app/db/navidocs.db

---

Useful Shortcuts

Create Alias for Common Commands

# Add to ~/.bashrc or ~/.zshrc
alias test-navidocs="bash test_search_wiring.sh"
alias start-search="docker run -d -p 7700:7700 --name meilisearch getmeili/meilisearch:latest"
alias stop-search="docker stop meilisearch && docker rm meilisearch"
alias dev-navidocs="cd server && npm run dev"
alias test-search="curl -s http://localhost:3001/api/v1/search?q=test | jq"

One-liner: Complete Setup

# Start Meilisearch, API, and verify
docker run -d -p 7700:7700 --name meilisearch getmeili/meilisearch:latest && \
sleep 2 && \
cd server && npm run dev &
sleep 3 && \
bash test_search_wiring.sh && \
curl -s http://localhost:3001/api/v1/search?q=test | jq .

---

Performance Testing

Load Test Search Endpoint

Using Apache Bench:

ab -n 1000 -c 10 "http://localhost:3001/api/v1/search?q=test"

Using hey:

go get -u github.com/rakyll/hey
hey -n 1000 -c 10 http://localhost:3001/api/v1/search?q=test

Using wrk:

wrk -t4 -c100 -d30s http://localhost:3001/api/v1/search?q=test

Monitor Performance

Real-time monitoring:

watch -n 1 'curl -s http://localhost:3001/api/v1/search?q=test | jq .took_ms'

Average response time:

for i in {1..10}; do
  curl -s -w "%{time_total}\n" -o /dev/null "http://localhost:3001/api/v1/search?q=test"
done | awk '{sum+=$1; count++} END {print "Average: " sum/count "s"}'

---

Next Steps

1. Run full verification: bash test_search_wiring.sh
2. Start services: Meilisearch + API server
3. Test endpoints: Confirm /api/v1/search responds
4. Review logs: Check for any warnings or errors
5. Commit changes: Add to git with proper message
6. Deploy: Use Docker for production

All deliverables are production-ready and fully documented!