service_collab.nu — hero_collab server + UI lifecycle module #84
Labels
No labels
prio_critical
prio_low
type_bug
type_contact
type_issue
type_lead
type_question
type_story
type_task
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
lhumina_code/hero_skills#84
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Child of #75.
Objective
Add
tools/modules/services/service_collab.nuimplementing the standardinstall | start | stop | statuslifecycle for the hero_collab service (server + UI).Scope
ssh://git@forge.ourworld.tf/lhumina_code/hero_collab.gitbuildenv.sh):hero_collab,hero_collab_server,hero_collab_uihero_collab_server,hero_collab_uilhumina_code/hero_zero/services/hero_collab.toml$HERO_SOCKET_DIR/hero_collab/rpc.sock,$HERO_SOCKET_DIR/hero_collab/ui.sock(confirm in spec)RUST_LOG=infofor both — no placeholders.[package]).--rootflag optional, user-level default.Acceptance criteria
use services/mod.nu *makesservice_collabavailable.service_collab install [--root] [--update]clones + builds all 3 binaries, installs to~/hero/bin/(or/root/hero/bin/).service_collab start [--reset] [--root] [--update]registers both actions + the service, starts, prints sockets + UI URL. Idempotent without--reset.service_collab status [--root]reports state.service_collab stop [--root]cleanly unregisters.Template
service_whiteboard.nu(PR #83, merged) — identical pattern expected (virtual workspace, noserve, no preflight, no env placeholders). This should be another pure copy-rename if the spec phase confirms hero_collab's binaries match.Spec should verify:
servesubcommand viahero_collab_server --help/main.rsinspection.$HERO_SOCKET_DIR/hero_collab/{rpc,ui}.sockconvention.If any of those diverge, the spec should call out exactly what and adapt.
Implementation Spec for Issue #84
Objective
Add
tools/modules/services/service_collab.nu— a pure copy-rename ofservice_whiteboard.nuprovidinginstall | start | stop | statusforhero_collab(server + UI) viahero_proc.Requirements
lhumina_code/hero_collab:hero_collab,hero_collab_server,hero_collab_ui(CLI is shipped, not registered as a hero_proc action).hero_collab_server(rpc.sock, OpenRPC health check) andhero_collab_ui(ui.sock, OpenRPC health check).hero_collabin contextcore, classsystem, criticalfalse.env: {RUST_LOG: "info"}on both actions — no other env vars, no placeholders.depends_on(matcheshero_collab.toml— zero dependencies declared).svc_require_proc;--rootwith sudo;--updateforforge merge;--resetfor clean re-register../lib.nu's shared helpers only. No new helpers, no preflight, no custom state directories.Files to Modify/Create
tools/modules/services/service_collab.nu— new, ~310 lines, cloned fromservice_whiteboard.nu.tools/modules/services/mod.nu— appendexport use service_collab.nu(last line, afterservice_whiteboard.nuon line 10).Implementation Plan
Verbatim copy-rename of
service_whiteboard.nu. Every edit is a literal string substitution — no structural changes.Step 1: Copy
service_whiteboard.nu→service_collab.nuStep 2: Header comment block (
service_whiteboard.nulines 1–39)Substitute
whiteboard→collabthroughout the banner. Adjust the description lines:OpenRPC state server for workspaces, channels, messages, canvases, and huddles.HTTP server that serves the collab UI at '/' and admin dashboard at '/admin/' over a Unix socket.$HERO_SOCKET_DIR/hero_collab/{rpc,ui}.sock(confirmed againstcrates/hero_collab_server/src/main.rs:98-104,266-268andcrates/hero_collab_ui/src/main.rs:22-34).main.rs:262-274). Add a one-liner noting the server accepts optional--auth-mode,--livekit-*, and--seed-dev-usersflags (main.rs:38-95) — the module passes NONE, which gives the safe production defaults (auth_mode=proxy, huddles disabled).Step 3: Constants block (lines 48–53)
SVX_SERVICE_NAME = "hero_collab"SVX_FORGE_LOC = "lhumina_code/hero_collab"hero_collab is the CLI, shipped but not registered as a hero_proc action.SVX_BINARIES = ["hero_collab" "hero_collab_server" "hero_collab_ui"]SVX_ACTIONS = ["hero_collab_server" "hero_collab_ui"]Step 4: Action spec builders
svx_server_action(whiteboard lines 59–98):svc_bin "hero_collab_server".name: "hero_collab_server".kill_other.socket: [$"($sock_base)/hero_collab/rpc.sock"].health_checks[0].action: "hero_collab_server",.openrpc_socket: .../hero_collab/rpc.sock.svx_ui_action(whiteboard lines 100–139):svc_bin "hero_collab_ui".name: "hero_collab_ui".kill_other.socket: [$"($sock_base)/hero_collab/ui.sock"].health_checks[0].action: "hero_collab_ui",.openrpc_socket: .../hero_collab/ui.sock.svx_service_config(whiteboard lines 141–153):description: "Hero Collab — collaboration platform: workspaces, channels, messages, canvases, huddles"(mirrorshero_collab.toml:3).svx_drop_registration(whiteboard lines 156–162): no changes — constants drive it.Step 5:
install,start,stop,status(whiteboard lines 171–312)Text substitution of
whiteboard→collabthroughout. Key spots:svc_require_proc "service_collab"in start and status.($sock_base)/hero_collab/rpc.sock,/hero_collab/ui.sock.proc logs tail hero_collab_server/hero_collab_uiin the commands block.Step 6: Register in
mod.nuAppend
export use service_collab.nuafterservice_whiteboard.nu(current line 10).Step 7: Syntax-check and smoke test
nu -c "source tools/modules/services/service_collab.nu; print parse-ok".nu -c "use tools/modules/services/mod.nu *; scope commands | where name =~ '^service_collab '"— expect 4 subcommands.service_collab install --root— cargo build + 3 binaries in/root/hero/bin/.service_collab start --reset --root— both actions registered, both sockets live, state: running.service_collab status --root— record shows running, 0 restarts.service_collab start --root— idempotent "already running".service_collab stop --root— clean unregistration.service_collab status --root— expectedservice 'hero_collab' not found.Acceptance Criteria
tools/modules/services/service_collab.nuexists and exportsinstall,start,stop,status.tools/modules/services/mod.nuincludesexport use service_collab.nu.service_collab installbuilds all three binaries and copies them to$HOME/hero/bin/(or/root/hero/bin/with--root).service_collab startregistershero_collab_server+hero_collab_uiactions and thehero_collabservice, starts it, prints the summary block with both socket paths.service_collab startis idempotent;--resetforces clean re-register.service_collab stopunregisters cleanly; safe when nothing is registered or hero_proc is down.service_collab statusproxiesproc service status hero_collab.--rootworks end-to-end with passwordless sudo;--updatepulls viaforge mergebefore rebuild.proc service status.Notes
hero_collab/Cargo.toml:1-10is[workspace]-only with 6 members and no root[package]; no hybrid-workspace accommodation needed. Matches whiteboard.servesubcommand on either binary.hero_collab_serveruses clap with optional args only (--auth-mode,--livekit-*,--seed-dev-users; all have safe defaults —main.rs:38-95).hero_collab_uitakes zero args (main.rs:36-43). Both launch with bareexec.$HERO_SOCKET_DIR/hero_collab/rpc.sock(server,main.rs:98-104,266-268) and$HERO_SOCKET_DIR/hero_collab/ui.sock(UI,main.rs:22-34). Both binaries remove a stale socket before bind.~/hero/var/data/hero_collab/and openscollab.dbon first start. No preflight needed.HOMEenv to be set; hero_proc's spawn sets this.apikeys.dbat the repo root is a dev artifact — no code path inmain.rsordb.rsreferences it. Ignore it.proxy(fail-closed). Raw RPC calls without hero_proxy'sX-Hero-Userheader will be rejected, but the service itself starts cleanly and health checks pass. Production-correct default — do not pass--auth-mode=devfrom the module.hero_collab.toml:9-11,17-19has onlyRUST_LOG = "info"on each of[server.env]/[ui.env]).hero_collab.tomldeclares none.Critical Files for Implementation
Implementation summary
Changes
tools/modules/services/service_collab.nu— ~275 lines, pure copy-rename ofservice_whiteboard.nu.tools/modules/services/mod.nu— addedexport use service_collab.nu.End-to-end smoke test on Hetzner
Every assertion green.
service_proc start --roothealthyservice_collab install --rootproduced 3 binariesservice_collab start --reset --rootregisters + startsrpc.socklive unix socketui.socklive unix socketcurl --unix-socket rpc.sockaccepts HTTPcurl --unix-socket ui.sockaccepts HTTPstatusreturns{name: hero_collab, state: running, restarts: 0}startwithout--resetprints "already running"runningservice_collab stop --rootstops and unregistersstatusreturns expectedservice 'hero_collab' not foundEvery dimension tested matches the service_whiteboard baseline — no hero_collab-specific surprises. Both sockets come up, both health-check clean, auth_mode defaults to
proxy(production-correct) without intervention, LiveKit is off as expected.Acceptance criteria
use services/mod.nu *oruse services/service_collab.nu *.installbuilds 3 binaries and places them in~/hero/bin/(or/root/hero/bin/with--root).startregisters both actions + the service, starts, surfaces both sockets in the summary.statusreports the hero_proc record.stopcleanly unregisters.--rootoptional, user-level default.PR opened: #85