refactor: unify event names + centralize them in DEVFRAME_EVENTS / HUB_EVENTS maps - #258
Merged
Conversation
Rename the internal EventEmitter events on the subsystem hosts to the plural subsystem vocabulary already used across every wire name, so the bus lines up with its RPC/broadcast/shared-state counterparts: - dock:activate -> docks:activate - dock:entry:updated -> docks:entry:updated - terminal:session:updated -> terminals:session:updated - message:* -> messages:* - command:* -> commands:* Add a dedicated Hub Events Reference docs page tabling the three event channels (internal node bus, hub: server RPC, devframe: broadcasts and shared state) and their scope/flow. Wire names (hub:*, devframe:*) are public API and stay unchanged.
✅ Deploy Preview for devfra ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Introduce one source-of-truth event map per package and reference it from every call site, so event/broadcast/shared-state/channel names stop living as scattered string literals: - packages/devframe/src/events.ts (DEVFRAME_EVENTS) — agent host bus events, client connection events, and server->client broadcasts; re-exported from devframe/constants. - packages/hub/src/events.ts (HUB_EVENTS) — the docks/terminals/messages/ commands bus events, hub: RPC methods, devframe: broadcasts, shared-state keys, and channels; re-exported from @devframes/hub/constants. Call sites across both packages (plus hub-ui and the messages dev harness) now reference the maps instead of literals. The unavoidable type-position keys (EventEmitter<...> maps, RPC augmentation interfaces) mirror the maps. Document the core devframe channels in the Events Reference and note that the two maps back the page; add an AGENTS.md rule requiring the maps and events.md to move together and forbidding magic event names. Public constant types are preserved (DOCK_RENDERERS_STATE_KEY, FRAME_NAV_CHANNEL, DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPE stay `string`); the snapshot change is purely the additive HUB_EVENTS / DEVFRAME_EVENTS.
antfubot
changed the title
antfu
approved these changes
Aug 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Two related cleanups to how devframe names its events.
1. Unify inconsistent internal event names.
ctx.docks.eventsemitteddock:activatewhile its wire counterpart broadcastsdevframe:docks:activate— the internal bus was the only place using a singular subject. Renamed the internalEventEmitterevents to the plural subsystem vocabulary used everywhere else, so each internal event lines up with its wire counterpart:dock:activate→docks:activate,dock:entry:updated→docks:entry:updatedterminal:session:updated→terminals:session:updatedmessage:*→messages:*,command:*→commands:*2. Centralize every event name in one source-of-truth map per package, so names stop living as scattered string literals ("no magic event names"):
packages/devframe/src/events.ts→DEVFRAME_EVENTS(agent host bus events, client connection events, server→client broadcasts). Re-exported fromdevframe/constants.packages/hub/src/events.ts→HUB_EVENTS(docks/terminals/messages/commands bus events,hub:RPC methods,devframe:broadcasts, shared-state keys, channels). Re-exported from@devframes/hub/constants.Call sites across both packages — plus
@devframes/hub-uiand the messages dev harness — now referenceDEVFRAME_EVENTS.*/HUB_EVENTS.*instead of literals. The only literals left are unavoidable type-position keys (theEventEmitter<…>maps and the RPC augmentation interfaces), which mirror the maps.@devframes/plugin-terminalskeeps a local literal by design — it models the hub bridge structurally and takes no hub dependency.Docs & guardrail
docs/guide/events.md) tables every channel: the hub's three channels (internal node bus,hub:server RPC,devframe:broadcasts/shared state) and the core devframe channels (agent bus, client connection events, broadcasts). Wired into the sidebar under Hub.HUB_EVENTS/DEVFRAME_EVENTSback it, and an AGENTS.md rule now requires the maps and the page to move together and forbids magic event names.Scope & compatibility
Wire names (
hub:*,devframe:*) are public API and unchanged. The internal.eventsnames are@internal. Public constant types are preserved (DOCK_RENDERERS_STATE_KEY,FRAME_NAV_CHANNEL,DEVFRAME_REMOTE_ASSETS_ERROR_MESSAGE_TYPEstaystring), so the tsnapi snapshot delta is purely the additiveHUB_EVENTS/DEVFRAME_EVENTSexports.Verification
pnpm build, fullvitest(104 files / 1163 tests),pnpm knip, docs build, and typecheck fordevframe/@devframes/hub/@devframes/hub-uiall pass; lint clean. (A pre-existingdevframe/utils/get-porttypecheck error in some plugin test utils is unrelated and present on the base branch.)This PR was created with the help of an agent.