fix(cli): align socket dir docs with code and warn on stale env override #21

Merged

mahmoud merged 1 commit from development_fix_codescalers_service_name into development

2026-04-29 10:32:58 +00:00

mahmoud commented

2026-04-29 10:25:59 +00:00

Owner

Closes #17.

Summary

The Rust source already binds to the canonical hero_codescalers/ socket directory (commit 7edb4e3 / PR #16). The "stuck in starting" symptom on issue #17 was caused by:

Stale README documentation still describing the legacy hero_codescalers_server/ layout, which led operators to export HERO_CODESCALERS_SOCK_NAME=hero_codescalers_server from previous setups.
No defensive warning when that exported value silently disagreed with the CLI's instance-derived directory.

Changes

README.md — replaced legacy socket-directory references with the canonical names:
- "Unix socket directories" table (hero_codescalers_server*/ -> hero_codescalers*/).
- Example command path on line 243.
- HERO_CODESCALERS_SOCK_NAME default in the env-var table (hero_codescalers_server -> hero_codescalers).
- Remaining hero_codescalers_server matches are deliberately kept (binary name + hero_proc action names — distinct concepts from the socket dir).
crates/hero_codescalers/src/main.rs — added a non-fatal eprintln! guard inside build_service_definition that warns when a stale HERO_CODESCALERS_SOCK_NAME exported in the caller's environment differs from the instance-derived directory. The CLI was already passing the correct value via ActionBuilder::env(...), so this is purely informational and removes the silent foot-gun.

Test plan

cargo check -p hero_codescalers clean.
cargo test --workspace — 10/10 pass (no regressions).
cargo fmt --all -- --check — fails on development baseline (122 diffs across 18 files unrelated to this patch); should be tracked separately.
cargo clippy --workspace --all-targets -- -D warnings — fails on development baseline (32 errors unrelated to this patch); should be tracked separately.
Manual verification (Step 3 of spec — requires running stack): hero_codescalers --start, confirm ~/hero/var/sockets/hero_codescalers/{rpc,ui}.sock exist, hero_router dashboard shows hero_codescalers Healthy with a working UI link.

If a prior run left a stale ~/hero/var/sockets/hero_codescalers_server*/ directory on disk, operators should rm -rf ~/hero/var/sockets/hero_codescalers_server* once after merging.

Closes #17. ## Summary The Rust source already binds to the canonical `hero_codescalers/` socket directory (commit `7edb4e3` / PR #16). The "stuck in starting" symptom on issue #17 was caused by: 1. Stale README documentation still describing the legacy `hero_codescalers_server/` layout, which led operators to export `HERO_CODESCALERS_SOCK_NAME=hero_codescalers_server` from previous setups. 2. No defensive warning when that exported value silently disagreed with the CLI's instance-derived directory. ## Changes - `README.md` — replaced legacy socket-directory references with the canonical names: - "Unix socket directories" table (`hero_codescalers_server*/` -> `hero_codescalers*/`). - Example command path on line 243. - `HERO_CODESCALERS_SOCK_NAME` default in the env-var table (`hero_codescalers_server` -> `hero_codescalers`). - Remaining `hero_codescalers_server` matches are deliberately kept (binary name + hero_proc action names — distinct concepts from the socket dir). - `crates/hero_codescalers/src/main.rs` — added a non-fatal `eprintln!` guard inside `build_service_definition` that warns when a stale `HERO_CODESCALERS_SOCK_NAME` exported in the caller's environment differs from the instance-derived directory. The CLI was already passing the correct value via `ActionBuilder::env(...)`, so this is purely informational and removes the silent foot-gun. ## Test plan - [x] `cargo check -p hero_codescalers` clean. - [x] `cargo test --workspace` — 10/10 pass (no regressions). - [ ] `cargo fmt --all -- --check` — fails on `development` baseline (122 diffs across 18 files unrelated to this patch); should be tracked separately. - [ ] `cargo clippy --workspace --all-targets -- -D warnings` — fails on `development` baseline (32 errors unrelated to this patch); should be tracked separately. - [ ] Manual verification (Step 3 of spec — requires running stack): `hero_codescalers --start`, confirm `~/hero/var/sockets/hero_codescalers/{rpc,ui}.sock` exist, hero_router dashboard shows `hero_codescalers` Healthy with a working UI link. If a prior run left a stale `~/hero/var/sockets/hero_codescalers_server*/` directory on disk, operators should `rm -rf ~/hero/var/sockets/hero_codescalers_server*` once after merging.

mahmoud added 1 commit

2026-04-29 10:25:59 +00:00