prospector/scripts/README.md

scripts — local install & run

One-command setup and launch for the prospector operator app on this machine. All are reachable through ./run (preferred) or by direct execution.

Script	./run	Purpose
install.sh	./run install	Deps → env files → DB + migrations → build API + web → tray app → MCP. Idempotent. --launch opens the app after. Skip steps with SKIP_DB/SKIP_TRAY/SKIP_MCP.
app.sh	./run app	Start API + the vite-preview front door, health-check, open Chrome as an app window. --build rebuilds first; --detach runs in the background (used by the tray). Reuses an already-running instance.
stop.sh	./run stop	Stop the detached app — kills only the PIDs in .run/app.pids, never a blanket node kill.
make-tray.sh	./run tray	Build the Prospector.app menu-bar tray (~/Applications): ❖ status icon with Open / Stop / Quit. AppleScript-ObjC + built-in icon tooling, no Swift/deps.
migrate.sh	./run db:migrate	Apply pending migrations/*.sql, tracked in a _prospector_migrations ledger (each file runs once).
lib.sh	—	Shared helpers (logging, .env.local loading, psql locating). Sourced, not run.
mcp/install-mcp.sh	./run install:mcp	Register the agent/coworker MCP ("prospector") into Claude Desktop + global ~/.claude/mcp-config.json (for Claude Code / desktop coworker). Builds the mcp package, handles secrets from .env or vault, safe edits.

Quick start

./run install --launch     # set up everything and open the app
# or, step by step:
./run install              # set up
./run app                  # launch + open the Chrome app window
./run install:mcp          # (separate) register the prospector MCP for agents in Claude

Requirements

• Node 20+ and npm.
• PostgreSQL reachable per .env.local (PROSPECTOR_DB_*). The installer finds psql on PATH or in common macOS installs (Homebrew, Postgres.app); set PSQL=/path/to/psql to override. No psql → DB step is skipped with a hint.
• Google Chrome for the app-window experience (falls back to default browser).

How the pieces fit

• The API (dist/main.js) listens on PROSPECTOR_API_PORT (3210) and owns its Postgres DB. Routes are guarded by a bearer service token.
• The panel is the built web/dist, served by vite preview, which proxies /api/* → the API and injects the token (so it never lives in browser JS). This is the same proxy vite uses in dev — see web/vite.config.ts.
• app.sh starts both, waits for /health, then opens http://localhost:<web>/#/markets as a Chrome --app window. Ctrl-C stops only the processes it started (never a blanket node kill).

Env files (created by the installer if absent)

• .env.local — API config (port, PROSPECTOR_DB_*, service token, upstreams).
• web/.env.local — PROSPECTOR_API_URL + PROSPECTOR_SERVICE_TOKEN for the panel proxy. Keep its token equal to the API's.

Re-running install never overwrites existing env files.

Remote / mesh access (optional, gated)

By default the panel binds localhost only — not reachable from the mesh. To use it from another mesh host (this laptop is 10.9.0.3 on the WG mesh):

1. Set a passcode in web/.env.local — the panel has no login of its own, so this gate is required before exposing it:

   PROSPECTOR_PANEL_PASSCODE=your-passcode
   

   Empty = gate off (localhost-only). The passcode is checked by the vite preview front door (HMAC cookie, HttpOnly); the service token is never injected until a valid session exists.
2. Bind beyond localhost and relaunch:

   ./run stop && ./run app --host          # all interfaces (mesh + LAN)
   ./run app --host=10.9.0.3               # mesh IP only
   

   Then open http://10.9.0.3:4173/#/markets from the other host and enter the passcode. ./run app --host without a passcode set prints a loud warning.

The API itself (:3210) is bearer-guarded regardless; only the panel front door needs the passcode. The API does not need to be mesh-exposed — the panel proxies to it over localhost.