hanzo

Overview ¶

Command hanzo is the unified Hanzo Go binary, dispatched by subcommand.

hanzo                 list subcommands
hanzo --help          list subcommands
hanzo <svc> [flags]   serve exactly one subsystem (iam, kms, commerce,
                      gateway, ai, base, vfs, o11y, …)
hanzo cloud [flags]   serve the full unified surface (all enabled
                      subsystems mounted into one zip.App / one listener)

One binary. Many subsystems. The subcommand selects WHICH subsystem(s) serve this process; the same artifact is every standalone service AND the fused cloud control plane.

Design — one mechanism, not many. The subsystem set is the explicit list apps.Wire() returns — []cloud.MountSpec in mount order (kms first-tier, iam 50, commerce 100, …, ai last), no init()-registry. A subcommand is just a *selection* over that slice:

• `hanzo <svc>` ⇒ cloud.Serve(specs, []string{svc}); MountAll mounts only it.
• `hanzo cloud` ⇒ cloud.Serve(specs, nil); cfg.Enable per --enable (empty = all).

Both paths run the identical compose root (BuildDeps → zip.App → health contract → MountAll → graceful Listen) — that body lives once in cloud.Serve and is shared with cmd/cloud. No subcommand duplicates boot logic.

The single exception is `hanzo iam`. The registry's iam Mount (pkg/iam, order 50) wraps the Beego handler under /v1/iam/* for the fused surface; the FULL standalone IAM — login UI at /, all ~150 routes at root, LDAP + RADIUS listeners — is iamserver.Run(), the body of the legacy iamd main(). `hanzo iam` runs that, so the standalone identity provider is byte-for-byte what iamd shipped. See the iam case in dispatch().

THE BEEGO CRUX (and why this binary does not init-panic). iam imports github.com/hanzoai/beego/v2; that fork carries process-global state (web.BeeApp singleton, ORM model registry, logger registration). The fear is that importing iam alongside the other subsystems collides at package load regardless of subcommand. It does not, for two reasons this codebase already established:

1. iam's ~150 route registrations and ORM table creation are NOT at package init() — they live inside iamserver.Init() / routers.InitAPI() / object.CreateTables(), which run only when iam actually serves. Blank-importing the package is inert: no router, no ORM, no listener.
2. There is exactly ONE Beego v2 import path in the graph (hanzoai/beego/v2), so there is exactly one Beego global to initialize, and it is initialized lazily by whichever path serves iam. (visor, the other Beego service, pins the *v1* fork github.com/beego/beego and is intentionally NOT linked here — two Beego majors in one binary is the collision to avoid, so we don't.)

The proof is mechanical: the existing cmd/cloud binary already links this same graph (iam Beego v2 + kms + commerce + gateway + …) and builds + boots. cmd/hanzo links the same set plus iamserver for the standalone path; nothing new collides.