MeshBot/AGENTS.md

MeshBot — Workflow Rules

Change process (mandatory)

1. Small, incremental changes — work is done one change at a time, in smaller parts; each part must be tested thoroughly with unit tests covering it before moving on. Connected issues/tasks that reference the same part of code MAY be done together on one branch/PR with a single version bump (e.g. two tweaks to the same codec function).
2. Feature branch + PR — every change lands on a feature branch off main (no direct pushes to main). The branch carries the commits below; open a pull request to main.
3. Changelog entry — every such change is listed in CHANGELOG.md with date, time and version (format: ## v<version> — YYYY-MM-DD HH:MM, then bullet points of what changed).
4. Version bump — the version is updated in package.json.
5. Verification must pass — there is no CI pipeline yet; before opening a PR both local checks must be green: npm run build and npm test (vitest unit suite).
6. Tag + manual deploy after merge — once merged, tag the version on main (e.g. v0.1.0). The service (http://bot.dev.kkhost.pl) is updated manually afterwards: docker compose up -d --build on the host.

Verification

1. Local checks — npm run build (nest build) and npm test (vitest; no e2e suite yet). Both must pass before a PR is opened.
2. Docker — docker compose build, then after docker compose up -d: curl -s -H "Host: bot.dev.kkhost.pl" http://localhost/api/status returns JSON ({ connected, myNodeNum, host, port }). "connected":false is normal while the bridge/device is down — the service retries every 5 s.

API

1. Live base URL — http://bot.dev.kkhost.pl (Traefik → docker-compose stack on this host; container port 3000 via external network dev_net, no published ports).
2. Endpoints — all under the /api global prefix: GET /api/status ({ connected, myNodeNum, host, port }), POST /api/send (body { "text": "...", "to"?: <node number | "!b" | "broadcast"> }, returns { id }), GET /api/channels (the device's Meshtastic channels as { index, name, uplinkEnabled, downlinkEnabled }[]; psk/keys redacted), GET /api/nodes (known nodes sorted by num as { num, longName?, shortName?, hwModel?, batteryLevel?, lastHeard: number|null, position?: { lat, lon, alt? } }[], from the initial sync plus live POSITION_APP updates; reset on reconnect) and GET /api/nodes/:id (lookup by exact node number/numeric string, then case-insensitive exact long/short name, else unique substring; 404 when ambiguous or missing). Scalar API docs are served at / (OpenAPI JSON at /docs-json). Keep this list in sync with the controller. All POST /api/send traffic targets channel index 2 (testowy) on purpose — never the primary channel; override via MESH_SEND_CHANNEL (default 2).

Other

1. For longer terminal tasks you should use pty_* tools.
2. Host npm (10.9.4) has an arborist crash bug ("edgesOut") — if plain npm misbehaves on installs, use npx npm@latest .... The lockfile must stay in sync with package.json: the Docker build runs npm ci.