`.claude/skills/run-app/SKILL.md`

52 lines
---
name: run-app
description: Launch and drive the designerwallcoverings-ai root app (the "Vision-Match a Room to Wallcovering" Gemini tool, server.js). Use for "/run", "run the app", "start the DW ai app", "launch server.js", or to verify a change to the root storefront/vision-match server works locally. Covers the missing-deps + port-collision gotchas.
---

# Run the designerwallcoverings-ai root app

The repo root is a small Express app (`designerwallcoverings-ai`, `npm start` = `node server.js`).
It is the **Vision-Match a Room to Wallcovering** tool (Gemini vision), NOT one of the ~130 pm2
microservices. It loads ~8,200 products from local data at boot.

## Verified launch recipe

```bash
cd ~/Projects/designerwallcoverings

# 1. Deps are gitignored and often absent — install if node_modules is missing.
[ -d node_modules ] || npm install --no-audit --no-fund   # express + multer only, ~79 pkgs

# 2. Default port is 9925. 9925 is usually free, but nearby ports (9926, etc.)
#    are held by OTHER pm2 apps — a 401 on a "free-looking" port means another
#    app is there. Pick a genuinely free port and pin BIND to localhost.
for p in $(seq 9940 9960); do lsof -ti:$p >/dev/null 2>&1 || { PORT=$p; break; }; done
PORT=$PORT BIND=127.0.0.1 node server.js > /tmp/dwrun.log 2>&1 &
sleep 2.5; cat /tmp/dwrun.log
# expect: "designerwallcoverings.ai on http://127.0.0.1:<PORT> · 8227 products · ga=… · gemini_key=false"
```

## Drive it (routes)

`GET /` · `GET /about` · `GET /ads.txt` · `GET /health` · `POST /api/match` · `POST /api/match-url`

```bash
B=http://127.0.0.1:$PORT
curl -s -o /dev/null -w "/ -> %{http_code}\n" $B/           # 200, title "Vision-Match a Room…"
curl -s $B/health                                           # {"ok":true,"products":8227,...}
```

## Gotchas
- **`Cannot find module 'express'`** → deps not installed; run step 1.
- **`gemini_key=false`** → `GEMINI_API_KEY` is empty in `.env`, so `POST /api/match`
  (the core room-photo → wallcovering vision call) cannot run. It is a **metered Gemini
  call (~$0.0006/image)** — only exercise it deliberately, with the key sourced from the
  secrets store, and show the cost.
- **Port 9925/9926 confusion** → nearby ports are occupied by other pm2 services; always
  scan for a free one rather than assuming.

## Cleanup
```bash
kill $(lsof -ti:$PORT) 2>/dev/null   # stop the dev instance you started
```