feat(core): add WebSocket RPC protocol and browser API client#97
Merged
mgks merged 4 commits intodocmd-io:mainfrom Apr 9, 2026
Merged
feat(core): add WebSocket RPC protocol and browser API client#97mgks merged 4 commits intodocmd-io:mainfrom
mgks merged 4 commits intodocmd-io:mainfrom
Conversation
Plugins can now export `actions` (for WebSocket RPC handlers) and `events` (for fire-and-forget handlers) alongside existing build-time hooks. Also defines PluginModule, ActionContext, and SourceTools types for the plugin API contract.
Action dispatcher routes WebSocket RPC calls and events to plugin handlers with a sandboxed ActionContext. Source-tools translate rendered-output references (block positions, text offsets) back to raw markdown source positions for safe file editing. - Port action-dispatcher.js to TypeScript/ESM with async fs.promises - Port source-tools.js to TypeScript/ESM with async fs.promises - Import createMarkdownProcessor from @docmd/parser (upstream export) - safePath rejects any path traversal outside projectRoot - Export both modules from @docmd/core barrel
The dev server now handles JSON-based WebSocket messages for plugin action calls (RPC) and events alongside the existing live-reload. The browser API (docmd-api.js) provides docmd.call(), docmd.send(), docmd.on(), docmd.afterReload(), and docmd.scheduleReload() for plugin-server communication. Also injects git user info for plugin identity features. Changes: - New file: packages/ui/assets/js/docmd-api.js — browser-side IIFE that manages WebSocket connection, RPC calls with promise-based responses, fire-and-forget events, server event subscriptions, and sessionStorage-backed reload context stashing. Backwards compatible with plain 'reload' string messages. - Modified: packages/core/src/commands/dev.ts — replaced inline live-reload script injection with external docmd-api.js served from /__dev/docmd-api.js route. Added WebSocket message handler that dispatches JSON RPC calls to plugin action handlers via createActionDispatcher. Added getGitDevInfo() helper that reads git config and computes Gravatar URL for dev identity injection.
7 tasks
…er API - Use const for non-reassigned loop variable (prefer-const) - Add comments to empty catch blocks (no-empty) - Declare browser globals for docmd-api.js (no-undef)
Member
|
Merged! WebSocket RPC is now integrated with our native fs.watch file watcher (we replaced chokidar since 0.6.6). Both systems coexist cleanly. 🎉 |
This was referenced Apr 9, 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.
Summary
'reload'string protocoldocmd-api.jsbrowser client withdocmd.call(),docmd.send(),docmd.on(),docmd.afterReload(),docmd.scheduleReload()window.__docmd_dev) for plugin auth features'reload'messagesContext
Part of the plugin API infrastructure discussed in #73. Depends on #95 and #96.
This is the final piece that wires the action dispatcher into the dev server. The browser API replaces the inline live-reload script with a served file at
/__dev/docmd-api.jsthat handles both live-reload and plugin RPC.Wire protocol
Note:
reload: falsein responses — file changes are detected by chokidar which triggers rebuild + broadcastReload, preventing double-reload.Changes
packages/core/src/commands/dev.ts/__dev/route, git identity injectionpackages/ui/assets/js/docmd-api.jsTest plan
callmessage, verifyresponse'reload'string messages still trigger page reload (backwards compat)/__dev/docmd-api.jsis served with correct Content-Typepnpm test