lhumina_code/hero_codescalers

Fork 0

[hero_codescalers] Fix service registration name — UI stuck in starting #17

New issue

Closed

opened 2026-04-29 07:10:12 +00:00 by mahmoud · 3 comments

mahmoud commented

2026-04-29 07:10:12 +00:00

Owner

Problem

The hero_codescalers UI is stuck in "starting" state. Root cause identified:
the service is registered under the wrong name (hero_codescalers_server_ui
instead of the correct naming convention used by hero_router).

Steps to fix

Audit the service registration name in crates/hero_codescalers_server/
and crates/hero_codescalers_ui/
Align with the standard socket naming convention:
$HERO_SOCKET_DIR/hero_codescalers_server<N>/rpc.sock
Restart and verify hero_router picks it up and shows it as connected
Confirm UI is reachable via hero_router (not stuck in starting)

Acceptance Criteria

Service registration name matches hero_router expectations
UI no longer stuck in starting state
hero_router dashboard shows hero_codescalers as connected and clickable

## Problem The hero_codescalers UI is stuck in "starting" state. Root cause identified: the service is registered under the wrong name (`hero_codescalers_server_ui` instead of the correct naming convention used by hero_router). ## Steps to fix - Audit the service registration name in `crates/hero_codescalers_server/` and `crates/hero_codescalers_ui/` - Align with the standard socket naming convention: `$HERO_SOCKET_DIR/hero_codescalers_server<N>/rpc.sock` - Restart and verify hero_router picks it up and shows it as connected - Confirm UI is reachable via hero_router (not stuck in starting) ## Acceptance Criteria - [ ] Service registration name matches hero_router expectations - [ ] UI no longer stuck in starting state - [ ] hero_router dashboard shows hero_codescalers as connected and clickable

mahmoud self-assigned this

2026-04-29 07:12:32 +00:00

mahmoud added this to the ACTIVE project

2026-04-29 07:12:35 +00:00

mahmoud commented

2026-04-29 07:41:42 +00:00

Author

Owner

Implementation Spec for Issue #17

Objective

Eliminate every remaining reference to the legacy hero_codescalers_server-prefixed socket directory naming so that hero_router reliably discovers hero_codescalers under the canonical Hero socket convention ($HERO_SOCKET_DIR/hero_codescalers/{rpc,ui}.sock) and the UI stops being stuck in "starting".

Root Cause

