4.node-api.md

title	Node-Side API
navigation	icon i-lucide-server-cog
description	Lookup tables for the node side: DevframeDefinition fields, CLI options, storage scopes, RPC function types, broadcast options, streaming lifecycle, remote assets, the cross-devframe services surface, diagnostics prefixes, and the auth surface.

Lookup tables for a devframe's node side. Each section links the guide page that teaches the concept.

Definition fields

The fields of a DevframeDefinition: Devframe Definition.

Field	Type	Description
id	string	Required. Unique namespaced id (kebab-case); prefixes RPC/dock/MCP-tool names.
name	string	Required. Display name (dock, agent manifests).
version	string	Required. Semver; shown in hub UIs, diagnostics.
packageName	string	Required. npm package (@scope/my-tool).
importMetaUrl	string	Recommended. Pass import.meta.url, the deps resolution base: default resolveFrom for remote assets and declared services.
homepage	string	Required. Homepage/docs URL.
description	string	Required. One-line summary.
icon	string | { light, dark }	Optional Iconify name, image URL, light/dark pairs, etc. See Icon values.
basePath	string	Optional mount-path override. Default / standalone (cli/build), /__<id>/ hosted (vite/embedded).
duplicationStrategy	'warn' | 'silent' | 'throw' | 'duplicate'	Hub reaction when another devframe shares this id. Default 'warn'. See Duplication strategies; standalone adapters ignore it.
capabilities	{ dev?, build? }	Per-runtime feature flags. boolean = whole runtime; object = individual features.
services	DevframeServiceInput[]	Wire services consumed: descriptors ({ package, version?, required?, options? }) imported against the devframe's own deps, or ready definitions. See Cross-Devframe Services.
clientAssets	string | RemoteAssets	Built SPA served as the UI: local dist dir or remote assets. Read by every UI-serving adapter (dev, build, vite, next, hub).
rpc	{ snapshot?: (string | { method, inputs })[] }	RPC config. rpc.snapshot opts an RPC this devframe doesn't own into the static dump. Bare method id bakes the no-arg call; { method, inputs } bakes one record per argument-tuple (inputs = tuples or async (ctx) => tuples). First tuple = fallback.
setup	(ctx, info?) => void | Promise<void>	Required. Server-side entry point, run in every runtime. Optional 2nd arg carries runtime metadata, notably parsed CLI flags under createCac.
cli	DevframeCliOptions	CLI adapter defaults. See CLI options.

Icon values

The icon field, and every dock entry, command, and terminal icon, accept the same string forms. A { light, dark } pair picks the matching variant per active color scheme, and each side takes any of these forms:

Form	Example	Rendered as
Iconify name	ph:gauge-duotone, logos:nuxt-icon	the collection:icon glyph, fetched from Iconify as inline SVG
Image URL	/icons/logo.svg, https://example.com/logo.png	an <img>; relative URLs resolve against the supplying hub
Data URL	data:image/svg+xml,%3Csvg…%3E	an inline <img> from the embedded data
SVG mask	mask:/icons/logo.svg, mask:data:image/svg+xml,%3Csvg…%3E	an alpha mask tinted with currentColor, following the surrounding text color
Light/dark pair	{ light: './logo-light.svg', dark: './logo-dark.svg' }	the variant matching the active color scheme; each side is any string form above

The reference hub UI and terminal SPA render mask: icons with the surrounding text color, preserving the image's shape and opacity, so a bundled monochrome SVG follows the dock's foreground color through selected and dimmed states. For a bundled SVG, use `mask:data:image/svg+xml,${encodeURIComponent(svg)}`. A mask produces one color; use an ordinary image URL for multicolor artwork. Relative mask URLs on dock entries resolve against the supplying hub's URL. Custom hub UI providers implement this string convention in their own icon renderer.

CLI options

The cli field's DevframeCliOptions: CLI options.

Field	Type	Description
command	string	Binary name in --help. Default: the id.
port	number	Preferred dev-server port.
portRange	[number, number]	Port scan range (get-port-please).
random	boolean	Prefer a random open port.
host	string	Default bind host.
open	boolean | string	true = origin, string = a path, false = off (--open/--no-open). With auth, embeds the OTP.
auth	boolean	Disable WS trust flow when localhost-only, single-user. Default true.
configure	(cli: CAC) => void	Contribute flags/commands before createCac's configureCli.

Storage scopes

The three classes ctx.host.getStorageDir(scope) places persisted state in: Storage scopes.

Scope	Placement	For
workspace	committable, <workspaceRoot>/.devframe/	team-shared: saved presets, config
project	per-checkout, <cwd>/node_modules/.<app>/devframe/	caches, personal settings
global	per-user, ~/.<app>/devframe/	auth tokens, machine-wide prefs

RPC function types

The type field of defineRpcFunction: RPC.

Type	Description	Cached	Static Dump
query	Read operation that can change over time.	Opt-in via cacheable	Manual (declare dump)
static	Data that never changes for a given input.	Indefinitely	Automatic
action	Mutation with side effects.	Never	Never
event	Fire-and-forget; no response.	Never	Never

Broadcast options

The options of rpc.broadcast: Broadcasting.

Option	Type	Description
method	browser-side RPC name	Browser-side function to call.
args	any[]	Arguments for the browser-side function.
optional	boolean	Don't throw if no RPC client is listening.
event	boolean	Fire-and-forget.
filter	(client) => boolean	Skip specific RPC clients.

