58 lines
2.4 KiB
Markdown
58 lines
2.4 KiB
Markdown
|
# EVOLV tooling (`tools/`)
|
||
|
|
|
||
|
|
Repo-local tools and MCP services for EVOLV development. All Node.js
|
||
|
|
native (no Python toolchain). Each tool encodes a rule that we've
|
||
|
|
previously discovered through a bug; skipping them re-opens those bugs.
|
||
|
|
|
||
|
|
See `CLAUDE.md` § "Tooling (Docker-first, local now, central later)"
|
||
|
|
for the operating doctrine.
|
||
|
|
|
||
|
|
## Tools (CLI)
|
||
|
|
|
||
|
|
| Tool | Path | What it does | Run |
|
||
|
|
|---|---|---|---|
|
||
|
|
| `contract-verify` | `tools/contract-verify/` | Diffs `nodes/<n>/CONTRACT.md` topic table vs `src/commands/index.js` | `node tools/contract-verify/bin/contract-verify.js` |
|
||
|
|
| `flow-lint` | `tools/flow-lint/` | Lints `examples/*.flow.json` against the flow-layout rule | `node tools/flow-lint/bin/flow-lint.js` |
|
||
|
|
| `wiki-gen` | `tools/wiki-gen/` | Regenerates AUTOGEN topic-contract blocks in per-node wikis | `node tools/wiki-gen/bin/wiki-gen.js` |
|
||
|
|
| `output-manifest-verify` | `tools/output-manifest-verify/` | Enforces the output-coverage manifest rule | `node tools/output-manifest-verify/bin/output-manifest-verify.js` |
|
||
|
|
| `physics-sanity` | `tools/physics-sanity/` | Library of cross-node balance helpers; import from tests | `require('../../tools/physics-sanity')` |
|
||
|
|
|
||
|
|
CI-friendly: every tool accepts `--json` (JSON output) and exits non-zero
|
||
|
|
on findings.
|
||
|
|
|
||
|
|
## MCP services (Docker)
|
||
|
|
|
||
|
|
See `tools/mcp/README.md`. Three services scaffolded:
|
||
|
|
|
||
|
|
| Service | Purpose | Status |
|
||
|
|
|---|---|---|
|
||
|
|
| `mcp-node-red-admin` | Wraps Node-RED admin HTTP API | TODO (scaffold) |
|
||
|
|
| `mcp-influxdb` | Telemetry query + assertion | TODO (scaffold) |
|
||
|
|
| `mcp-browser` | Headless Playwright against the dashboard | TODO (scaffold) |
|
||
|
|
|
||
|
|
Start (once impls land):
|
||
|
|
```bash
|
||
|
|
cd tools && docker compose --profile mcp up -d
|
||
|
|
```
|
||
|
|
|
||
|
|
## CI integration
|
||
|
|
|
||
|
|
Recommended order on every PR:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
node tools/contract-verify/bin/contract-verify.js # 1. CONTRACT vs registry
|
||
|
|
node tools/flow-lint/bin/flow-lint.js # 2. Flow JSON shapes
|
||
|
|
node tools/wiki-gen/bin/wiki-gen.js --check # 3. Wiki AUTOGEN blocks
|
||
|
|
node tools/output-manifest-verify/bin/output-manifest-verify.js # 4. Manifest coverage
|
||
|
|
```
|
||
|
|
|
||
|
|
Each is fast (<1 s on the whole repo).
|
||
|
|
|
||
|
|
## Adding a new tool
|
||
|
|
|
||
|
|
1. `tools/<name>/package.json` with a `bin` entry.
|
||
|
|
2. `tools/<name>/bin/<name>.js` — must accept `--json` and exit 1 on drift.
|
||
|
|
3. `tools/<name>/README.md` — one-page docs.
|
||
|
|
4. Add a row to this README + a row to `CLAUDE.md` § Tooling.
|
||
|
|
5. Wire into the CI snippet above.
|