hero_service

The canonical Hero service template — the "clone-me" starting point that contributors mirror when bootstrapping a new Hero service. Generated by hero_rpc_generator (see hero_service_scaffold skill), then tuned to satisfy lab infocheck with zero hand-edits.

Doubles as a meta-example: the shipped OSchema describes ServiceDefinition records — one per Hero service repo in lhumina_code. This is the seed of the future production scaffold service (hero_skills#261, parent hero_skills#262).

See PURPOSE.md for the component breakdown.

Quickstart

# Build the workspace (cargo build behind the scenes).
lab build --workspace

# Build + install every declared binary into $PATH_BUILD/bin.
lab service hero_service --install

# Register with hero_proc and start every server/admin/web binary.
lab service hero_service --start

# Status / stop.
lab service hero_service --status
lab service hero_service --stop

lab reads each crate's service.toml (via <bin> --info --json) and drives the whole build / install / start / stop pipeline on top of hero_proc. There is intentionally no Makefile, no scripts/*.sh, and no service_hero_service.nu file (ADR-0001).

Audit

lab infocheck   # validates service.toml + --info wiring of every binary

lab infocheck must finish with 0 findings on this repo. See hero_service_check for the audit recipe and hero_service_check_fix for fixes per finding type.

Layout

crates/
  hero_service/             # core types + auto-generated handlers (lib)
  hero_service_server/      # JSON-RPC 2.0 server          (bin, service.toml)
  hero_service_sdk/         # type-safe async Rust SDK      (lib)
  hero_service_admin/       # Axum admin panel              (bin, service.toml)
  hero_service_rhai/        # Rhai scripting bindings       (lib)
  hero_service_examples/    # runnable SDK examples         (bin examples)
schemas/catalog/catalog.oschema     # the meta-domain (single source of truth for types)
docs/schemas/                       # generated docs (after first build)
sdk/                                # generated non-Rust SDKs (after first build)
.forgejo/workflows/build-linux.yaml # release CI (per forge-release-workflow skill)

Adding a domain

1. Drop a new <domain>.oschema under schemas/<domain>/.
2. Re-run the build — crates/hero_service/build.rs picks up the new domain and codegen produces the trait + server module + SDK client.
3. Implement the trait stub in crates/hero_service/src/<domain>/.
4. lab service hero_service --install --start to deploy.

Smoke test

After lab service hero_service --start, validate the server contract:

SOCK="$HERO_SOCKET_DIR/hero_service_server/rpc.sock"

curl -s --unix-socket "$SOCK" http://localhost/health
curl -s --unix-socket "$SOCK" http://localhost/openrpc.json | jq '.methods[].name'
curl -s --unix-socket "$SOCK" http://localhost/.well-known/heroservice.json
curl -s --unix-socket "$SOCK" -X POST http://localhost/rpc \
    -H 'Content-Type: application/json' \
    -d '{"jsonrpc":"2.0","id":1,"method":"system.ping","params":{}}'

lab service hero_service --start runs these checks automatically after startup — manual curl is only for spot-checks.

How this repo was generated

Reproducible from any empty workspace:

mkdir -p hero_service/schemas/services
# (drop your services.oschema into hero_service/schemas/services/)
cd hero_service
hero_rpc_generator --name hero_service --schemas-dir schemas

The scaffolder writes the 6-crate workspace, service.toml files, the §5 main.rs boilerplate, PURPOSE.md, README.md, .gitignore, and .forgejo/workflows/build-linux.yaml. Everything else is hand-tuned in this repo as a reference for what a finished service should look like.

References

• hero_service_scaffold — end-to-end scaffold flow.
• hero_service_check — read-only audit.
• hero_service_check_fix — per-finding fix recipes.
• hero_service_refactor — legacy → canonical migration.
• hero_service_toml_info — service.toml schema.
• herolib_base — the base layer API (service_base!(), validate_service_toml, handle_info_flag, print_startup_banner, prepare_sockets).
• Parent META: hero_skills#262.
• Reference services: hero_proc (wiring) and hero_compute (layout).