# Local Development Servers - Troubleshooting ## Quick Reference **Use the scripts** (see ct skill for full documentation): ```bash ./scripts/start-local-dev.sh # Start both servers ./scripts/stop-local-dev.sh # Stop both servers ./scripts/restart-local-dev.sh # Restart both ./scripts/restart-local-dev.sh --force # Force kill first ./scripts/restart-local-dev.sh --clear-cache # Clear disposable caches (preserves spaces) ./scripts/restart-local-dev.sh --dangerously-clear-all-spaces # Clear databases/spaces ./scripts/restart-local-dev.sh --bg-updater # Also start background-charm-service ./scripts/check-local-dev.sh # Health check both servers ``` **URLs:** | What | URL | |------|-----| | Backend API | `http://localhost:8000` | | Frontend/Shell | `http://localhost:8000` | | Access a space | `http://localhost:8000/[space-name]` | **Logs:** - `packages/shell/local-dev-shell.log` - `packages/toolshed/local-dev-toolshed.log` **First-time browser login:** When accessing a space for the first time, you'll need to register: 1. Click "➕ Register" 2. Click "🔑 Generate Passphrase" 3. Click "🔒 I've Saved It - Continue" For Playwright testing, use: ```javascript await page.goto("http://localhost:8000//"); ``` --- ## Architecture CommonTools requires **two servers** for local development: 1. **Backend (Toolshed)** - Port 8000 - API, storage, runtime, proxies shell 2. **Frontend (Shell)** - Port 5173 - Dev server with hot reload (accessed via 8000 proxy) You cannot access spaces without BOTH running. Access the application at **port 8000**, which proxies to shell. The scripts handle starting them in the correct order. **Important:** Use `dev-local` (not `dev`) for shell when running against local Toolshed. The `dev` task points to production. **After editing runtime code:** Restart the servers to pick up changes. --- ## Troubleshooting ### Scripts Not Working **Check if ports are in use:** ```bash # macOS or Linux with lsof lsof -i :8000 # Toolshed lsof -i :5173 # Shell # Linux without lsof (use ss instead) ss -tlnp 'sport = :8000' # Toolshed ss -tlnp 'sport = :5173' # Shell ``` **Force restart:** ```bash ./scripts/restart-local-dev.sh --force ``` ### Verifying Servers Are Running ```bash ./scripts/check-local-dev.sh ``` This checks both process presence and HTTP health, exiting non-zero if anything is wrong. It supports the same `--port-offset`, `--shell-port`, and `--toolshed-port` flags as the other scripts. ### Common Issues | Symptom | Cause | Fix | |---------|-------|-----| | Commands hang/timeout | Servers not running | Run `./scripts/restart-local-dev.sh` | | Space shows errors | Only one server running | Ensure BOTH are running | | Port already in use | Previous server didn't stop | Use `--force` flag | | Stale data | Cache issues | Use `--clear-cache` flag (or `--dangerously-clear-all-spaces` for database issues) | | `*.ts.net` URLs hang | Not on Tailscale | Connect to CT network via Tailscale | | OAuth error: `Unexpected token '<'` | Fetching from wrong port | Use port 8000 for API calls ([see below](#oauth-returns-html-instead-of-json)) | | UI component changes not appearing | Shell doesn't watch packages/ui | Restart local dev server | ### Manual Fallback If scripts fail completely, manual process: ```bash # 1. Kill by port (choose based on your system) # macOS or Linux with lsof: lsof -ti :8000 | xargs kill -9 2>/dev/null # Toolshed lsof -ti :5173 | xargs kill -9 2>/dev/null # Shell # Linux without lsof (use ss + awk): ss -tlnp 'sport = :8000' | awk -F'pid=' 'NF>1{split($2,a,","); print a[1]}' | xargs kill -9 2>/dev/null ss -tlnp 'sport = :5173' | awk -F'pid=' 'NF>1{split($2,a,","); print a[1]}' | xargs kill -9 2>/dev/null # 2. Wait for cleanup sleep 2 # 3. Start backend (Terminal 1) cd packages/toolshed SHELL_URL=http://localhost:5173 deno task dev # 4. Start frontend (Terminal 2) cd packages/shell TOOLSHED_PORT=8000 deno task dev-local ``` **Alternative: Local shell with cloud backend:** ```bash cd packages/toolshed SHELL_URL=http://localhost:5173 API_URL=https://toolshed.saga-castor.ts.net/ deno task dev ``` **Environment setup:** Copy `.env.example` to `.env` in the toolshed directory. See `packages/toolshed/env.ts` for all available environment variables. ### Checking Logs ```bash # View recent shell errors tail -50 packages/shell/local-dev-shell.log # View recent toolshed errors tail -50 packages/toolshed/local-dev-toolshed.log # Follow logs in real-time tail -f packages/shell/local-dev-shell.log tail -f packages/toolshed/local-dev-toolshed.log ``` ### OAuth Returns HTML Instead of JSON **Error:** `SyntaxError: Unexpected token '<', " **Note:** This package is still named `background-charm-service` in the > codebase. "Charm" is the legacy name for "piece"; they refer to the same > concept. The background-charm-service polls registered pieces and triggers their `bgUpdater` handlers server-side. This is **optional** - only needed if you're testing background/scheduled piece execution (e.g., auto-refreshing Google OAuth tokens). ### Quick Setup (Recommended) Use the `--bg-updater` flag with the local dev scripts: ```bash ./scripts/start-local-dev.sh --bg-updater # or ./scripts/restart-local-dev.sh --bg-updater ``` This waits for toolshed to be healthy, then starts the background service. The service log is at `packages/background-charm-service/local-dev-bg.log`. The stop script will also clean up the background service process. The system space cell is auto-created when a piece is first registered (e.g., during Google OAuth). ### Manual Setup If you prefer manual control: ```bash # 1. Ensure toolshed is running (uses "implicit trust" identity in dev mode) ./scripts/restart-local-dev.sh # 2. Start the background service from source cd packages/background-charm-service OPERATOR_PASS="implicit trust" API_URL="http://localhost:8000" deno task start ``` > **Optional:** The `add-admin-charm` task deploys an admin dashboard piece > into the system space. It is **not** required for normal background-service > operation -- the system space cell is bootstrapped automatically by > `setBGCharm()` during the OAuth callback when a piece is first registered. > Run it only if you want the admin dashboard: > > ```bash > cd packages/background-charm-service > OPERATOR_PASS="implicit trust" API_URL="http://localhost:8000" deno task add-admin-charm > ``` ### Registering a Piece for Background Updates Pieces must be registered to receive background polling: ```bash # Via curl curl -X POST http://localhost:8000/api/integrations/bg \ -H "Content-Type: application/json" \ -d '{"pieceId":"baedrei...","space":"did:key:z6Mk...","integration":"my-integration"}' ``` Or use the `` component in your piece's UI. ### Key Details - **Polling interval**: 60 seconds (default) - **Identity**: Must match toolshed's identity (in dev mode: `OPERATOR_PASS="implicit trust"`) - **bgUpdater triggers**: Service sends `{}` to the piece's `bgUpdater` Stream - **Logs**: Watch service output for `Successfully executed piece` messages ### Troubleshooting | Symptom | Cause | Fix | |---------|-------|-----| | `CompilerError: no exported member 'pattern'` | Binary version mismatch | Run `deno task build-binaries` | | `AuthorizationError` on system space | System space not yet bootstrapped | Register a piece (e.g., via OAuth) to auto-create it, or run optional `add-admin-charm` | | Piece not polling | Not registered | Register via `/api/integrations/bg` | See `packages/background-charm-service/CLAUDE.md` for more details.