@ctrlpi/ctrlpi-lab 0.9.25 → 0.9.26

package/README.md

@@ -1,7 +1,7 @@
 # ctrlPi Lab
 
 [![Platform: Cross-Platform](https://img.shields.io/badge/platform-Cross--Platform-006400.svg)](#quick-start)
-[![Version 0.9.25](https://img.shields.io/badge/version-0.9.25-blue.svg)](https://github.com/ctrlpi/ctrlpi-lab/tags)
+[![Version 0.9.26](https://img.shields.io/badge/version-0.9.26-blue.svg)](https://github.com/ctrlpi/ctrlpi-lab/tags)
 [![Node.js 20+](https://img.shields.io/badge/node.js-20%2B-blue.svg)](https://nodejs.org/)
 [![Auth: Api-Key](https://img.shields.io/badge/auth-Api--Key-orange.svg)](#usage)
 [![License: MIT](https://img.shields.io/badge/license-MIT-188038.svg)](LICENSE)
@@ -12,7 +12,7 @@ A local browser dashboard for your ctrlPi setup. Test GPIO and sensor endpoints,
 watch webhook events, and tail agent logs, with zero dependencies.
 
 Runs on **macOS, Linux, and Windows** with **Node.js 20+**. The dashboard connects
-to an agent’s REST API; install `pi-gpio-api` or `pico-gpio-api` on your board separately.
+to an agent’s REST API; install `pi-gpio-api`, `pico-gpio-api`, or `esp32-gpio-api` on your board separately.
 
 ## Quick start
 
@@ -24,7 +24,7 @@ npx @ctrlpi/ctrlpi-lab
 
 Your browser will open automatically at [http://localhost:7474](http://localhost:7474).
 
-Or clone and run directly (no `npm install` needed):
+Or run directly from source without installing dependencies:
 
 ```bash
 git clone https://github.com/ctrlpi/ctrlpi-lab.git
@@ -32,34 +32,8 @@ cd ctrlpi-lab
 node ctrlpi-lab.js
 ```
 
-You can also start it with `npm start`. Python is needed only for the mock-agent tests.
-By default, the dashboard listens only on this computer (`127.0.0.1`). To allow LAN
-devices to connect, start it with `--host 0.0.0.0`:
-
-```bash
-npx @ctrlpi/ctrlpi-lab --host 0.0.0.0
-```
-
-LAN access also exposes the dashboard’s agent credentials and unrestricted proxy to those devices.
-
-To skip opening a browser:
-
-```bash
-npx @ctrlpi/ctrlpi-lab --no-open
-```
-
-To change the port on macOS/Linux:
-
-```bash
-PORT=9000 npx @ctrlpi/ctrlpi-lab
-```
-
-Or in Windows PowerShell:
-
-```powershell
-$env:PORT = "9000"
-npx @ctrlpi/ctrlpi-lab
-```
+By default, the dashboard listens only on the local computer (`127.0.0.1`). To allow LAN
+devices to connect, pass `--host 0.0.0.0` (LAN access exposes the dashboard’s agent credentials and unrestricted proxy to those devices). Use `--no-open` to skip opening a browser, or `PORT=9000` to select a different port.
 
 ## Discovery
 
@@ -80,7 +54,7 @@ and verifies a supplied key through the backend proxy before saving.
 3. Open **Logs** to search the agent’s output, or **Webhooks** to inspect the public
    ctrlpi.com test feed when that target is configured on your agent.
 
-The **Welcome to ctrlPi** panel includes Pi and Pico installation steps.
+The **Welcome to ctrlPi** panel includes Pi, Pico, and ESP32 installation steps.
 **API - cURL Examples** provides nine commands using your selected address and key.
 
 ### Examples
@@ -101,22 +75,24 @@ bridge target is configured; otherwise, the agent logs the events.
 
 ## Configuration
 
-Saved agents are stored in the shared `config.json`'s `agents[]` (`{name, ip, port, api_key}`), the
+Saved agents are stored in the shared `agents-config.json`'s `agents[]` (`{name, ip, port, api_key, updated_at}`), the
 one list every ctrlpi project reads - add an agent here and `mcp-bridge`, `studio-bridge` and the
 smart-home bridges all see it. This dashboard's own `lab-config.json` holds the rest: the agent it
 is currently pointed at (`selected_agent: {ip, port}`, its key coming from that agent's `agents[]`
-entry), the MCP server (`mcp: {ip, port, api_key}`), and `online_agents` (what the last network scan
+entry) and `online_agents` (what the last network scan
 reached, retained as scan history; saved agents remain selectable), as `ip:port` strings. Every host uses the same
-`ip` + `port` pair, never a URL, and `mcp-bridge`'s own key is `mcp.api_key`, so no two keys mean
-the same thing.
+`ip` + `port` pair, never a URL.
 
 > **Where the config lives:** in `~/.ctrlpi/`, always - never next to `ctrlpi-lab.js`, whatever way you
-> started it. Two files: the shared **`~/.ctrlpi/config.json`** holds `agents[]` (every ctrlpi project
+> started it. Two files: the shared **`~/.ctrlpi/agents-config.json`** holds `agents[]` (every ctrlpi project
 > reads and updates that one list), and **`~/.ctrlpi/lab-config.json`** holds what only this dashboard
-> owns (`selected_agent`, the `mcp` section, `online_agents`). Pass `--config <path>` (a `.json` file,
+> owns (`selected_agent`, `online_agents`). Pass `--config <path>` (a `.json` file,
 > or a directory to hold both) to put them anywhere else.
+>
+> When reading the shared agents, ctrlpi-lab also checks if `/var/lib/homebridge/ctrlpi-agents-config.json`
+> exists; if so, it reads it (read-only) and reconciles agents whose `updated_at` is newer. It never writes to the Homebridge config file.
 
-Both files are optional. For example, the shared `~/.ctrlpi/config.json` can contain:
+Both files are optional. For example, the shared `~/.ctrlpi/agents-config.json` can contain:
 
 ```json
 {
@@ -135,21 +111,18 @@ The dashboard’s `~/.ctrlpi/lab-config.json` stores its selected agent and scan
 }
 ```
 
-The backend also preserves optional MCP settings as
-`mcp: {ip, port, api_key}` for compatibility; the current dashboard has no MCP tab
-or registered stdio MCP routes. Use `mcp-bridge` separately for MCP tools.
-
 - The header shows the selected agent’s IP and port after its model. Use the arrow to choose a saved agent,
   or the **+** button to add an IP/hostname, port, and API key. The key icon edits the selected agent’s key.
-- Environment overrides: `API_KEY` (agent key), `MCP_API_KEY` (MCP HTTP key).
-- Discovered and last-used agents are saved back to the shared `~/.ctrlpi/config.json` automatically,
+- Environment override: `API_KEY` sets the agent key.
+- Discovered and last-used agents are saved back to the shared `~/.ctrlpi/agents-config.json` automatically,
   so you don't have to edit it by hand.
 
 ## Tabs
 
-- **API**: test GPIO, sensor, and configuration endpoints. The sidebar includes board pinouts,
-  **Welcome to ctrlPi** with Pi/Pico installation instructions, and nine **API - cURL Examples**
-  aligned with the Pi API README and populated with the selected address/key. Changing the
+- **API**: test GPIO, sensor, and configuration endpoints. The sidebar's Get Started section has
+  **Welcome to ctrlPi** with Pi, Pico and ESP32 installation steps, nine **API - cURL Examples**
+  aligned with the Pi API README and populated with the selected address/key, and a **Pinouts**
+  link to the board pinouts on ctrlpi.com. Changing the
   agent’s API key is available only in the red Danger Zone of Config Update.
 - **Logs**: compact log viewer with text search. Webhook tags are orange.
   Red trash and refresh icons sit immediately after the search box. Reset Log
@@ -164,69 +137,56 @@ status indicator, and network scan button.
 
 ## How it works
 
-Agent requests, including the + form’s health/key checks, pass through
-`/api/proxy/url` using `piApiFetch`, avoiding browser CORS restrictions. The backend uses
-Node’s built-in `http` and `fetch`, assembles HTML from `pages/`, and caches it in memory.
-The Logs tab fetches the selected agent’s `/logs` through that proxy and filters in the browser;
-`/api/logs` remains available as a separate backend helper. Webhook feed requests also use the proxy.
-
-After editing HTML, restart the server and refresh the browser. In development mode
-(`npm run dev`), the header’s **Reload page cache** icon rebuilds the cache and reloads the page.
-The day/night toggle only changes the theme; it does not rebuild the cache.
-
-### Backend endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/` | The dashboard HTML (assembled from `pages/` and cached in memory) |
-| `GET` | `/api/default-config` | Connection defaults plus `local_network_prefix` and `dev_mode` |
-| `POST` | `/api/save-config` | Saves `api_host` / `api_port` and/or the `mcp` section to `lab-config.json` |
-| `GET` · `POST` | `/api/servers` | List / add saved agents (kept in the shared `config.json`) |
-| `GET` | `/api/scan?port=` | Scans the local subnet via `/hello`; port defaults to 8314. Add `stream=1` for incremental NDJSON results |
-| `GET` | `/api/logs` | Proxies the agent's `GET /logs`; supports `?limit=`, `?search=`, `?category=` |
-| `*` | `/api/proxy/url?url=` | General HTTP proxy for the browser's GPIO / MCP-HTTP calls (also relays the `Mcp-Session-Id` header) |
-| `POST` | `/api/reload-cache` | Rebuilds cached dashboard HTML from disk |
-| `GET` | `/images/{file}` · `/pages/{file}` | Serves image and page files |
+The dashboard runs on Node's built-in HTTP server with zero runtime dependencies. Browser
+requests to agents pass through `/api/proxy/url` using `piApiFetch`, avoiding CORS restrictions.
+HTML assets in `pages/` are assembled and cached in memory. In development mode (`npm run dev`),
+the header’s **Reload page cache** icon rebuilds the cache and reloads the page.
+
+The dashboard answers only requests addressed to an IP address, `localhost`, this computer's
+own name (or `<name>.local`) or the `--host` value, and only from its own page. A website you
+visit cannot read your agent keys or reach your agents through it.
 
 ## Tests and CI
 
-Requires Node 20+ and Python 3 (`python3`, or set `PYTHON` to its executable).
+Requires Node 20+ and Python 3 (`python3`, or set `PYTHON` to its executable). Python is needed only for the mock-agent tests.
 
 ```bash
 npm test                # unit tests + mock-agent HTTP integration tests
-npm run test:ci         # CI entry point; runs the same tests
 ```
 
 Integration tests launch the real lab server and a local copy of
 `ctrlpi-cli/mock_agent.py` on OS-assigned loopback ports. They use a temporary
 `--config` directory, preserve unrelated shared-config fields, and stop child
 processes and delete temporary configs after each run. No Pi, Pico, public webhook
-service, real credentials, or user configuration is needed. The fixture differs
-from the CLI copy only in its header and reporting the actual allocated port.
+service, real credentials, or user configuration is needed. The fixture is the same
+`mock_agent.py` the other ctrlPi projects test against.
 
 The lab supports `--no-open` to skip opening a browser and `--no-startup-scan`
-to skip automatic discovery. Tests use both, plus `HOST=127.0.0.1` and `PORT=0`;
-normal startup still opens the browser and discovers agents as before.
+to skip automatic discovery. Tests use both, plus `HOST=127.0.0.1` and `PORT=0`.
 
 No npm installation is needed for the app or tests. CI runs all nine combinations
 of Node 22, 24, and 26 with macOS, Linux (Ubuntu), and Windows. Each job starts the
 real lab server and the mock agent. There is no coverage reporting or coverage gate.
 
 Tests cover agent discovery/selection, adding agents, credentials, real proxy
-requests, GPIO write/read state, sensors, configuration persistence, logs, and
-webhook rendering. Dashboard tests use a small DOM stub, not a browser. Hardware
-timing/electrical behavior, real LAN discovery, external webhook delivery, MCP
-bridge interoperability, and visual layout remain outside this suite. The mock
+requests, the Host and Origin check, GPIO write/read state and form values, sensors,
+configuration persistence, logs, and webhook rendering. Dashboard tests use a small DOM stub, not a browser. Hardware
+timing/electrical behavior, real LAN discovery, external webhook delivery, and visual
+layout remain outside this suite. The mock
 agent approximates the REST contract; it does not replace tests on real hardware.
 
 ## Related projects
 
 - **[`pi-gpio-api`](https://github.com/ctrlpi/pi-gpio-api)**: Raspberry Pi GPIO REST server that reads inputs and drives outputs (and named sensors) over an HTTP API.
 - **[`pico-gpio-api`](https://github.com/ctrlpi/pico-gpio-api)**: Raspberry Pi Pico W port of the GPIO REST server, with the same endpoints, wire format, and auth.
-- **[`ctrlpi-cli`](https://github.com/ctrlpi/ctrlpi-cli)**: Command-line interface to the same agents, with shared agent configuration.
-- **`mcp-bridge`**: MCP server that exposes GPIO control as tools for AI agents (e.g. Claude), executing them over the agents' REST API.
-- **`homekit-bridge`**: native Apple HomeKit bridge that exposes GPIO pins and sensors as HomeKit accessories, driven over the agents' REST API.
-- **`matter-bridge`**: Matter bridge that exposes GPIO pins and sensors to any Matter platform (Apple Home, Google Home, Alexa, Home Assistant), driven over the agents' REST API.
+- **[`esp32-gpio-api`](https://github.com/ctrlpi/esp32-gpio-api)**: ESP32 port of the GPIO REST server for MicroPython, with the same endpoints, wire format, and auth.
+- **[`mcp-bridge`](https://github.com/ctrlpi/mcp-bridge)**: MCP server that exposes GPIO control as tools for AI agents (e.g. Claude), executing them over the agents' REST API.
+- **[`homebridge-ctrlpi`](https://github.com/ctrlpi/homebridge-ctrlpi)**: A Homebridge plugin that brings Raspberry Pi, Pico W, and ESP32 GPIO into Apple Home, by driving one or more GPIO agents over their REST API.
+- **`homekit-bridge`** *(coming soon)*: Native Apple HomeKit bridge that exposes GPIO pins and sensors as HomeKit accessories, driven over the agents' REST API.
+- **`matter-bridge`** *(coming soon)*: Matter bridge that exposes GPIO pins and sensors to any Matter platform (Apple Home, Google Home, Alexa, Home Assistant), driven over the agents' REST API.
+- **[`ctrlpi-cli`](https://github.com/ctrlpi/ctrlpi-cli)**: Command-line interface for interacting with ctrlPi agents, with shared agent configuration.
+- **[`pico-bay`](https://github.com/ctrlpi/pico-bay)**: Web app and MCP server for managing MicroPython and CircuitPython boards, such as the Raspberry Pi Pico and ESP32, over USB.
+- **`pi-bay`** *(coming soon)*: A local web app and MCP server for Raspberry Pi boards over the network. Edit files, open a remote terminal, and manage your Pi remotely.
 
 ## License