The Rust source has already been migrated to the canonical convention (SERVICE_NAME = "hero_codescalers" is used as the default --sockname in both binaries and as the sock_dir_name(0) value in the CLI), per the previous fix in commit 7edb4e3 ("fix(cli): align CLI socket dir default with the server's", PR #16). However, stale documentation and a wrong env-var default in README.md still describe the OLD layout, which is what is making operators (and freshly-built environments where HERO_CODESCALERS_SOCK_NAME=hero_codescalers_server was exported from a previous setup) bind to a directory that hero_router does not look in. Specifically:

README.md:61-63 — the "Unix socket directories" table still says instance 0 lives in hero_codescalers_server/ (and instances N in hero_codescalers_serverN/), which contradicts the code (crates/hero_codescalers/src/main.rs:42-51, which produces hero_codescalers/ and hero_codescalers_{N}/).
README.md:243 — example command points at ~/hero/var/sockets/hero_codescalers_server1/rpc.sock, a path that nothing in the code now produces.
README.md:265 — env var table claims HERO_CODESCALERS_SOCK_NAME defaults to hero_codescalers_server. The actual default, set via clap's default_value = SERVICE_NAME in crates/hero_codescalers_server/src/main.rs:43 and crates/hero_codescalers_ui/src/main.rs:59, is hero_codescalers.
The literal string hero_codescalers_server_ui from the issue title does not appear in source — it is a description of the symptom: when the UI binary inherited a stale HERO_CODESCALERS_SOCK_NAME=hero_codescalers_server from the environment, both binaries wrote into hero_codescalers_server/, and hero_router (which scans for <service>/{rpc,ui}.sock and reads the name field from .well-known/heroservice.json) saw a directory whose name did not match the manifest's name: "hero_codescalers" and could not stitch the UI behind the RPC service — leaving the UI listed but stuck in "starting".

The code itself is consistent: heroservice.json for both crates declares "name": "hero_codescalers"; both binaries default --sockname to SERVICE_NAME = "hero_codescalers"; the CLI's sock_dir_name(instance) returns hero_codescalers for instance 0; both server and UI are launched with HERO_CODESCALERS_SOCK_NAME = sock_dir_name(instance) from the CLI (crates/hero_codescalers/src/main.rs:458,500). The bug is purely that the README still documents the legacy default and that there is no defensive guard against a stale exported env var overriding the CLI-supplied value.

The issue body's "expected naming" — $HERO_SOCKET_DIR/hero_codescalers_server<N>/rpc.sock — itself uses the legacy form. The canonical Hero socket convention (per the hero_sockets skill, sections 2 and 12) is unambiguous: the directory name MUST equal the service name, MUST NOT carry _server/_ui/_sdk suffixes, and <service>/rpc.sock is the canonical layout. The author of the issue likely typed the legacy name from memory; we should align the fix on the canonical hero_codescalers/ convention that the manifests and the actual Rust code already use.

Requirements

The README's documented socket directories, env-var defaults, and example commands MUST match the code's behaviour (hero_codescalers/, hero_codescalers_{N}/).
A stale HERO_CODESCALERS_SOCK_NAME exported in the operator's environment MUST NOT silently override the CLI's instance-derived directory name and MUST NOT cause the UI's socket to land in a different directory from the server's.
heroservice.json for both crates MUST keep declaring "name": "hero_codescalers".
After the fix, hero_router scanning $HERO_SOCKET_DIR MUST find hero_codescalers/rpc.sock AND hero_codescalers/ui.sock in the same directory, both manifest-named hero_codescalers, and present hero_codescalers as Healthy with a clickable UI link.
All tests, smoke scripts, and Makefile targets that reference socket paths MUST already use hero_codescalers/ (verified: Makefile:13-14, crates/hero_codescalers_ui/scripts/test-users-ui.sh:74).

Files to Modify/Create

README.md — fix the "Unix socket directories" table (lines 61-63), the CLI example path (line 243), and the env-var defaults table (line 265) to match the code's actual behaviour.
crates/hero_codescalers/src/main.rs — make self_start immune to a stale exported HERO_CODESCALERS_SOCK_NAME by adding a startup guard that warns if the external HERO_CODESCALERS_SOCK_NAME differs from the instance-derived value.

Implementation Plan

Step 1: Fix the README documentation drift

Files: README.md
Changes:

Replace the "Unix socket directories" table (currently lines 59-63) so the directory column reads hero_codescalers/, hero_codescalers_1/, hero_codescalers_N/ (matching sock_dir_name() in crates/hero_codescalers/src/main.rs:42-51).
Update the example command on line 243 from ~/hero/var/sockets/hero_codescalers_server1/rpc.sock to ~/hero/var/sockets/hero_codescalers_1/rpc.sock.
Update the env-var defaults table on line 265 so the default for HERO_CODESCALERS_SOCK_NAME reads hero_codescalers (matching SERVICE_NAME in both _server and _ui main.rs).
Dependencies: none

Step 2: Add a defensive startup guard in the CLI against a stale exported `HERO_CODESCALERS_SOCK_NAME`

Files: crates/hero_codescalers/src/main.rs
Changes:

In build_service_definition (lines 419-539), after computing let dir = sock_dir_name(instance); (line 433), check if the current process already has HERO_CODESCALERS_SOCK_NAME exported and it differs from dir. If so, emit a single eprintln! warning telling the operator that the exported value is being overridden by the instance-derived value for the spawned action's environment.
Concretely, add right before line 444 (// ── Server action ──):

if let Ok(stale) = std::env::var("HERO_CODESCALERS_SOCK_NAME") {
    if stale != dir {
        eprintln!(
            "warning: HERO_CODESCALERS_SOCK_NAME='{stale}' in caller env differs \
             from instance-derived '{dir}'; the spawned actions will use '{dir}'."
        );
    }
}

Dependencies: none (independent of Step 1)

Step 3: Verify hero_router picks up the service end-to-end

Files: none (verification only)
Changes:

make install && hero_codescalers --start.
Confirm ~/hero/var/sockets/hero_codescalers/rpc.sock and ~/hero/var/sockets/hero_codescalers/ui.sock both exist.
curl --unix-socket ~/hero/var/sockets/hero_codescalers/rpc.sock http://localhost/.well-known/heroservice.json returns "name":"hero_codescalers","socket":"rpc".
curl --unix-socket ~/hero/var/sockets/hero_codescalers/ui.sock http://localhost/.well-known/heroservice.json returns "name":"hero_codescalers","socket":"ui".
Open hero_router dashboard (default http://127.0.0.1:9988/) — hero_codescalers MUST appear as Healthy and clickable; clicking the UI link MUST land on the dashboard via http://127.0.0.1:9988/hero_codescalers/ui/, no longer "starting".
Dependencies: Step 1 and Step 2 merged.

Acceptance Criteria

README.md no longer contains the strings hero_codescalers_server/, hero_codescalers_server1/, hero_codescalers_serverN/, or the env-var default hero_codescalers_server.
crates/hero_codescalers/src/main.rs warns (non-fatally) when a stale exported HERO_CODESCALERS_SOCK_NAME would have differed from the instance-derived directory.
After hero_codescalers --start, ~/hero/var/sockets/hero_codescalers/rpc.sock AND ~/hero/var/sockets/hero_codescalers/ui.sock both exist (single shared directory, no _server or _ui directory siblings created).
hero_router dashboard lists hero_codescalers as Healthy / connected / clickable and the UI link no longer reports "starting".
cargo build --workspace --release, cargo fmt --all -- --check, and cargo clippy --workspace --all-targets -- -D warnings all pass.
No regression in make test-server or make test-ui (both already point at ~/hero/var/sockets/hero_codescalers/{rpc,ui}.sock).

Notes

Service name convention: the issue body's $HERO_SOCKET_DIR/hero_codescalers_server<N>/rpc.sock form is the legacy layout. The canonical Hero convention (hero_sockets skill section 2 and 12) is $HERO_SOCKET_DIR/<service>/<type>.sock with NO _server/_ui suffix on the directory. The Rust code already follows the canonical form; this fix only catches up the README and adds a defence against a stale env var. We are aligning with the canonical convention, not the issue body's example.
No hero_router restart required: hero_router scans $HERO_SOCKET_DIR periodically (default HERO_ROUTER_REFRESH=30 seconds); after the next stop/start of hero_codescalers, hero_router will re-probe and pick up the (still canonical) hero_codescalers/ directory. If a prior run left a stale hero_codescalers_server/ directory on disk, operators should rm -rf ~/hero/var/sockets/hero_codescalers_server* once.
No database / config / secret changes: this is purely a documentation + defensive-warning change in the CLI. KVS data dirs (~/hero/var/hero_codescalers/db) are untouched.
heroservice.json already correct: both crates/hero_codescalers_server/heroservice.json and crates/hero_codescalers_ui/heroservice.json declare "name": "hero_codescalers" (verified). hero_router uses this value as the authoritative service name when grouping rpc.sock and ui.sock from the same directory under one logical service.
Multi-instance still works: instance N's directory remains hero_codescalers_{N} (e.g. hero_codescalers_1/). The README table fix preserves this — only the legacy _server segment is removed.

## Implementation Spec for Issue #17 ### Objective Eliminate every remaining reference to the legacy `hero_codescalers_server`-prefixed socket directory naming so that hero_router reliably discovers `hero_codescalers` under the canonical Hero socket convention (`$HERO_SOCKET_DIR/hero_codescalers/{rpc,ui}.sock`) and the UI stops being stuck in "starting". ### Root Cause The Rust source has already been migrated to the canonical convention (`SERVICE_NAME = "hero_codescalers"` is used as the default `--sockname` in both binaries and as the `sock_dir_name(0)` value in the CLI), per the previous fix in commit `7edb4e3` ("fix(cli): align CLI socket dir default with the server's", PR #16). However, **stale documentation and a wrong env-var default in `README.md`** still describe the OLD layout, which is what is making operators (and freshly-built environments where `HERO_CODESCALERS_SOCK_NAME=hero_codescalers_server` was exported from a previous setup) bind to a directory that hero_router does not look in. Specifically: - `README.md:61-63` — the "Unix socket directories" table still says instance 0 lives in `hero_codescalers_server/` (and instances N in `hero_codescalers_serverN/`), which contradicts the code (`crates/hero_codescalers/src/main.rs:42-51`, which produces `hero_codescalers/` and `hero_codescalers_{N}/`). - `README.md:243` — example command points at `~/hero/var/sockets/hero_codescalers_server1/rpc.sock`, a path that nothing in the code now produces. - `README.md:265` — env var table claims `HERO_CODESCALERS_SOCK_NAME` defaults to `hero_codescalers_server`. The actual default, set via clap's `default_value = SERVICE_NAME` in `crates/hero_codescalers_server/src/main.rs:43` and `crates/hero_codescalers_ui/src/main.rs:59`, is `hero_codescalers`. - The literal string `hero_codescalers_server_ui` from the issue title does not appear in source — it is a description of the *symptom*: when the UI binary inherited a stale `HERO_CODESCALERS_SOCK_NAME=hero_codescalers_server` from the environment, both binaries wrote into `hero_codescalers_server/`, and hero_router (which scans for `<service>/{rpc,ui}.sock` and reads the `name` field from `.well-known/heroservice.json`) saw a directory whose name did not match the manifest's `name: "hero_codescalers"` and could not stitch the UI behind the RPC service — leaving the UI listed but stuck in "starting". The code itself is consistent: `heroservice.json` for both crates declares `"name": "hero_codescalers"`; both binaries default `--sockname` to `SERVICE_NAME = "hero_codescalers"`; the CLI's `sock_dir_name(instance)` returns `hero_codescalers` for instance 0; both server and UI are launched with `HERO_CODESCALERS_SOCK_NAME = sock_dir_name(instance)` from the CLI (`crates/hero_codescalers/src/main.rs:458,500`). The bug is purely that the README still documents the legacy default and that there is no defensive guard against a stale exported env var overriding the CLI-supplied value. The issue body's "expected naming" — `$HERO_SOCKET_DIR/hero_codescalers_server<N>/rpc.sock` — itself uses the *legacy* form. The canonical Hero socket convention (per the `hero_sockets` skill, sections 2 and 12) is unambiguous: the directory name MUST equal the service name, MUST NOT carry `_server`/`_ui`/`_sdk` suffixes, and `<service>/rpc.sock` is the canonical layout. The author of the issue likely typed the legacy name from memory; we should align the fix on the canonical `hero_codescalers/` convention that the manifests and the actual Rust code already use. ### Requirements - The README's documented socket directories, env-var defaults, and example commands MUST match the code's behaviour (`hero_codescalers/`, `hero_codescalers_{N}/`). - A stale `HERO_CODESCALERS_SOCK_NAME` exported in the operator's environment MUST NOT silently override the CLI's instance-derived directory name and MUST NOT cause the UI's socket to land in a different directory from the server's. - `heroservice.json` for both crates MUST keep declaring `"name": "hero_codescalers"`. - After the fix, hero_router scanning `$HERO_SOCKET_DIR` MUST find `hero_codescalers/rpc.sock` AND `hero_codescalers/ui.sock` in the same directory, both manifest-named `hero_codescalers`, and present `hero_codescalers` as Healthy with a clickable UI link. - All tests, smoke scripts, and Makefile targets that reference socket paths MUST already use `hero_codescalers/` (verified: `Makefile:13-14`, `crates/hero_codescalers_ui/scripts/test-users-ui.sh:74`). ### Files to Modify/Create - `README.md` — fix the "Unix socket directories" table (lines 61-63), the CLI example path (line 243), and the env-var defaults table (line 265) to match the code's actual behaviour. - `crates/hero_codescalers/src/main.rs` — make `self_start` immune to a stale exported `HERO_CODESCALERS_SOCK_NAME` by adding a startup guard that warns if the external `HERO_CODESCALERS_SOCK_NAME` differs from the instance-derived value. ### Implementation Plan #### Step 1: Fix the README documentation drift Files: `README.md` Changes: - Replace the "Unix socket directories" table (currently lines 59-63) so the directory column reads `hero_codescalers/`, `hero_codescalers_1/`, `hero_codescalers_N/` (matching `sock_dir_name()` in `crates/hero_codescalers/src/main.rs:42-51`). - Update the example command on line 243 from `~/hero/var/sockets/hero_codescalers_server1/rpc.sock` to `~/hero/var/sockets/hero_codescalers_1/rpc.sock`. - Update the env-var defaults table on line 265 so the default for `HERO_CODESCALERS_SOCK_NAME` reads `hero_codescalers` (matching `SERVICE_NAME` in both `_server` and `_ui` `main.rs`). Dependencies: none #### Step 2: Add a defensive startup guard in the CLI against a stale exported `HERO_CODESCALERS_SOCK_NAME` Files: `crates/hero_codescalers/src/main.rs` Changes: - In `build_service_definition` (lines 419-539), after computing `let dir = sock_dir_name(instance);` (line 433), check if the *current process* already has `HERO_CODESCALERS_SOCK_NAME` exported and it differs from `dir`. If so, emit a single `eprintln!` warning telling the operator that the exported value is being overridden by the instance-derived value for the spawned action's environment. - Concretely, add right before line 444 (`// ── Server action ──`): ```rust if let Ok(stale) = std::env::var("HERO_CODESCALERS_SOCK_NAME") { if stale != dir { eprintln!( "warning: HERO_CODESCALERS_SOCK_NAME='{stale}' in caller env differs \ from instance-derived '{dir}'; the spawned actions will use '{dir}'." ); } } ``` Dependencies: none (independent of Step 1) #### Step 3: Verify hero_router picks up the service end-to-end Files: none (verification only) Changes: - `make install && hero_codescalers --start`. - Confirm `~/hero/var/sockets/hero_codescalers/rpc.sock` and `~/hero/var/sockets/hero_codescalers/ui.sock` both exist. - `curl --unix-socket ~/hero/var/sockets/hero_codescalers/rpc.sock http://localhost/.well-known/heroservice.json` returns `"name":"hero_codescalers","socket":"rpc"`. - `curl --unix-socket ~/hero/var/sockets/hero_codescalers/ui.sock http://localhost/.well-known/heroservice.json` returns `"name":"hero_codescalers","socket":"ui"`. - Open hero_router dashboard (default `http://127.0.0.1:9988/`) — `hero_codescalers` MUST appear as Healthy and clickable; clicking the UI link MUST land on the dashboard via `http://127.0.0.1:9988/hero_codescalers/ui/`, no longer "starting". Dependencies: Step 1 and Step 2 merged. ### Acceptance Criteria - [ ] `README.md` no longer contains the strings `hero_codescalers_server/`, `hero_codescalers_server1/`, `hero_codescalers_serverN/`, or the env-var default `hero_codescalers_server`. - [ ] `crates/hero_codescalers/src/main.rs` warns (non-fatally) when a stale exported `HERO_CODESCALERS_SOCK_NAME` would have differed from the instance-derived directory. - [ ] After `hero_codescalers --start`, `~/hero/var/sockets/hero_codescalers/rpc.sock` AND `~/hero/var/sockets/hero_codescalers/ui.sock` both exist (single shared directory, no `_server` or `_ui` directory siblings created). - [ ] `hero_router` dashboard lists `hero_codescalers` as Healthy / connected / clickable and the UI link no longer reports "starting". - [ ] `cargo build --workspace --release`, `cargo fmt --all -- --check`, and `cargo clippy --workspace --all-targets -- -D warnings` all pass. - [ ] No regression in `make test-server` or `make test-ui` (both already point at `~/hero/var/sockets/hero_codescalers/{rpc,ui}.sock`). ### Notes - **Service name convention**: the issue body's `$HERO_SOCKET_DIR/hero_codescalers_server<N>/rpc.sock` form is the *legacy* layout. The canonical Hero convention (`hero_sockets` skill section 2 and 12) is `$HERO_SOCKET_DIR/<service>/<type>.sock` with NO `_server`/`_ui` suffix on the directory. The Rust code already follows the canonical form; this fix only catches up the README and adds a defence against a stale env var. We are aligning with the canonical convention, not the issue body's example. - **No hero_router restart required**: hero_router scans `$HERO_SOCKET_DIR` periodically (default `HERO_ROUTER_REFRESH=30` seconds); after the next stop/start of `hero_codescalers`, hero_router will re-probe and pick up the (still canonical) `hero_codescalers/` directory. If a prior run left a stale `hero_codescalers_server/` directory on disk, operators should `rm -rf ~/hero/var/sockets/hero_codescalers_server*` once. - **No database / config / secret changes**: this is purely a documentation + defensive-warning change in the CLI. KVS data dirs (`~/hero/var/hero_codescalers/db`) are untouched. - **`heroservice.json` already correct**: both `crates/hero_codescalers_server/heroservice.json` and `crates/hero_codescalers_ui/heroservice.json` declare `"name": "hero_codescalers"` (verified). hero_router uses this value as the authoritative service name when grouping `rpc.sock` and `ui.sock` from the same directory under one logical service. - **Multi-instance still works**: instance N's directory remains `hero_codescalers_{N}` (e.g. `hero_codescalers_1/`). The README table fix preserves this — only the legacy `_server` segment is removed.

mahmoud commented

2026-04-29 08:41:25 +00:00

Author

Owner

Test Results

cargo fmt --all -- --check

fail (pre-existing, unrelated to issue #17 changes)

Total diffs reported: 122 across 18 files
Verified by stashing the issue #17 patch and re-running cargo fmt --check on HEAD (commit a5d0f5c): the same 122 diffs are present, so this is a baseline issue in the repo, not a regression from this change.
The two files modified for issue #17 (README.md and crates/hero_codescalers/src/main.rs — adding the stale-env-var warning) do not introduce any new fmt diffs in our edited region. The main.rs diffs are in unrelated lines (e.g. struct-init formatting in command handlers around lines 173, 251, 277, etc.).

Representative excerpt (unrelated to our edit):

Diff in crates/hero_codescalers/src/main.rs:173:
-    UserDelete {
-        username: String,
-    },
+    UserDelete { username: String },

cargo clippy --workspace --all-targets -- -D warnings

fail (pre-existing, unrelated to issue #17 changes)

Verified by stashing the issue #17 patch and re-running clippy on HEAD: 32 errors are reported in hero_codescalers_server (e.g. collapsible_if lint in crates/hero_codescalers_server/src/main.rs:272).
With our patch applied, the first surfaced error is dead_code on IndexTemplate.version in crates/hero_codescalers_ui/src/main.rs:113 — also a file we did not touch.
Conclusion: clippy -D warnings is currently red on development baseline; our change does not add any new lints.

Last warnings (with patch applied):

error: field `version` is never read
   --> crates/hero_codescalers_ui/src/main.rs:113:5
    |
110 | struct IndexTemplate {
    |        ------------- field in this struct
...
113 |     version: String,
    |     ^^^^^^^
    |
    = note: `-D dead-code` implied by `-D warnings`

cargo test --workspace

Total: 10
Passed: 10
Failed: 0

Breakdown:

hero_codescalers (bin unittests): 2 passed (tests::duration_units, tests::duration_errors)
hero_codescalers_sdk (lib unittests): 0 tests
hero_codescalers_server (bin unittests): 5 passed (jobs cleanup tests)
hero_codescalers_ui (bin unittests): 0 tests
nu_exec (lib unittests): 0 tests
hero_codescalers_sdk doc-tests: 1 passed
nu_exec doc-tests: 2 passed

All workspace tests pass. The server bin emits 13 dead_code warnings during the test build (pre-existing — same warnings on HEAD without the patch).

Notes

make test-server and make test-ui were not run because they require a live hero_proc / hero_router stack; that is part of the manual verification in Step 3 of the spec.
The fmt and clippy failures above are pre-existing on the development baseline and are not introduced by this issue's changes; fixing them is out of scope for issue #17.
Our two source-level changes for issue #17 are: README.md (legacy socket-directory names replaced with the canonical hero_codescalers/ form) and crates/hero_codescalers/src/main.rs (added a non-fatal eprintln! warning in build_service_definition when a stale HERO_CODESCALERS_SOCK_NAME env var differs from the instance-derived directory).

## Test Results ### cargo fmt --all -- --check fail (pre-existing, unrelated to issue #17 changes) - Total diffs reported: 122 across 18 files - Verified by stashing the issue #17 patch and re-running `cargo fmt --check` on `HEAD` (commit `a5d0f5c`): the same 122 diffs are present, so this is a baseline issue in the repo, not a regression from this change. - The two files modified for issue #17 (`README.md` and `crates/hero_codescalers/src/main.rs` — adding the stale-env-var warning) do not introduce any new fmt diffs in our edited region. The `main.rs` diffs are in unrelated lines (e.g. struct-init formatting in command handlers around lines 173, 251, 277, etc.). Representative excerpt (unrelated to our edit): ``` Diff in crates/hero_codescalers/src/main.rs:173: - UserDelete { - username: String, - }, + UserDelete { username: String }, ``` ### cargo clippy --workspace --all-targets -- -D warnings fail (pre-existing, unrelated to issue #17 changes) - Verified by stashing the issue #17 patch and re-running clippy on `HEAD`: 32 errors are reported in `hero_codescalers_server` (e.g. `collapsible_if` lint in `crates/hero_codescalers_server/src/main.rs:272`). - With our patch applied, the first surfaced error is `dead_code` on `IndexTemplate.version` in `crates/hero_codescalers_ui/src/main.rs:113` — also a file we did not touch. - Conclusion: clippy `-D warnings` is currently red on `development` baseline; our change does not add any new lints. Last warnings (with patch applied): ``` error: field `version` is never read --> crates/hero_codescalers_ui/src/main.rs:113:5 | 110 | struct IndexTemplate { | ------------- field in this struct ... 113 | version: String, | ^^^^^^^ | = note: `-D dead-code` implied by `-D warnings` ``` ### cargo test --workspace - Total: 10 - Passed: 10 - Failed: 0 Breakdown: - `hero_codescalers` (bin unittests): 2 passed (`tests::duration_units`, `tests::duration_errors`) - `hero_codescalers_sdk` (lib unittests): 0 tests - `hero_codescalers_server` (bin unittests): 5 passed (jobs cleanup tests) - `hero_codescalers_ui` (bin unittests): 0 tests - `nu_exec` (lib unittests): 0 tests - `hero_codescalers_sdk` doc-tests: 1 passed - `nu_exec` doc-tests: 2 passed All workspace tests pass. The server bin emits 13 `dead_code` warnings during the test build (pre-existing — same warnings on `HEAD` without the patch). ### Notes - `make test-server` and `make test-ui` were not run because they require a live `hero_proc` / `hero_router` stack; that is part of the manual verification in Step 3 of the spec. - The fmt and clippy failures above are pre-existing on the `development` baseline and are not introduced by this issue's changes; fixing them is out of scope for issue #17. - Our two source-level changes for issue #17 are: README.md (legacy socket-directory names replaced with the canonical `hero_codescalers/` form) and `crates/hero_codescalers/src/main.rs` (added a non-fatal `eprintln!` warning in `build_service_definition` when a stale `HERO_CODESCALERS_SOCK_NAME` env var differs from the instance-derived directory).

mahmoud commented

2026-04-29 09:59:17 +00:00

Author

Owner

Implementation Summary

The Rust source already binds to the canonical hero_codescalers/ socket directory (see commit 7edb4e3 / PR #16); the "stuck in starting" symptom was caused by stale README documentation pointing at the legacy hero_codescalers_server/ layout, plus the absence of any guard against an operator carrying a stale HERO_CODESCALERS_SOCK_NAME export from a previous setup.

Changes

README.md — replaced legacy socket-directory references with the canonical names:

"Unix socket directories" table (lines 61-63):
- instance 0: hero_codescalers_server/ → hero_codescalers/
- instance 1: hero_codescalers_server1/ → hero_codescalers_1/
- instance N: hero_codescalers_serverN/ → hero_codescalers_N/
Example command (line 243):
- ~/hero/var/sockets/hero_codescalers_server1/rpc.sock → ~/hero/var/sockets/hero_codescalers_1/rpc.sock
Env-var defaults table (line 265):
- HERO_CODESCALERS_SOCK_NAME default: hero_codescalers_server → hero_codescalers

The remaining hero_codescalers_server matches in the README are deliberately kept — they refer to the binary name (line 15) and to hero_proc action names (lines 69-71), which are distinct from the socket directory.

crates/hero_codescalers/src/main.rs — added a non-fatal startup guard inside build_service_definition. When the caller's environment already exports HERO_CODESCALERS_SOCK_NAME and the value differs from the instance-derived directory, an eprintln! warning is emitted before the actions are spawned. The CLI was already passing the correct value via ActionBuilder::env(...) at lines 458 and 500, so this is purely informational and removes the silent foot-gun.

if let Ok(stale) = std::env::var("HERO_CODESCALERS_SOCK_NAME") {
    if stale != dir {
        eprintln!(
            "warning: HERO_CODESCALERS_SOCK_NAME='{stale}' in caller env differs \
             from instance-derived '{dir}'; the spawned actions will use '{dir}'."
        );
    }
}

Test Results

cargo test --workspace — pass (10/10: 2 hero_codescalers + 5 hero_codescalers_server + 1 sdk doctest + 2 nu_exec doctests; zero failures)
cargo fmt --all -- --check — fail (122 diffs across 18 files; verified to be a pre-existing baseline on development HEAD a5d0f5c, not introduced by this patch)
cargo clippy --workspace --all-targets -- -D warnings — fail (32 errors on baseline HEAD; same set with our patch applied, no new lints from the changes here)

The fmt and clippy failures are pre-existing on the development branch and outside the scope of issue #17. They should be tracked in a separate ticket.

Acceptance Criteria

README.md no longer contains socket-directory references to hero_codescalers_server/, hero_codescalers_server1/, hero_codescalers_serverN/, or the env-var default hero_codescalers_server.
crates/hero_codescalers/src/main.rs warns (non-fatally) when a stale exported HERO_CODESCALERS_SOCK_NAME would have differed from the instance-derived directory.
cargo check -p hero_codescalers clean; workspace tests pass.
After hero_codescalers --start, both ~/hero/var/sockets/hero_codescalers/rpc.sock and ~/hero/var/sockets/hero_codescalers/ui.sock exist (manual verification — Step 3).
hero_router dashboard lists hero_codescalers as Healthy / connected / clickable; the UI link no longer reports "starting" (manual verification — Step 3).

Manual Verification Required (Step 3 of spec)

This patch does not run the full stack. Before closing the issue, please:

make install and hero_codescalers --start from a freshly-checked-out copy of this branch.
Confirm ~/hero/var/sockets/hero_codescalers/rpc.sock and ~/hero/var/sockets/hero_codescalers/ui.sock both exist in the same directory.
curl --unix-socket ~/hero/var/sockets/hero_codescalers/rpc.sock http://localhost/.well-known/heroservice.json returns "name":"hero_codescalers","socket":"rpc".
Same against ui.sock, returning "socket":"ui".
Open the hero_router dashboard (default http://127.0.0.1:9988/) and confirm hero_codescalers appears Healthy and the UI link works.
If the operator's previous setup left a stale ~/hero/var/sockets/hero_codescalers_server*/ directory on disk, run rm -rf ~/hero/var/sockets/hero_codescalers_server* once.

Branch

Changes committed locally on development_fix_codescalers_service_name (no push, no PR — opening a PR is out of scope for this skill).

## Implementation Summary The Rust source already binds to the canonical `hero_codescalers/` socket directory (see commit `7edb4e3` / PR #16); the "stuck in starting" symptom was caused by stale README documentation pointing at the legacy `hero_codescalers_server/` layout, plus the absence of any guard against an operator carrying a stale `HERO_CODESCALERS_SOCK_NAME` export from a previous setup. ### Changes **`README.md`** — replaced legacy socket-directory references with the canonical names: - "Unix socket directories" table (lines 61-63): - instance 0: `hero_codescalers_server/` → `hero_codescalers/` - instance 1: `hero_codescalers_server1/` → `hero_codescalers_1/` - instance N: `hero_codescalers_serverN/` → `hero_codescalers_N/` - Example command (line 243): - `~/hero/var/sockets/hero_codescalers_server1/rpc.sock` → `~/hero/var/sockets/hero_codescalers_1/rpc.sock` - Env-var defaults table (line 265): - `HERO_CODESCALERS_SOCK_NAME` default: `hero_codescalers_server` → `hero_codescalers` The remaining `hero_codescalers_server` matches in the README are deliberately kept — they refer to the binary name (line 15) and to hero_proc action names (lines 69-71), which are distinct from the socket directory. **`crates/hero_codescalers/src/main.rs`** — added a non-fatal startup guard inside `build_service_definition`. When the caller's environment already exports `HERO_CODESCALERS_SOCK_NAME` and the value differs from the instance-derived directory, an `eprintln!` warning is emitted before the actions are spawned. The CLI was already passing the correct value via `ActionBuilder::env(...)` at lines 458 and 500, so this is purely informational and removes the silent foot-gun. ```rust if let Ok(stale) = std::env::var("HERO_CODESCALERS_SOCK_NAME") { if stale != dir { eprintln!( "warning: HERO_CODESCALERS_SOCK_NAME='{stale}' in caller env differs \ from instance-derived '{dir}'; the spawned actions will use '{dir}'." ); } } ``` ### Test Results - `cargo test --workspace` — **pass** (10/10: 2 hero_codescalers + 5 hero_codescalers_server + 1 sdk doctest + 2 nu_exec doctests; zero failures) - `cargo fmt --all -- --check` — fail (122 diffs across 18 files; verified to be a pre-existing baseline on `development` HEAD `a5d0f5c`, not introduced by this patch) - `cargo clippy --workspace --all-targets -- -D warnings` — fail (32 errors on baseline `HEAD`; same set with our patch applied, no new lints from the changes here) The fmt and clippy failures are pre-existing on the `development` branch and outside the scope of issue #17. They should be tracked in a separate ticket. ### Acceptance Criteria - [x] `README.md` no longer contains socket-directory references to `hero_codescalers_server/`, `hero_codescalers_server1/`, `hero_codescalers_serverN/`, or the env-var default `hero_codescalers_server`. - [x] `crates/hero_codescalers/src/main.rs` warns (non-fatally) when a stale exported `HERO_CODESCALERS_SOCK_NAME` would have differed from the instance-derived directory. - [x] `cargo check -p hero_codescalers` clean; workspace tests pass. - [ ] After `hero_codescalers --start`, both `~/hero/var/sockets/hero_codescalers/rpc.sock` and `~/hero/var/sockets/hero_codescalers/ui.sock` exist (manual verification — Step 3). - [ ] hero_router dashboard lists `hero_codescalers` as Healthy / connected / clickable; the UI link no longer reports "starting" (manual verification — Step 3). ### Manual Verification Required (Step 3 of spec) This patch does not run the full stack. Before closing the issue, please: 1. `make install` and `hero_codescalers --start` from a freshly-checked-out copy of this branch. 2. Confirm `~/hero/var/sockets/hero_codescalers/rpc.sock` and `~/hero/var/sockets/hero_codescalers/ui.sock` both exist in the same directory. 3. `curl --unix-socket ~/hero/var/sockets/hero_codescalers/rpc.sock http://localhost/.well-known/heroservice.json` returns `"name":"hero_codescalers","socket":"rpc"`. 4. Same against `ui.sock`, returning `"socket":"ui"`. 5. Open the hero_router dashboard (default `http://127.0.0.1:9988/`) and confirm `hero_codescalers` appears Healthy and the UI link works. 6. If the operator's previous setup left a stale `~/hero/var/sockets/hero_codescalers_server*/` directory on disk, run `rm -rf ~/hero/var/sockets/hero_codescalers_server*` once. ### Branch Changes committed locally on `development_fix_codescalers_service_name` (no push, no PR — opening a PR is out of scope for this skill).

mahmoud referenced this issue from a commit

2026-04-29 10:16:38 +00:00

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

mahmoud referenced this issue from a pull request that will close it,

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

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

mahmoud closed this issue

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

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

lhumina_code/hero_codescalers#17

No description provided.

Rows
Columns

[hero_codescalers] Fix service registration name — UI stuck in starting #17

Problem

Steps to fix

Acceptance Criteria

Implementation Spec for Issue #17

Objective

Root Cause

Requirements

Files to Modify/Create

Implementation Plan

Step 1: Fix the README documentation drift

Step 2: Add a defensive startup guard in the CLI against a stale exported HERO_CODESCALERS_SOCK_NAME

Step 3: Verify hero_router picks up the service end-to-end

Acceptance Criteria

Notes

Test Results

cargo fmt --all -- --check

cargo clippy --workspace --all-targets -- -D warnings

cargo test --workspace

Notes

Implementation Summary

Changes

Test Results

Acceptance Criteria

Manual Verification Required (Step 3 of spec)

Branch

Step 2: Add a defensive startup guard in the CLI against a stale exported `HERO_CODESCALERS_SOCK_NAME`