Hero Inspector

A CLI tool and web dashboard for discovering and documenting RPC services.

Hero Inspector scans your Hero OS service ecosystem, fetches OpenRPC specifications, generates documentation, and provides an interactive web UI for exploring your services.

Features

• Auto-discovery — scan ~/hero/var/sockets/ for live RPC services
• Web Dashboard — interactive two-pane interface with Bootstrap 5 styling
• CLI Tool — inspect services, generate docs, list services without running a server
• Manual imports — add any OpenRPC spec by local file path or HTTP(S) URL
• Documentation generation — produce Markdown and HTML docs
• JSON-RPC 2.0 API — all data operations available via RPC
• MCP Gateway — expose each healthy service as MCP-compatible endpoint
• Dark/Light theme — responsive design with theme toggle

Architecture

hero_inspector/
├── Cargo.toml                         # workspace root
├── Makefile
├── buildenv.sh
├── scripts/
│   ├── build_lib.sh
│   └── download-assets.sh
├── crates/
│   ├── hero_inspector/                # core library (herolib_inspector)
│   ├── hero_inspector_server/         # JSON-RPC backend (Unix socket only)
│   ├── hero_inspector_sdk/            # generated OpenRPC client
│   ├── hero_inspector_ui/             # web UI + HTTP server
│   └── hero_inspector_examples/       # SDK usage examples

Crate	Type	Description
herolib_inspector	library	Core logic: scanner, cache, probe, doc generation
hero_inspector_server	binary	JSON-RPC backend on Unix socket, CLI subcommands
hero_inspector_sdk	library	Generated typed client from OpenRPC spec
hero_inspector_ui	binary	Web dashboard (Unix socket + optional TCP via --http)
hero_inspector_examples	examples	SDK usage examples

Sockets

Component	Socket Path
Server (JSON-RPC)	~/hero/var/sockets/hero_inspector_server.sock
UI (HTTP)	~/hero/var/sockets/hero_inspector_ui.sock

The UI also supports TCP binding via --http --port 8802 for direct browser access. This is needed because the inspector UI proxies other services' web UIs.

Quick Start

# Clone and build
git clone ssh://forge.ourworld.tf/lhumina_code/hero_inspector.git
cd hero_inspector
make install

# Run both server and UI
make run

# Or run in debug mode
make rundev

CLI Usage

# List discovered services
hero_inspector_server list

# Scan for services
hero_inspector_server scan --verbose

# Fetch a service spec
hero_inspector_server spec hero_books

# Generate Markdown documentation
hero_inspector_server markdown hero_books --output docs.md

# Generate HTML documentation
hero_inspector_server html hero_books --output docs.html

# Start JSON-RPC backend only
hero_inspector_server serve

# Start web UI with TCP access
hero_inspector_ui --http --port 8802

JSON-RPC API

When the server is running, all operations are available via JSON-RPC 2.0.

Method	Description
inspector.services	List all services
inspector.service	Get single service by ID
inspector.scan	Trigger re-scan
inspector.openrpc	Get cached OpenRPC spec
inspector.markdown	Generate Markdown docs
inspector.html	Generate HTML docs
inspector.status	Health and stats
inspector.add	Register manual spec
inspector.remove	Remove manual spec
inspector.mcp_logs	MCP gateway logs
inspector.mcp_logs_clear	Clear MCP logs
admin.health	Simple health check
rpc.discover	Return this OpenRPC spec

Configuration

Setting	Default	Env Var
Socket directory	~/hero/var/sockets	INSPECTOR_SOCKET_DIR
TCP port (with --http)	8802	INSPECTOR_PORT
TCP host	127.0.0.1	INSPECTOR_HOST
Refresh interval	30 seconds	INSPECTOR_REFRESH
Probe timeout	3 seconds	INSPECTOR_PROBE_TIMEOUT

Building

make build       # Build release binaries
make check       # Fast code check
make test        # Run tests
make lint        # Run clippy
make install     # Build and install to ~/hero/bin
make clean       # Remove build artifacts

Security

• TCP listener is 127.0.0.1 only (never 0.0.0.0)
• No authentication required (localhost-only access)
• All OpenRPC text is HTML-escaped by Askama
• Inspector only calls rpc.discover — never executes arbitrary methods

License

See LICENSE file in repository root.