RnD/EVOLV

Files

znetsixe 6e6699c763 tools: add physics-sanity + Docker MCP scaffolding + tools/README

- tools/physics-sanity/ — JS library of cross-node balance helpers
  (mass / hydraulic / hydraulic-power / oxygen-transfer / energy) with
  7 unit tests + a CLI demo. Designed for `require()` from per-node
  integration tests where shape-based unit tests miss physically-
  impossible plant states.
- tools/docker-compose.yml + tools/mcp/{node-red-admin,influxdb,browser}
  scaffolding — placeholder Dockerfiles + a ROADMAP.md for the Node-RED
  admin MCP. Compose file is the target shape for the Q3-2026 migration
  to the central MCP server; the per-service Dockerfile stays in this
  repo as the canonical definition either way. Implementations are TODO.
- tools/README.md — top-level tooling index; documents the CI order for
  running every tool on a PR.
- .gitignore: ignore tools/.env (developer-specific MCP endpoints).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-19 10:16:47 +02:00

2.4 KiB

Raw Blame History

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):

cd tools && docker compose --profile mcp up -d

CI integration

Recommended order on every PR:

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

tools/<name>/package.json with a bin entry.
tools/<name>/bin/<name>.js — must accept --json and exit 1 on drift.
tools/<name>/README.md — one-page docs.
Add a row to this README + a row to CLAUDE.md § Tooling.
Wire into the CI snippet above.

2.4 KiB Raw Blame History

EVOLV tooling (tools/)