chore: align hero_books with hero_sockets and simplify the README #97

Merged

mahmoud merged 2 commits from development_align_hero_sockets_and_readme into development

2026-04-21 07:34:58 +00:00

mahmoud commented

2026-04-21 06:35:18 +00:00

Owner

Summary

Broader cleanup pass after auditing hero_books against twelve Hero skills (hero_sockets, naming_convention, hero_crates_best_practices_check, hero_proc_service_selfstart, makefile_helper, makefile_helper_ci, testing_suite, hero_ui_whitelists, hero_ui_openrpc_proxy, hero_web_prefix, cargo_deps, rust_toolchain). Code is already largely compliant — most drift was in docs and a handful of typos.

This PR supersedes #96 (docs: call out hero_embedder as a prerequisite). The rewritten README.md here incorporates the Prerequisites / Troubleshooting content from #96 in a more compact form. #96 can be closed once this lands.

Changes

Documentation

README.md — rewritten in the hero_compute / hero_whiteboard style: short landing page, explicit Sockets table pointing at the real per-service layout under $HERO_SOCKET_DIR/hero_books/, and a Documentation section linking to docs/manual/. Prerequisites + Troubleshooting kept (condensed).
docs/manual/README.md — replaced obsolete hero_books --port 8883 / hero_books_client quick-start with the current hero_books --start + hero_router URL layout.
deploy/single-vm/README.md — refreshed topology diagram: hero_router fronting UDS-based services instead of per-service TCP ports.
.env.example — dropped stale HERO_BOOKS_PORT / HERO_REDIS_PORT / HERO_EMBEDDER_PORT; pointed at HERO_SOCKET_DIR instead.

New per-crate READMEs (previously missing — flagged by `hero_crates_best_practices_check`)

crates/hero_books_lib/README.md
crates/hero_books_ui/README.md
crates/hero_books_admin/README.md
crates/hero_books_app/README.md
crates/hero_books_lib_rhai/README.md
crates/hero_books_examples/README.md

Fixes

crates/hero_books_admin/Makefile — copy-paste bug fixed. Every target used -p hero_books_ui instead of -p hero_books_admin; make test from inside the admin crate was silently testing the UI.
cargo_deps alignment — hero_embedder_sdk switched from a pinned rev to branch = "development" in both hero_books_server/Cargo.toml and hero_books_lib/Cargo.toml, matching the rest of the Hero deps.
Makefile test-smoke — no longer swallows cargo failures behind || echo. Detects whether smoke.rs exists and runs cargo only when it does.

Cleanup

Removed unused crates/hero_books_lib_rhai/buildenv.sh — the root buildenv.sh is the single source of truth.

Test Results

cargo build --workspace — ok.
cargo test -p hero_books_server --lib — 16/16 passed.
cargo fmt --check — clean.

Follow-up issues to open

Out of scope for this PR; each is a distinct concern worth its own ticket:

hero_books_admin has no /rpc proxy route, but its templates call BASE_PATH + "/rpc" — 404 today (hero_ui_openrpc_proxy violation).
Admin whitelist module not present (hero_ui_whitelists).
Playwright e2e baseURL: http://localhost:8883 broken against the UDS-only server — needs a UDS bridge or rewrite.
specs/startup_flow.md and specs/schemas/openrpc_spec.md still carry TCP-era examples.
Workspace has no unit tests in most crates (testing_suite non-compliance). Smoke tests exist; per-crate unit tests need to be added.

Partly closes the documentation gap reported in #87 (the parts that were in-scope for #96).

