Document `lab user init` prerequisite in service skills (PATH_ROOT requirement) #272

New issue

Open

opened 2026-05-20 05:56:42 +00:00 by timur · 1 comment

timur commented

2026-05-20 05:56:42 +00:00

Owner

Context

From the hero_logic#41 §1 audit.

Services that use herolib_core::base::paths::path_root() (transitively via resolve_socket_dir → path_var → path_root) panic at startup if PATH_ROOT isn't set:

PATH_ROOT is not set — run lab user init first

Nothing in hero_service.md, hero_service_toml_info.md, or hero_service_check_fix.md mentions this. A friend setting up a fresh dev environment hits the panic without warning.

Note: hero_proc#109 (now merged) helps for hero_proc-managed daemons — they pick up ~/hero/cfg/env/*.env on supervisor startup. But direct cargo run invocations still need PATH_ROOT in shell env, and lab user init is the canonical way to populate ~/hero/cfg/.

Tasks

Option A — Document the prerequisite

Add a one-liner near the top of hero_service_check_fix.md §7 (smoke test):

> Prerequisite: `lab user init` must have been run on this machine so `PATH_ROOT` and friends are set. Otherwise services that call `herolib_core::base::paths::path_root()` panic at startup.

Option B — Fallback in `path_root()`

Make path_root() fall back to $HOME/hero when PATH_ROOT unset, with a tracing::warn! rather than a panic. Lives in herolib_core::base::paths::path_root (hero_lib repo).

My lean: both. Option B handles the friendly-default case; Option A keeps the explicit setup story documented.

Acceptance

Skill §7 mentions the lab user init prerequisite.
(Optional) path_root() has a safe fallback.
A new dev can clone hero_service / hero_logic / hero_proc and follow the skills to a working lab service … --start without hitting the unexplained panic.

## Context From the [hero_logic#41 §1 audit](https://forge.ourworld.tf/lhumina_code/hero_logic/issues/41#issuecomment-34455). Services that use `herolib_core::base::paths::path_root()` (transitively via `resolve_socket_dir → path_var → path_root`) panic at startup if `PATH_ROOT` isn't set: ``` PATH_ROOT is not set — run lab user init first ``` Nothing in `hero_service.md`, `hero_service_toml_info.md`, or `hero_service_check_fix.md` mentions this. A friend setting up a fresh dev environment hits the panic without warning. Note: `hero_proc#109` (now merged) helps for hero_proc-managed daemons — they pick up `~/hero/cfg/env/*.env` on supervisor startup. But direct `cargo run` invocations still need `PATH_ROOT` in shell env, and `lab user init` is the canonical way to populate `~/hero/cfg/`. ## Tasks ### Option A — Document the prerequisite Add a one-liner near the top of `hero_service_check_fix.md` §7 (smoke test): ``` > Prerequisite: `lab user init` must have been run on this machine so `PATH_ROOT` and friends are set. Otherwise services that call `herolib_core::base::paths::path_root()` panic at startup. ``` ### Option B — Fallback in `path_root()` Make `path_root()` fall back to `$HOME/hero` when `PATH_ROOT` unset, with a `tracing::warn!` rather than a panic. Lives in `herolib_core::base::paths::path_root` (hero_lib repo). My lean: **both**. Option B handles the friendly-default case; Option A keeps the explicit setup story documented. ## Acceptance - Skill §7 mentions the `lab user init` prerequisite. - (Optional) `path_root()` has a safe fallback. - A new dev can clone hero_service / hero_logic / hero_proc and follow the skills to a working `lab service … --start` without hitting the unexplained panic.

timur referenced this issue from lhumina_code/hero_logic

2026-05-20 05:57:01 +00:00

Audit alignment with hero_skills + assess migration to upgraded hero_rpc #41

timur referenced this issue

2026-05-20 05:57:18 +00:00

[META] Standardize Hero service architecture — template, hero_rpc alignment, framework hoist, skills #262

timur referenced this issue

2026-05-20 06:53:09 +00:00

[META] Standardize Hero service architecture — template, hero_rpc alignment, framework hoist, skills #262

timur referenced this issue

2026-05-20 06:59:12 +00:00

[META] Standardize Hero service architecture — template, hero_rpc alignment, framework hoist, skills #262

timur commented

2026-05-20 07:10:27 +00:00

Author

Owner

Direction locked: improve panic message — no fallback, no skill update

@timur's call (2026-05-20): "always die principle. no fallback." Users should follow standards; we shouldn't paper over missing setup with implicit defaults.

Action: a single change to the herolib_core::base::paths::path_root() panic message. Make it actionable:

PATH_ROOT is not set.
Recommended: run services via `lab` (e.g. `lab service <name> --start`) — lab handles env setup.
If running directly: `lab user init` will set PATH_ROOT and other Hero env vars.

(Wording can vary — the key bits are: mention lab first as the preferred path, then lab user init as the manual fallback. No code-level fallback to $HOME/hero.)

Skill update is NOT in scope. The improved panic message itself is the discoverability fix; the skill text doesn't need to call this out separately.

Option A (document) and Option B (path_root() fallback) from the issue body are both superseded by this.

## Direction locked: improve panic message — no fallback, no skill update @timur's call (2026-05-20): "always die principle. no fallback." Users should follow standards; we shouldn't paper over missing setup with implicit defaults. **Action: a single change to the `herolib_core::base::paths::path_root()` panic message.** Make it actionable: ``` PATH_ROOT is not set. Recommended: run services via `lab` (e.g. `lab service <name> --start`) — lab handles env setup. If running directly: `lab user init` will set PATH_ROOT and other Hero env vars. ``` (Wording can vary — the key bits are: mention `lab` first as the preferred path, then `lab user init` as the manual fallback. No code-level fallback to $HOME/hero.) **Skill update is NOT in scope.** The improved panic message itself is the discoverability fix; the skill text doesn't need to call this out separately. **Option A** (document) and **Option B** (path_root() fallback) from the issue body are both superseded by this.

timur referenced this issue

2026-05-20 09:41:12 +00:00

[META] Standardize Hero service architecture — template, hero_rpc alignment, framework hoist, skills #262

timur referenced this issue

2026-05-20 23:01:33 +00:00

[META] Standardize Hero service architecture — template, hero_rpc alignment, framework hoist, skills #262