name: dev-environment-cleanup description: Clean up development environment issues in the Orient monorepo. Use when asked to "clean build", "rebuild from scratch", "fix build issues", "clean node_modules", or when encountering stale build artifacts, tsbuildinfo issues, or turbo cache problems. NOT for testing the installer - use fresh-install-testing for that.

Development Environment Cleanup

Package Names

All workspace packages use the @orient-bot/ namespace:

• @orient-bot/core - Configuration, logging, utilities
• @orient-bot/database - Database schemas and clients
• @orient-bot/database-services - Database service layer
• @orient-bot/agents - Agent framework and registry
• @orient-bot/mcp-tools - MCP tool implementations
• @orient-bot/dashboard - Dashboard server and API
• @orient-bot/dashboard-frontend - React frontend
• @orient-bot/bot-whatsapp - WhatsApp bot service
• @orient-bot/bot-slack - Slack bot service
• @orient-bot/integrations - Third-party integrations

Note: Do not confuse with @orient/ (old namespace) or @orientbot/ (typo).

Database Modes

Orient supports two database modes:

SQLite Mode (dev-local, installer)

./run.sh dev-local

• No Docker required
• Database: .dev-data/instance-N/orient.db
• Recommended for local development and the one-line installer

PostgreSQL Mode (dev, Docker)

./run.sh dev

• Requires Docker for PostgreSQL, MinIO, Nginx
• Full production-like environment
• Used for testing Docker deployments

Quick Reference

# Full cleanup and reinstall
rm -rf node_modules .turbo packages/*/node_modules packages/*/.turbo packages/*/dist
find packages/*/src -type f \( -name "*.js" -o -name "*.js.map" -o -name "*.d.ts" -o -name "*.d.ts.map" \) -delete
find packages -name "*.tsbuildinfo" -delete
rm -f .tsbuildinfo
pnpm install
pnpm run build:packages

Common Issues & Fixes

1. Stale tsbuildinfo Files (Incremental Compilation)

Symptoms:

• tsc runs without error but produces no output
• Turbo shows "cache hit" but dist/ folders are empty
• Turbo warns: "no output files found for task @orient-bot/mcp-tools#build"
• Build completes "successfully" but dependent packages fail with TS2307

Cause: TypeScript's .tsbuildinfo files store incremental compilation state. When stale, tsc believes everything is up-to-date and skips compilation entirely - even when dist/ is empty.

Key indicator: The warning "no output files found" after a build means tsbuildinfo is stale.

Fix:

find packages -name "*.tsbuildinfo" -delete
rm -f .tsbuildinfo

Verification (critical step after cleaning):

# Rebuild
pnpm run build:packages

# Verify dist directories are populated BEFORE proceeding
ls packages/mcp-tools/dist/index.js
ls packages/core/dist/index.js
ls packages/agents/dist/index.js

If dist/ is still empty after rebuild, check for other issues (stray files in src/, turbo cache).

2. Stray Compiled Files in src/

Symptom: Build errors about missing modules even though dependencies are installed.

Cause: Previous builds left .js, .d.ts, .js.map, .d.ts.map files in src/ directories instead of dist/.

Fix:

find packages/*/src -type f \( -name "*.js" -o -name "*.js.map" -o -name "*.d.ts" -o -name "*.d.ts.map" \) -delete

3. Turbo Cache Issues

Symptom: Build appears cached but dist folders are empty or stale.

Fix:

rm -rf .turbo packages/*/.turbo

4. Stale Worktrees

Symptom: Many old worktrees consuming disk space.

Check:

git worktree list

Fix:

# Remove worktree directories
rm -rf ~/claude-worktrees/orient/*
rm -rf ~/.cursor/worktrees/orient/*
# Prune git references
git worktree prune

5. Stale Fresh Install Folders

Symptom: Multiple orient-fresh-* directories in parent folder.

Fix:

rm -rf ../orient-fresh-*

6. Module Resolution Errors (TS2307)

Symptom: Build fails with error TS2307: Cannot find module '@orient-bot/mcp-tools' or similar.

Cause: Turbo's dependency graph wasn't respected because:

• Stale tsbuildinfo made turbo think prerequisite packages were already built
• The dist/ folder was empty or missing despite turbo showing "cache hit"

Troubleshooting:

1. Verify turbo.json has "dependsOn": ["^build"] for the build task
2. Check package.json has correct workspace:* dependencies
3. Manually verify prerequisite package dist exists:

   ls packages/mcp-tools/dist/index.js
   

Fix: Clean tsbuildinfo and turbo cache, then rebuild:

find packages -name "*.tsbuildinfo" -delete
rm -rf .turbo packages/*/.turbo packages/*/dist
pnpm run build:packages

Full Cleanup Procedure

1. Remove node_modules and build artifacts:

   rm -rf node_modules .turbo packages/*/node_modules packages/*/.turbo packages/*/dist
   

2. Clean stray compiled files from src directories:

   find packages/*/src -type f \( -name "*.js" -o -name "*.js.map" -o -name "*.d.ts" -o -name "*.d.ts.map" \) -delete
   

3. Clean tsbuildinfo files:

   find packages -name "*.tsbuildinfo" -delete
   rm -f .tsbuildinfo
   

4. Clean worktrees (optional):

   rm -rf ~/claude-worktrees/orient/* ~/.cursor/worktrees/orient/*
   git worktree prune
   

5. Fresh install:

   pnpm install
   

6. Build packages:

   pnpm run build:packages
   

7. Verify build completion (critical - don't skip):

   # Turbo's "cache hit" can be misleading - always verify dist/ exists
   ls packages/*/dist/index.js
   

   If any package is missing dist/index.js, clean tsbuildinfo and rebuild that package.

Docker Testing Mode

Running Tests with Docker Stack

./run.sh test        # Build and start full Docker stack
./run.sh test pull   # Use pre-built images from ghcr.io (requires auth)
./run.sh test status # Check container health
./run.sh test stop   # Stop containers

7. Docker Build Hangs on Metadata Loading

Symptom: ./run.sh test hangs at "load metadata for docker.io/library/node:20-alpine"

Cause: Docker buildx can be slow to fetch metadata from Docker Hub on macOS.

Workaround: Use existing local images without rebuilding:

cd docker
docker compose --env-file ../.env -f docker-compose.v2.yml -f docker-compose.local.yml --profile slack up -d --no-build

8. Port Conflicts (9000, 80)

Symptom: Bind for 0.0.0.0:9000 failed: port is already allocated

Cause: Dev containers (orienter--0) share ports with test containers (orienter-).

Fix: Stop dev containers first:

docker stop orienter-nginx-0 orienter-minio-0
docker rm orienter-nginx-0 orienter-minio-0

Then start test containers:

./run.sh test

9. ghcr.io Authentication Required

Symptom: ./run.sh test pull fails with 401 Unauthorized

Cause: Private images require GitHub authentication.

Fix: Either authenticate to ghcr.io or use local builds:

# Option 1: Authenticate
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

# Option 2: Use local images (skip pull)
./run.sh test  # builds locally

Verification

After cleanup and rebuild, verify:

# Check dist directories exist
ls packages/*/dist

# Run unit tests
pnpm run test:ci

# Run e2e tests with Docker stack
./run.sh test status  # Ensure all healthy
E2E_TESTS=true pnpm vitest run tests/e2e