aev-web 0.1.1

# aev-web

`aev-web` is the Aev web terminal plugin crate from Trevor Knott / Knott Dynamics. It provides a local, token-protected HTTP server for controlling PTY-backed terminal sessions from a browser or another local tool.

It also exports the future Aev plugin entrypoint `aev_plugin_init` and advertises the `aev.plugin.v1` manifest contract.

## Package

- Crate: `aev-web`
- Binary: `aev-web`
- Plugin ID: `aev-web`
- Plugin entrypoint: `aev_plugin_init`
- Protocol: `aev.plugin.v1`
- Author: Trevor Knott
- Organization: Knott Dynamics
- Repository: `https://github.com/Tknott95/AevWeb`

## What It Does

- Starts a local HTTP server, default `127.0.0.1:8765`.
- Generates a bearer token unless `AEV_WEB_TOKEN` is provided.
- Serves a small browser UI at `/`.
- Creates PTY-backed shell sessions with UUIDv7 IDs.
- Lets clients write terminal input and poll terminal output.
- Keeps output in a bounded in-memory ring buffer.
- Exposes an Aev plugin manifest at `/api/manifest`.

## Install

From crates.io:

```bash
cargo install aev-web
```

From source:

```bash
git clone https://github.com/Tknott95/AevWeb.git
cd AevWeb
cargo run
```

## Quick Start

Run with a generated token:

```bash
aev-web
```

Run with a stable token:

```bash
AEV_WEB_TOKEN=replace-with-a-secret aev-web --bind 127.0.0.1:8765
```

The server prints a local URL like:

```text
open http://127.0.0.1:8765/?token=<token>
```

Open that URL in a browser on the same machine.

## Configuration

| Setting | CLI | Environment | Default |
| --- | --- | --- | --- |
| Bind address | `--bind` | `AEV_WEB_BIND` | `127.0.0.1:8765` |
| API token | `--token` | `AEV_WEB_TOKEN` | generated UUIDv7 token |

Keep the default loopback bind unless you intentionally expose terminal access through a separate bridge such as `aev-bridge`.

## HTTP API

Public health endpoint:

```bash
curl http://127.0.0.1:8765/health
```

Authenticated requests use `Authorization: Bearer <token>`.

Create a session:

```bash
curl -sS -X POST http://127.0.0.1:8765/api/sessions \
  -H "Authorization: Bearer $AEV_WEB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Create a custom command session:

```bash
curl -sS -X POST http://127.0.0.1:8765/api/sessions \
  -H "Authorization: Bearer $AEV_WEB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"command":"/bin/sh","args":["-lc","pwd && whoami"],"rows":24,"cols":100}'
```

Write terminal input:

```bash
curl -sS -X POST http://127.0.0.1:8765/api/sessions/$SESSION_ID/input \
  -H "Authorization: Bearer $AEV_WEB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data":"ls -la\r"}'
```

Read terminal output:

```bash
curl -sS "http://127.0.0.1:8765/api/sessions/$SESSION_ID/output?since=0" \
  -H "Authorization: Bearer $AEV_WEB_TOKEN"
```

Terminate a session:

```bash
curl -sS -X DELETE http://127.0.0.1:8765/api/sessions/$SESSION_ID \
  -H "Authorization: Bearer $AEV_WEB_TOKEN"
```

## API Routes

- `GET /health` returns public server health.
- `GET /api/manifest` returns the `aev-web` plugin manifest.
- `POST /api/sessions` creates a PTY-backed terminal session.
- `GET /api/sessions` lists active sessions.
- `GET /api/sessions/{id}` returns one session summary.
- `GET /api/sessions/{id}/output?since={cursor}` reads terminal output.
- `POST /api/sessions/{id}/input` writes terminal input.
- `DELETE /api/sessions/{id}` terminates a session.

## Aev Registration

The current Aev plugin board validates descriptors and contracts. It does not load plugin code yet. Register the descriptor with:

```text
/plugins add aev-web git https://github.com/Tknott95/AevWeb.git aev_plugin_init tool,terminal,web,local-http,bearer-auth
/plugins validate all
```

See `examples/plugins.json` for an equivalent `.aev/plugins.json` entry.

## Use With aev-bridge

Use `aev-web` as the local terminal owner and `aev-bridge` as the phone/LAN bridge:

```bash
AEV_WEB_TOKEN=replace-with-a-secret aev-web
```

Then start `aev-bridge` with the same upstream token:

```bash
AEV_WEB_TOKEN=replace-with-a-secret AEV_BRIDGE_TOKEN=phone-secret aev-bridge
```

## Security

- Treat `AEV_WEB_TOKEN` as terminal access.
- Keep `aev-web` bound to loopback unless you know exactly why it must be reachable elsewhere.
- Prefer `aev-bridge` for phone access instead of exposing `aev-web` directly.
- The browser UI stores the token in local storage for convenience.
- Do not put real tokens in committed `.env` files.

## Development

```bash
cargo fmt --check
cargo test
cargo clippy --all-targets -- -D warnings
cargo publish --dry-run
```

## Release Notes

See `CHANGELOG.md`.