[platform] migration of repo's on development trunk on the Hero Platform #309
Labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set.
Reference
lhumina_code/home_lhumina#309
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?
migration
See if there are changes done from integration which might have to be cherry picked to ,
development, and putting every service on one repeatable pattern: a schema-driven OSIS backend and a Dioxus frontend, offline-first, behind a clear test gate. Whendevelopmentcarries the whole platform on this pattern, we point the live testing organization at it and verify, then retireintegration.mainstays as the release tag we cut at a strong moment. We drop the rpc2 experiment for good; the backend runs on traditional rpc, which cm50_app already proves with blueprint and the current hero_lib.The pattern (every service looks like this)
Backend. Schemas in
oschema(rootobjects, OTOML types,@index) feed the hero_lib macro (openrpc_server!), which generates the typed CRUD, the dispatch, and the serving entry. Storage is OSIS, generated by hero_blueprint (hero_rpc_osis: DBTyped, OsisObject). hero_lib (hero_lifecycle) serves it as the multi-domain layout: a control plane at/api/rpc(ping, discover_domains) plus one socket per domain at/api/{domain}/rpc. The backend foundation is hero_lib + hero_blueprint; each service keeps its backend in its own workspace so the frontend's old client never enters the backend lockfile.Frontend. Dioxus, using the shared component library hero_components (one service-parameterized admin SPA, reachable through hero_router at
/hero_components/admin/?service=<name>) styled by dioxus-bootstrap-css (Bootstrap 5.3 as type-safe components, zero JavaScript, assets bundled offline). The frontend talks to its backend at/api/{domain}/rpc. Existing user-facing frontends are preserved during the convergence; the Dioxus admin redesign is a parallel track.Offline-first. The admin must not fetch styling from a public CDN at runtime, because a sovereign machine may be offline. dioxus-bootstrap-css bundles its assets offline, which satisfies this by construction. Anything still on the old fetch-and-cache path should bundle its assets locally instead.
Authorization. OSIS authenticates the caller but does no authorization, so generated read methods can expose other users data. Schema-level read, write, and hidden rules are required before any private per-user data reaches real users. Tracked in lhumina_code/home#310 (work in progress, needs team decisions).
How we migrate one service
Three steps, in order. A service advances to the next step only when the current one is fully verified.
Step 1 — Hero-lib based macros, manual backend mapping (no OSIS yet)
Wire each service onto the standard hero_lib macro stack (
openrpc_server!,hero_lifecycle) and the hero loop. Do not change the existing storage layer. Instead, manually map each incoming OpenRPC call to the backend logic that was already there. Use the existing skills for the serving and macro patterns.Once the macros are in place, add a dedicated integration test crate. Tests drive the server through MCP over the router — no direct in-process calls — so they exercise the full network path. Every existing RPC method must be covered and pass before the service leaves this step.
Gate: integration test crate builds green, all existing functionality verified end-to-end over the router.
Step 2 — Dioxus admin UI in hero_components
Add a Dioxus admin interface for the service inside hero_components. The admin talks to the backend exclusively through the router (no direct socket access). All existing admin features must be present and working in the new UI.
Do not remove the custom admin binaries or CLI admin tools until Christophe has reviewed the Dioxus UI and confirmed it is good enough. Only after that explicit sign-off do we retire the old admin.
Gate: Christophe approves the Dioxus admin; all features verified; old admin binaries removed.
Step 3 — cleanup, and docs
For most services: remove the CLI admin tooling (no longer needed once Step 2 is signed off), and document the service in the skills / new docs.
WHEN TO USE OSIS
For a small number of services (initially cm50 and services with the same complexity): replace the manually mapped backend with the full OSIS + hero_blueprint stack — write the oschema (rootobjects, OTOML types,
@index), regenerate, wire the storage glue, and verify the integration tests still pass. This is where the blueprinting and schema-first scaffolding come in. cm50_app is the worked example for this path.Gate: docs/skills updated; CLI admin removed; full-schema services build green with OSIS backend and tests passing.
Definition of done (none require AI to run):
Plan and status
Migration guide
The how-to lives as skills in hero_skills on the development branch, under
skills/blueprint/migration:hero_server_migration: the schema-driven backend (the serving side).Who is on what (edit this table to claim a service)
Not every service has an owner yet. If you pick one up, edit this table and add your name so we do not double up. Status moves through: not started, merged, backend, frontend, done.
PHASE 1
PHASE 2
How this runs
One service per repository, so several people work at once without colliding. The guide plus this issue are enough to migrate a service by hand with a normal coding setup, no special tooling. Always work against the latest remote development. If a foundation change moves the pattern, the skills are updated to match, so re-read them when you start a service.
[platform] Converge the integration and development branches into one development trunk on the Hero Platformto [platform] migration of repo's on development trunk on the Hero Platformhero_biz Step 1 is done: an out-of-process integration test now drives all 62 business and projects RPC methods as MCP tool calls through hero_router, every method covered, deletes verified. Green and merged to hero_biz development (commit 7f4b32d).
One dependency for others doing Step 1: the test only passes against a hero_router built from development, where the new serving paths (/api/{domain}/rpc, /heroservice.json) are consumed. A router from integration or an older installed build probes a migrated service as 0 methods. So Step 1 tests need a development hero_router, pointed at via HERO_ROUTER_BIN.
Frontend (Step 2) is still pending the shared component styling. Planner is next, same harness.
hero_components dioxus bootstrap css done here:
lhumina_code/hero_components@7a51d5b970Live-verified against a development hero_router. I built the migrated hero_components server, served it through the router, and clicked through the router, proc, AI broker, and voice panes in a real browser. The Bootstrap migration renders correctly in both light and dark themes, the theme toggle works, forms and selects render, and the signal-driven modal that replaced the old Bootstrap JavaScript modal opens with its backdrop and form. No console errors on any pane or interaction.
The only failures were data panes showing non-JSON or 404 responses, and those trace to older installed backends that do not yet serve the new /api/{domain}/rpc contract, not to the styling change. The router panes that hit the new router returned real data, which confirms the frontend data path is correct. Ready for Kristof+Timur to review the Dioxus admin per the Step 2 gate.
@despiegk @timur Wdyt?
hero_biz CRM admin (Step 2 frontend) is built and live-verified on the hero_components
development_mikbranch (commit 9ad9b90, https://forge.ourworld.tf/lhumina_code/hero_components/compare/development...development_mik). It is one typed, schema-driven entity screen covering all eight rootobjects the backend serves (companies, people, opportunities, deals, contacts, instruments, contracts, projects) with list, create, edit, delete and a filter, built inside the shared hero_components shell. Verified over a development hero_router against a hero_biz backend built from development: every pane renders real data, a full create round-trip persists, light and dark, no console errors. It uses only the typed dioxus-bootstrap-css components (no CDN, no Bootstrap JS), enforced by a newmake lintgate. Not merged to development, ready for review.@mik-tf — went through the hero_biz backend on
developmentproperly (pulled it, built + tested it myself, didn't just read it). Confirming the approach is right, plus a few direction notes for the team before Phase 4 fans out.Pilot verified. Builds clean against live
hero_lib+hero_blueprintondevelopment(traditional rpc, no rpc2), the 4 hermetic tests pass,fmt/clippyclean, and the backend lockfile is rpc2-free — the separate-workspace split does its job. The schema-drivenopenrpc_server!+ hand-writtenDBTypedOSIS glue, the in-process test gate, and the MIGRATION.md +osis_storage_backendskill are a solid worked example. Step 1 (the 62-method out-of-process test through a development router) and the Step 2 CRM admin both look like the right shape. Good work.Two things to fix before others follow the guide:
findisn't actually indexed on this path. The indexer-backedfind(typedFindParamsper@indexfield, str/enum/numeric-range filters,OsisIndexer::search, write-through) exists only in the generator (hero_blueprint/crates/generator). The macro path that cm50_app and hero_biz use leavesfindhand-written, and both stub it as a full-tablelist()scan — the indexer is never touched. Direction: fold the indexer-backedfindinto theopenrpc_server!macro, and move the generator tohero_blueprint/_archive/(reference only, so nobody builds on it). Also: indexer-down should be a hard error the service returns (on method calls and at startup), not the current log-and-swallow. Until that lands, the guide/skill should stop presenting the full-scan stub as the pattern.The freezone auth reference is wrong. The skill cites
tenant_boundary.rs/identity_bind.rs— those don't exist in any freezone repo history. The real reference isznzfreezone_code/znzfreezone_backendsrc/auth_middleware.rs+src/rpc_auth.rs. Please fix the citation inosis_storage_backend.Authorization (answering the @timur Wdyt) — most of it already exists; we don't build a new claim system.
users.*,groups.*,roles.add_claim), syntheticusers.<name>/groups.<name>claims, reserved prefixes, and it already injectsX-Hero-Claims/X-Hero-Context/X-Hero-User(seehero_proxy/docs/claims.md). The service's job is to register its claim vocabulary on the proxy and enforce, not to store mappings.herolib_openrpc_authorizemodel: the service doesn't authenticate; it matches injectedX-Hero-Claimsagainst per-method/resource rules (dot-patterns,*allowed; any-claim-matches-any-rule; no claims = trusted internal call).X-Hero-Context= one OSIS context/DB per tenant, the freezone model) — no per-row owner columns; standardize onX-Hero-*and retire freezone's bespokeX-Proxy-*; authorization is just the existingbefore-hook seam used as middleware — the macro stack already exposes per-method before/after hooks, so a service registers abeforehook that matchesX-Hero-Claimsagainst its own rules and rejects. No schema annotations, no scaffolding, no new codegen — it only needed documenting; field-level hiding deferred. Written up now as a newdocs/2_blueprint/4_auth/chapter.Net: the pilot + Step 1/2 are the right foundation. Before Egypt picks up Phase 4, let's land (a) indexer-
findin the macro, so every migrated service inherits real indexed queries instead of the full-scan stub, and (b) apply the documentedbefore-hook authz pattern + per-tenant context wiring. The Phase 4 service split can be planned in parallel.@timur, thanks for the review. Quick recap of what landed since:
The only open item from your two asks is the backend one, the indexed find in the macro. I wrote up the approach plus the design questions for you to confirm before I start: lhumina_code/hero_lib#159
Signed-by: mik-tf mik-tf@noreply.invalid
hero_components Bootstrap cleanup baseline is now merged to
development.Landed via lhumina_code/hero_components#13 as squash commit
62a17f7:dioxus-bootstrap-cssbumped to 0.5.3 inhero_components_app.tools/check-no-raw-bootstrap.mjsnow also catches conditionalclass: if/matchraw component classes.Verified after merge on
development:node tools/check-no-raw-bootstrap.mjs crates/hero_components_app/srccargo +1.96 checkincrates/hero_components_appcargo +1.96 checkincrates/hero_componentsBranch cleanup done: stale Mik branches removed; no active
development_mikbranch remains after merge.Signed-by: mik-tf mik-tf@noreply.invalid
Kimi admin target is merged into hero_components development.
Verification run before merge:
Kimi Step 2 status, corrected and verified over the router.
My earlier note here was unclear and had the wrong premise, so here is the accurate state. The Kimi backend already serves the standard multi-domain OpenRPC contract: the
hero_kimi_serverdaemon exposes three domains (agent, sessions, config) over the router at/hero_kimi/rpc/api/{domain}/rpc, generated from its schemas by the shared macro stack. There was nothing new to build. The confusion was thathero_kimi_web(the separate chat web app) does not expose OpenRPC, while the RPC daemonhero_kimi_serverdoes. The admin pane inhero_components(Sessions, Config, Agent) calls exactly that contract through the router, the same way Biz and Planner do.I verified the whole path end to end against a development router and every admin method passed: sessions list, create, rename, and delete (a created session shows its new title in the list and is gone after delete), config get, config as TOML, usage, and patch, and agent initialize, replay, cancel, plan mode, and YOLO. All returned real data or applied real changes, nothing missing.
The full in-browser render of the admin is currently blocked by a router packaging issue, not by Kimi: the admin shell discovers services through the router, and the renamed router binary plus a fixed bind port stop it from running for that step. Tracked separately in lhumina_code/hero_router#126 . It affects the Biz and Planner admin panes the same way.
So Kimi is now at the same bar as Biz and Planner: backend serving over the router, admin pane merged on development, all admin actions verified end to end. The remaining step is Kristof's review of the Dioxus admin before any old tooling is retired.
Signed-by: mik-tf mik-tf@noreply.invalid
Reorganized into a tracker of short per-repo stories at #313 (the earlier write up here was too document-heavy to work from). Closing in favor of that index.
Signed-by: mik-tf mik-tf@noreply.invalid