Streaming lifecycle

How each lifecycle event lands on both sides of a streaming channel: Streaming.

Event	Node side	Browser side
stream.close() / stream.error(err)	broadcasts end	for await resolves or throws
reader.cancel()	aborts stream.signal on last-subscriber cancel	for await ends
WS disconnects	aborts stream.signal on last-subscriber drop	reader survives, resubscribes on re-trust
chat panel closes	cancels upstream	none

Remote assets options

The fields of a RemoteAssets source for clientAssets and hostStatic: Remote assets.

Field	Purpose
package	npm package with the built assets.
version	Exact version, usually your pkg.version.
resolveFrom	Local-path resolution base. Defaults to importMetaUrl; null skips to cache + CDN.
path	Subpath the assets live under (default dist).
provider	'jsdelivr' (default), 'unpkg', or a custom provider (internal mirror).
offline	true serves only from local install or cache, never network.

DevframeServicesHost

The methods on ctx.services: Cross-Devframe Services.

Method	Signature	Role
provide	(id, service) => revoke	Publish an in-process service under a namespaced id. Throws DF0037 if the id is taken.
get	(id) => service | undefined	The service currently provided under id (augmented type, else unknown).
has	(id) => boolean	Whether a service is provided under id.
whenAvailable	(id, cb) => unsubscribe	Run cb as soon as the service exists (now if provided, else on provide), and re-fire on revoke/re-provide.
keys	() => string[]	Ids of every currently-provided service.
install	(input, options?) => Promise<api | undefined>	Install a wire service at runtime (the dynamic escape hatch; the common path is declarative). options.resolveFrom is the descriptor's resolution base.
ready	() => Promise<void>	Internal. Construct every queued wire service before any setup runs. Adapters call it; application code uses declarative services.

Service tiers

The two tiers a service can take: Cross-Devframe Services.

Tier	Shared how	Registers RPC	Advertised to clients
In-process service (provide/get)	live object, node side only	No	No
Wire service (install / declarative services)	npm package, node API + RPC	Yes, under its scope	Yes, via devframe:services shared state

Wire-service definition fields

The fields of a DevframeServiceDefinition returned by a service package's create<X>Service factory: Shipping a wire service.

Field	Type	Description
package	string	Required. npm package name, also its registry key (ctx.services.has(pkg)).
version	string	Required. Semver; advertised to clients, checked against declared ranges.
scope	string	Required. RPC namespace its functions register under (e.g. devframes:service:open); setup gets a context pre-scoped to it.
meta	Record<string, unknown>	Extra advertised metadata (feature flags, defaults). Must be JSON-serializable.
options	Options	This instance's own option set, baked in by its factory; joins the merge.
mergeOptions	(sets: Options[]) => Options	Merge multiple installers' option sets. Default: shallow, later wins.
setup	(ctx, info) => api	Required. Register RPC on the pre-scoped context; return the node API served from ctx.services.get(package).

Wire-service descriptor fields

The declarative reference form on DevframeDefinition.services / initHub({ services }): Declaring services.

Field	Type	Description
package	string	Required. npm package name; its default export is the factory the host imports.
version	string	Accepted semver range. Unsatisfied warns (DF0069), or throws (DF0068) when required.
required	boolean	Fail hard on a missing package (DF0067) or unsatisfied range. Default false: a missing service is skipped and clients see has() === false.
options	Options	Option set this installer contributes to the merge.

Advertised service meta

Each installed service's entry in the devframe:services shared state, mirrored to RPC clients as rpc.services: Feature-detecting on the RPC client.

Field	Description
package	npm package name, the registry key.
version	Installed version of the service.
scope	RPC namespace its functions live under.
meta	Extra service-declared metadata.

Diagnostic code prefixes

Prefixes in use across the ecosystem: Structured Diagnostics.

Prefix	Owner
DF	devframe
DTK	@vitejs/devtools (Vite-specific)
RDDT	@vitejs/devtools-rolldown
VDT	@vitejs/devtools-vite (reserved)

Auth methods

The wire-level RPC methods of the trust handshake: Security.

RPC method	Direction	Shape
anonymous:devframe:auth	client → server	{ authToken, ua, origin } → { isTrusted }: re-authenticate a stored token
anonymous:devframe:auth:exchange	client → server	{ code, ua, origin } → { authToken | null }: exchange a code for a token
anonymous:devframe:auth:request-code	client → server	{ ua, origin, reissue? } → print the code banner in the server terminal (reissue: true rotates the code first)
devframe:auth:revoke	client → server	self-revoke the caller's own token
devframe:auth:revoked	server → client	event: token revoked

Node auth primitives

The building blocks in devframe/node/auth: Security.

Function	Role
getTempAuthCode() / refreshTempAuthCode()	read / rotate the one-time code
exchangeTempAuthCode(code, session, { ua, origin }, storage)	verify a code, mint + store the token, trust the session, return it (or null)
verifyAuthToken(token, session, storage)	trust a session presenting a known token
buildOtpAuthUrl(origin, code?)	build a magic-link URL embedding the code
revokeAuthToken(context, storage, token)	delete a token and disconnect sessions using it

MCP CLI commands

The agent-facing CLI surface: Agent-Native Devframe.

Command	Description
<your-app> mcp	Start the MCP server on stdio.
<your-app> dev --mcp	Serve the agent-consumable API on /__mcp.
devframe connect	Discover running devframes and proxy their tools; see MCP adapter.