feat(service_os): close lifecycle gaps — start_base/start_full bundles + islands_build with preflight #162

New issue

Open

opened 2026-04-28 21:26:40 +00:00 by sameh-farouk · 0 comments

sameh-farouk commented

2026-04-28 21:26:40 +00:00

Member

Summary

service_os has two lifecycle gaps that bite anyone setting up hero_os from scratch:

No bundle-start command. A working hero_os deploy needs hero_proc + hero_router + several companion services (osis, aibroker, proxy, plus optional collab/livekit/voice/books/biz/foundry/indexer/embedder/codescalers/browser). Until now users had to compose service_X start calls by hand and remember the right set + ordering.
No service_* wrapper for the per-island WASM build. A complete UI needs THREE artifact phases: hero_os Rust binaries (service_os install), the main hero_os_app shell WASM (service_os wasm_build), and ~30 per-island WASM bundles built from hero_archipelagos via wasm-pack. Phase 3 has no service_os wrapper — users have to know to manually run cd ~/hero/code0/hero_archipelagos && make install. There's also no preflight warning when the islands directory is missing, so the failure mode is "click a dock icon → 404 in the browser console" rather than "see a hint at start time."

Plus a non-obvious operational gotcha for phase 3: hero_os_ui only registers the /islands HTTP route if the directory exists at process startup. So even after a successful islands install, the running hero_os_ui won't serve them until it's restarted.

Proposal

Three new commands + one preflight warn, all added to tools/modules/services/service_os.nu:

service_os start_base      # service_os + osis + aibroker + proxy
service_os start_full      # start_base + livekit + collab + voice + books + biz +
                           # foundry + indexer + embedder + codescalers + browser
service_os islands_build   # build + install per-island WASM bundles
                           # (wraps `cd ~/hero/code0/hero_archipelagos && make install`)

All three accept the standard --root / --update / --reset flags from the existing module conventions. islands_build also takes --restart (because of the at-startup route registration caveat above) and preflights wasm-pack availability.

start now has a non-fatal preflight warn for missing islands, mirroring the existing svx_check_assets pattern:

⚠ per-island WASM bundles not found at ~/hero/share/hero_os/islands
  Dock items will 404 when clicked (the desktop shell still loads).
  Build + install them once:
    service_os islands_build --restart

Design choices

No auto-chaining. start doesn't auto-call wasm_build/islands_build; start_base/start_full doesn't auto-call them either. Same separation-of-phases the module already uses for install vs wasm_build. Each phase logs separately and can be re-run independently.
start_base companion set is opinionated. Just the services hero_os_app actually consumes via SDK imports (hero_osis_sdk for AI bar / spaces) plus auth (hero_proxy, per the registry.rs comment "auth moves to hero_proxy"). Everything else is feature-island specific and goes in start_full.
start_full does explicit ordering. livekit before collab (collab auto-chains livekit, but explicit ordering keeps output readable).

hero_os#44 (open) — symptom report: "OSIS island crashes with WASM 404 error" — same class of gap caught by the new preflight warn
hero_demo#34 (open, was home#171) — broader UI-shell discussion about which islands need fallbacks
home#190 (open) — architectural question about parallel _app crates and island-*-native features

Acceptance

PR with the new commands merged
service_os start_base brings up hero_os + companions on a fresh box
service_os islands_build --restart produces a working dock without manual cd hero_archipelagos
service_os start warns clearly when islands are missing

## Summary `service_os` has two lifecycle gaps that bite anyone setting up hero_os from scratch: 1. **No bundle-start command.** A working hero_os deploy needs hero_proc + hero_router + several companion services (osis, aibroker, proxy, plus optional collab/livekit/voice/books/biz/foundry/indexer/embedder/codescalers/browser). Until now users had to compose `service_X start` calls by hand and remember the right set + ordering. 2. **No `service_*` wrapper for the per-island WASM build.** A complete UI needs THREE artifact phases: hero_os Rust binaries (`service_os install`), the main hero_os_app shell WASM (`service_os wasm_build`), and ~30 per-island WASM bundles built from `hero_archipelagos` via `wasm-pack`. Phase 3 has no `service_os` wrapper — users have to know to manually run `cd ~/hero/code0/hero_archipelagos && make install`. There's also no preflight warning when the islands directory is missing, so the failure mode is "click a dock icon → 404 in the browser console" rather than "see a hint at start time." Plus a non-obvious operational gotcha for phase 3: hero_os_ui only registers the `/islands` HTTP route if the directory **exists at process startup**. So even after a successful islands install, the running hero_os_ui won't serve them until it's restarted. ## Proposal Three new commands + one preflight warn, all added to `tools/modules/services/service_os.nu`: ``` service_os start_base # service_os + osis + aibroker + proxy service_os start_full # start_base + livekit + collab + voice + books + biz + # foundry + indexer + embedder + codescalers + browser service_os islands_build # build + install per-island WASM bundles # (wraps `cd ~/hero/code0/hero_archipelagos && make install`) ``` All three accept the standard `--root` / `--update` / `--reset` flags from the existing module conventions. `islands_build` also takes `--restart` (because of the at-startup route registration caveat above) and preflights wasm-pack availability. `start` now has a non-fatal preflight warn for missing islands, mirroring the existing `svx_check_assets` pattern: ``` ⚠ per-island WASM bundles not found at ~/hero/share/hero_os/islands Dock items will 404 when clicked (the desktop shell still loads). Build + install them once: service_os islands_build --restart ``` ## Design choices - **No auto-chaining.** `start` doesn't auto-call `wasm_build`/`islands_build`; `start_base`/`start_full` doesn't auto-call them either. Same separation-of-phases the module already uses for `install` vs `wasm_build`. Each phase logs separately and can be re-run independently. - **`start_base` companion set is opinionated.** Just the services hero_os_app actually consumes via SDK imports (`hero_osis_sdk` for AI bar / spaces) plus auth (`hero_proxy`, per the registry.rs comment "auth moves to hero_proxy"). Everything else is feature-island specific and goes in `start_full`. - **`start_full` does explicit ordering.** livekit before collab (collab auto-chains livekit, but explicit ordering keeps output readable). ## Related - hero_os#44 (open) — symptom report: "OSIS island crashes with WASM 404 error" — same class of gap caught by the new preflight warn - hero_demo#34 (open, was home#171) — broader UI-shell discussion about which islands need fallbacks - home#190 (open) — architectural question about parallel `_app` crates and `island-*-native` features ## Acceptance - [ ] PR with the new commands merged - [ ] `service_os start_base` brings up hero_os + companions on a fresh box - [ ] `service_os islands_build --restart` produces a working dock without manual `cd hero_archipelagos` - [ ] `service_os start` warns clearly when islands are missing