feat(services): add service_books.nu #81

Merged

mahmoud merged 1 commit from development_service_books into development

2026-04-19 18:51:04 +00:00

mahmoud commented

2026-04-19 17:38:50 +00:00

Owner

Summary

Adds tools/modules/services/service_books.nu, a lifecycle module for the hero_books service (server + UI) with install | start | stop | status subcommands. Mirrors the two-binary pattern from service_os.nu with three hero_books-specific adaptations.

Closes #80
Part of #75

Changes

tools/modules/services/service_books.nu — new module (~370 lines). Registers hero_books_server and hero_books_ui as hero_proc actions plus the hero_books service. Surfaces both Unix sockets and the http+unix://…/ui.sock/ URL in the start summary.
tools/modules/services/mod.nu — add export use service_books.nu.

--root is optional on every command; user-level is the default.

Hero_books-specific adaptations vs. service_os

Explicit --workspace cargo pass. hero_books is a hybrid workspace + root [package] layout, so plain cargo build --release --manifest-path Cargo.toml only builds the root hero_books crate + its direct deps (hero_books_lib, hero_books_docusaurus), missing hero_books_server, hero_books_ui, hero_books_admin. install runs cargo build --release --workspace first; svc_cargo_install then runs as an incremental no-op and copies all 5 binaries. hero_proc and hero_os are pure virtual workspaces (no root package) so their modules don't need this.
Env vars resolved at action-build time. HERO_BOOKS_DATA = <hero_home>/var/books, HERO_EMBEDDER_URL = unix://<sock_base>/hero_embedder/rpc.sock, both computed from svc_home $root / svc_sock_base $root. Matches the binary's compiled-in defaults; the TOML's __HERO_VAR__ / hardcoded /root/... placeholders are for a different templating path. Documented inline as a reusable convention for future services.
Both binaries invoked with serve subcommand. hero_books_server / hero_books_ui have a serve subcommand they must be invoked with, otherwise they print help and exit, which hero_proc interprets as a crash. script: $"($bin) serve" in both action specs.
svx_check_embedder preflight. Replaces service_os's WASM-assets preflight. Warns (does NOT fail) when the hero_embedder socket is absent — the server runs in degraded mode without it (no vector search / semantic Q&A) and retries on next RPC once embedder comes up, so no hero_books restart is needed after the fact.

Test Results

End-to-end smoke test on the Hetzner box from a clean state. Every assertion passed.

#	Assertion	Result
1a–1c	hero_proc-down error paths for status / stop / start	PASS
2a	`service_proc start --root` healthy	PASS
2b	`service_books install --root` produced all 5 binaries	PASS
2c	`service_books start --reset --root` with embedder preflight warning	PASS
2d–2e	Both `rpc.sock` and `ui.sock` live unix sockets	PASS
2f–2g	Both sockets accept HTTP (curl `--unix-socket`)	PASS
2h	`service_books status --root` returns `state: running, restarts: 0`	PASS
2i	Idempotent start (no `--reset`) prints "already running"	PASS
2j	`HERO_BOOKS_DATA` and `HERO_EMBEDDER_URL` correctly set on registered server action	PASS
2k	15 s observation — no new restarts, `state: running` held	PASS
2l	`service_books stop --root` stops and unregisters	PASS
2m	Both sockets removed after stop	PASS
2n	Post-stop status returns expected `service 'hero_books' not found`	PASS

Full per-step output is on issue #80.

Issues caught during testing (all fixed)

Binaries needed serve subcommand — initial run triggered 6 failed restarts + state: failed. Fix: script: $"($bin) serve" in both action specs.
Missing _server / _ui / _admin after plain cargo build — hybrid workspace layout. Fix: explicit --workspace pass.

Follow-up (not part of this PR)

sccache stall observed during cargo build (defunct child, 0.5% CPU, 0 rustc children). Worked around by unsetting RUSTC_WRAPPER / SCCACHE_* env in the test wrapper. Belongs in its own issue alongside the service_proc.nu:270 bug already tracked at #79.

