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

• CLI Tool — inspect services, generate docs, list services without running a server
• Web Dashboard — interactive two-pane interface with Bootstrap 5 styling
• Auto-discovery — scan ~/hero/var/sockets/ for live RPC services
• Manual imports — add any OpenRPC spec by local file path or HTTP(S) URL
• Documentation generation — produce Markdown (agent templates) and HTML docs
• JSON-RPC 2.0 API — all data operations available via RPC
• Downloads — export OpenRPC JSON, Markdown, or Bootstrap HTML
• Dark/Light theme — responsive design with theme toggle
• Unix socket + TCP — dual binding for flexibility

Quick Start

Installation

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

# Or run directly
make run

CLI Usage

# List discovered services
hero_inspector list

# Scan for services
hero_inspector scan

# Fetch a service spec
hero_inspector spec hero_books

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

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

# Start web dashboard
hero_inspector serve --port 7400

Web Dashboard

hero_inspector serve

Then visit http://127.0.0.1:7400 in your browser.

Features:

• Sidebar with auto-discovered and manually added services
• Search and filter by status
• View service details, methods, parameters, and examples
• Download documentation in multiple formats
• Add/remove manual specs
• Real-time service status updates via SSE

Usage

Subcommands

Command	Purpose
serve	Start web UI server (default)
list	List discovered services (table)
scan	Run discovery scan
spec	Fetch and print OpenRPC spec
markdown	Generate Markdown doc
html	Generate HTML doc
add	Register manual spec (file or URL)
remove	Remove manual spec

Options

hero_inspector serve [OPTIONS]
  --socket-dir <path>     Socket directory [default: ~/hero/var/sockets]
  --port <port>           TCP port to bind [default: 7400]
  --refresh <secs>        Auto-scan interval [default: 30]
  --open                  Open browser after starting

Examples

# List services in JSON format
hero_inspector list --format json

# Verbose scan output
hero_inspector scan --verbose

# Specify socket directory
hero_inspector list --socket-dir /custom/sockets

# Add a local OpenRPC spec
hero_inspector add /path/to/openrpc.json --name "My API"

# Add a remote spec
hero_inspector add https://api.example.com/openrpc.json

# Remove by ID or name
hero_inspector remove "My API"

JSON-RPC API

When running in server mode, all operations are available via JSON-RPC 2.0 at POST /rpc.

Methods

Method	Params	Returns	Description
inspector.services	{}	Vec<ServiceEntry>	All services
inspector.service	{service_id}	ServiceEntry	Single service
inspector.scan	{}	{triggered, services_count}	Trigger re-scan
inspector.openrpc	{service_id}	OpenRPC JSON	Parsed spec
inspector.markdown	{service_id}	Markdown string	Generated docs
inspector.html	{service_id}	HTML string	Generated docs
inspector.add	{source, name?}	{service_id, title, methods_count}	Add manual spec
inspector.remove	{service_id}	{}	Remove spec
rpc.discover	[]	OpenRPC doc	Inspector's own spec
admin.health	{}	{status, uptime}	Health check

Example

curl -X POST http://127.0.0.1:7400/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "inspector.services",
    "params": {}
  }'

Service Discovery

Auto-Discovery

Hero Inspector scans ~/hero/var/sockets/ for Unix domain sockets and probes them with the JSON-RPC rpc.discover method.

Service Status:

• healthy — connected + valid OpenRPC spec
• unhealthy — connected but invalid spec
• inactive — socket exists but connection refused
• non_rpc — connected but not a JSON-RPC endpoint
• unknown — not yet probed

Manual Sources

Manually added specs are persisted to ~/.hero/inspector/manual_sources.json and survive restarts.

Add a spec:

hero_inspector add /path/to/openrpc.json --name "My API"

Remove a spec:

hero_inspector remove "My API"

Configuration

Hero Inspector uses sensible defaults:

Setting	Default	Env Var
Socket directory	~/hero/var/sockets	INSPECTOR_SOCKET_DIR
TCP port	7400	INSPECTOR_PORT
TCP host	127.0.0.1	INSPECTOR_HOST
Refresh interval	30 seconds	INSPECTOR_REFRESH
Probe timeout	3 seconds	INSPECTOR_PROBE_TIMEOUT

Architecture

Crate Structure

src/
├── main.rs               ← CLI entry point
├── lib.rs                ← Public API
├── cli/                  ← Subcommand implementations
├── config.rs             ← Configuration builder
├── manifest.rs           ← Manual sources persistence
├── scanner.rs            ← Socket discovery & probing
├── cache.rs              ← In-memory service cache
├── probe.rs              ← OpenRPC fetching (socket/file/URL)
├── generator/            ← Markdown & HTML generation
├── server/               ← Web server & API
│   ├── routes.rs         ← HTTP routes
│   ├── rpc.rs            ← JSON-RPC dispatch
│   ├── sse.rs            ← Server-sent events
│   └── mcp.rs            ← MCP integration
├── assets.rs             ← Static asset embedding
└── templates/            ← Askama HTML templates

Data Model

ServiceEntry — represents a discovered or manually added service:

• service_id — stable UUID
• title — display name
• source_kind — Socket | File | Url
• status — Healthy | Inactive | etc.
• openrpc_json — cached spec
• methods_count — number of RPC methods
• error — error message if failed

SourceKind — where the spec came from:

• Socket — auto-discovered Unix domain socket
• File — local file path
• Url — HTTP(S) URL

Building

Development

# Build debug binary
make build

# Run with logging
RUST_LOG=debug make run

# Run tests
make test

# Run cargo check
make check

Release

# Build and install to ~/hero/bin
make install

# Or manual build
cargo build --release -p herolib_inspector

Dependencies

• Async: tokio
• Web: axum, tower, hyper
• Templates: askama
• Serialization: serde, serde_json
• CLI: clap
• Utilities: dirs, chrono, uuid, comfy-table, colored

All dependencies are pure Rust — no C dependencies.

Development

Project Structure

hero_inspector/
├── Cargo.toml            ← Package metadata
├── Makefile              ← Build targets
├── SPEC.md               ← Detailed spec
├── README.md             ← This file
├── build.sh              ← Build script
├── run.sh                ← Run script
├── install.sh            ← Install script
├── src/                  ← Rust source code
├── templates/            ← Askama HTML templates
├── static/               ← CSS, JS, fonts, favicon
└── scripts/              ← Build and test scripts

Adding a New Service

To manually add a service via CLI:

hero_inspector add https://api.example.com/openrpc.json --name "Example API"

Via JSON-RPC:

curl -X POST http://127.0.0.1:7400/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "inspector.add",
    "params": {
      "source": "https://api.example.com/openrpc.json",
      "name": "Example API"
    }
  }'

Customizing the Web UI

The web dashboard uses:

• Bootstrap 5.3.3 — CSS framework
• Bootstrap Icons 1.13.1 — icon set
• Unpoly 3.12.1 — AJAX + morphing
• Askama — server-side templating

Edit templates in templates/ and styles in static/css/dashboard.css.

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
• URL fetching restricted to HTTP/HTTPS

Troubleshooting

Services not discovered

Ensure sockets exist in ~/hero/var/sockets/:

ls -la ~/hero/var/sockets/

Connection refused

Check if services are running:

hero_inspector scan --verbose

Port already in use

Specify a different port:

hero_inspector serve --port 7401

View logs

RUST_LOG=debug hero_inspector serve

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

See LICENSE file in repository root.

Related

• Hero OS — Operating system
• OpenRPC — Service specification standard
• JSON-RPC 2.0 — RPC protocol