## Summary Broader cleanup pass after auditing `hero_books` against twelve Hero skills (`hero_sockets`, `naming_convention`, `hero_crates_best_practices_check`, `hero_proc_service_selfstart`, `makefile_helper`, `makefile_helper_ci`, `testing_suite`, `hero_ui_whitelists`, `hero_ui_openrpc_proxy`, `hero_web_prefix`, `cargo_deps`, `rust_toolchain`). Code is already largely compliant — most drift was in docs and a handful of typos. This PR **supersedes #96** (`docs: call out hero_embedder as a prerequisite`). The rewritten `README.md` here incorporates the Prerequisites / Troubleshooting content from #96 in a more compact form. #96 can be closed once this lands. ## Changes ### Documentation - **`README.md`** — rewritten in the hero_compute / hero_whiteboard style: short landing page, explicit Sockets table pointing at the real per-service layout under `$HERO_SOCKET_DIR/hero_books/`, and a Documentation section linking to `docs/manual/`. Prerequisites + Troubleshooting kept (condensed). - **`docs/manual/README.md`** — replaced obsolete `hero_books --port 8883` / `hero_books_client` quick-start with the current `hero_books --start` + hero_router URL layout. - **`deploy/single-vm/README.md`** — refreshed topology diagram: hero_router fronting UDS-based services instead of per-service TCP ports. - **`.env.example`** — dropped stale `HERO_BOOKS_PORT` / `HERO_REDIS_PORT` / `HERO_EMBEDDER_PORT`; pointed at `HERO_SOCKET_DIR` instead. ### New per-crate READMEs (previously missing — flagged by `hero_crates_best_practices_check`) - `crates/hero_books_lib/README.md` - `crates/hero_books_ui/README.md` - `crates/hero_books_admin/README.md` - `crates/hero_books_app/README.md` - `crates/hero_books_lib_rhai/README.md` - `crates/hero_books_examples/README.md` ### Fixes - **`crates/hero_books_admin/Makefile`** — copy-paste bug fixed. Every target used `-p hero_books_ui` instead of `-p hero_books_admin`; `make test` from inside the admin crate was silently testing the UI. - **`cargo_deps` alignment** — `hero_embedder_sdk` switched from a pinned `rev` to `branch = "development"` in both `hero_books_server/Cargo.toml` and `hero_books_lib/Cargo.toml`, matching the rest of the Hero deps. - **`Makefile` `test-smoke`** — no longer swallows cargo failures behind `|| echo`. Detects whether `smoke.rs` exists and runs cargo only when it does. ### Cleanup - Removed unused `crates/hero_books_lib_rhai/buildenv.sh` — the root `buildenv.sh` is the single source of truth. ## Test Results - `cargo build --workspace` — ok. - `cargo test -p hero_books_server --lib` — 16/16 passed. - `cargo fmt --check` — clean. ## Follow-up issues to open Out of scope for this PR; each is a distinct concern worth its own ticket: 1. `hero_books_admin` has no `/rpc` proxy route, but its templates call `BASE_PATH + "/rpc"` — 404 today (`hero_ui_openrpc_proxy` violation). 2. Admin whitelist module not present (`hero_ui_whitelists`). 3. Playwright e2e `baseURL: http://localhost:8883` broken against the UDS-only server — needs a UDS bridge or rewrite. 4. `specs/startup_flow.md` and `specs/schemas/openrpc_spec.md` still carry TCP-era examples. 5. Workspace has no unit tests in most crates (`testing_suite` non-compliance). Smoke tests exist; per-crate unit tests need to be added. ## Related - Partly closes the documentation gap reported in https://forge.ourworld.tf/lhumina_code/hero_books/issues/87 (the parts that were in-scope for #96).

mahmoud added 1 commit

2026-04-21 06:35:18 +00:00

chore: align hero_books with hero_sockets and simplify the README

Test / test (pull_request) Successful in 6m48s

Details

Test / integration (pull_request) Successful in 4m11s

Details

951b1287f4

Broader cleanup pass after auditing hero_books against hero_sockets,
naming_convention, hero_crates_best_practices_check, cargo_deps, and
several other Hero skills. Code is already largely compliant — most
drift was in docs and a handful of obvious typos.

README.md:
- Rewrite the landing page in the hero_compute / hero_whiteboard style.
- Correct the Sockets table to show the real per-service layout under
  $HERO_SOCKET_DIR/hero_books/ (previous table showed flat
  hero_books_server.sock / hero_books_ui.sock / hero_embedder.sock
  paths that haven't been right for a while).
- Add a Documentation section linking to docs/manual/ so the main
  README stays short and the deep content is one click away.
- Keep Prerequisites + Troubleshooting from the earlier embedder docs
  pass (issue #87) in a condensed form.

crates/hero_books_admin/Makefile:
- Fix copy-paste bug: every target used -p hero_books_ui instead of
  -p hero_books_admin. Running `make test` from inside the admin
  crate was silently testing the UI.

Cargo deps (cargo_deps skill):
- Switch hero_embedder_sdk from a pinned rev to branch = "development"
  so it tracks the same branch every other hero_* dep uses.

crates/hero_books_lib_rhai/buildenv.sh:
- Removed. Root buildenv.sh is the single source of truth; the nested
  copy was unused.

Makefile test-smoke target:
- Stop swallowing cargo failures behind "|| echo No smoke tests found".
  Detect whether smoke.rs exists; run cargo test if it does, skip
  cleanly if it doesn't. Real failures now surface.

.env.example:
- Drop stale HERO_BOOKS_PORT / HERO_REDIS_PORT / HERO_EMBEDDER_PORT
  references; hero_books binds Unix sockets only. Point at
  HERO_SOCKET_DIR instead.

deploy/single-vm/README.md:
- Refresh the ASCII topology to show hero_router fronting the
  UDS-based services instead of per-service TCP ports.

docs/manual/README.md:
- Replace the obsolete `hero_books --port 8883` / hero_books_client
  quick-start with the current `hero_books --start` + hero_router
  URL layout.

New per-crate READMEs (previously missing — flagged by
hero_crates_best_practices_check):
- crates/hero_books_lib/README.md
- crates/hero_books_ui/README.md
- crates/hero_books_admin/README.md
- crates/hero_books_app/README.md
- crates/hero_books_lib_rhai/README.md
- crates/hero_books_examples/README.md

No behavioural code changes. Build is green. 16/16 server tests pass.
Fmt clean.

Out of scope for this PR and tracked separately as follow-ups:
- hero_books_admin missing /rpc proxy route (hero_ui_openrpc_proxy).
- Admin whitelist module (hero_ui_whitelists).
- Playwright e2e baseURL still TCP-only; needs UDS bridge.
- Specs under specs/ still contain TCP-era examples.