## Summary Adds `tools/modules/services/service_books.nu`, a lifecycle module for the `hero_books` service (server + UI) with `install | start | stop | status` subcommands. Mirrors the two-binary pattern from `service_os.nu` with three hero_books-specific adaptations. ## Related - Closes #80 - Part of #75 ## Changes - `tools/modules/services/service_books.nu` — new module (~370 lines). Registers `hero_books_server` and `hero_books_ui` as hero_proc actions plus the `hero_books` service. Surfaces both Unix sockets and the `http+unix://…/ui.sock/` URL in the start summary. - `tools/modules/services/mod.nu` — add `export use service_books.nu`. `--root` is optional on every command; user-level is the default. ### Hero_books-specific adaptations vs. service_os 1. **Explicit `--workspace` cargo pass.** hero_books is a hybrid `workspace + root [package]` layout, so plain `cargo build --release --manifest-path Cargo.toml` only builds the root `hero_books` crate + its direct deps (`hero_books_lib`, `hero_books_docusaurus`), missing `hero_books_server`, `hero_books_ui`, `hero_books_admin`. `install` runs `cargo build --release --workspace` first; `svc_cargo_install` then runs as an incremental no-op and copies all 5 binaries. hero_proc and hero_os are pure virtual workspaces (no root package) so their modules don't need this. 2. **Env vars resolved at action-build time.** `HERO_BOOKS_DATA` = `<hero_home>/var/books`, `HERO_EMBEDDER_URL` = `unix://<sock_base>/hero_embedder/rpc.sock`, both computed from `svc_home $root` / `svc_sock_base $root`. Matches the binary's compiled-in defaults; the TOML's `__HERO_VAR__` / hardcoded `/root/...` placeholders are for a different templating path. Documented inline as a reusable convention for future services. 3. **Both binaries invoked with `serve` subcommand.** `hero_books_server` / `hero_books_ui` have a `serve` subcommand they must be invoked with, otherwise they print help and exit, which hero_proc interprets as a crash. `script: $"($bin) serve"` in both action specs. 4. **`svx_check_embedder` preflight.** Replaces `service_os`'s WASM-assets preflight. Warns (does NOT fail) when the hero_embedder socket is absent — the server runs in degraded mode without it (no vector search / semantic Q&A) and retries on next RPC once embedder comes up, so no hero_books restart is needed after the fact. ## Test Results End-to-end smoke test on the Hetzner box from a clean state. Every assertion passed. | # | Assertion | Result | |---|---|---| | 1a–1c | hero_proc-down error paths for status / stop / start | PASS | | 2a | `service_proc start --root` healthy | PASS | | 2b | `service_books install --root` produced all 5 binaries | PASS | | 2c | `service_books start --reset --root` with embedder preflight warning | PASS | | 2d–2e | Both `rpc.sock` and `ui.sock` live unix sockets | PASS | | 2f–2g | Both sockets accept HTTP (curl `--unix-socket`) | PASS | | 2h | `service_books status --root` returns `state: running, restarts: 0` | PASS | | 2i | Idempotent start (no `--reset`) prints "already running" | PASS | | 2j | `HERO_BOOKS_DATA` and `HERO_EMBEDDER_URL` correctly set on registered server action | PASS | | 2k | 15 s observation — no new restarts, `state: running` held | PASS | | 2l | `service_books stop --root` stops and unregisters | PASS | | 2m | Both sockets removed after stop | PASS | | 2n | Post-stop status returns expected `service 'hero_books' not found` | PASS | Full per-step output is on issue #80. ### Issues caught during testing (all fixed) 1. Binaries needed `serve` subcommand — initial run triggered 6 failed restarts + `state: failed`. Fix: `script: $"($bin) serve"` in both action specs. 2. Missing `_server` / `_ui` / `_admin` after plain cargo build — hybrid workspace layout. Fix: explicit `--workspace` pass. ### Follow-up (not part of this PR) - sccache stall observed during cargo build (defunct child, 0.5% CPU, 0 rustc children). Worked around by unsetting `RUSTC_WRAPPER` / `SCCACHE_*` env in the test wrapper. Belongs in its own issue alongside the `service_proc.nu:270` bug already tracked at #79.

mahmoud added 1 commit

2026-04-19 17:38:50 +00:00

feat(services): add service_books.nu 2566523853

Add a service_books module that provides install | start | stop | status
lifecycle commands for hero_books (hero_books_server + hero_books_ui)
through hero_proc, following the two-action pattern from service_os.

Three hero_books-specific pieces:
- Install runs an explicit cargo build --release --workspace pass because
  hero_books is a hybrid workspace+root-package layout: plain cargo build
  only produces the root hero_books + direct deps, missing _server, _ui,
  _admin. The --workspace pass builds every member; the subsequent
  svc_cargo_install is incremental and copies all five binaries.
- Server action registers with HERO_BOOKS_DATA and HERO_EMBEDDER_URL
  resolved at action-build time via svc_home / svc_sock_base so --root
  flips paths correctly. Both binaries are invoked with their `serve`
  subcommand.
- svx_check_embedder preflight warns (does not fail) when the hero_embedder
  socket is absent; the server runs in degraded mode without it and
  retries on next RPC once embedder comes up.

#80
#75