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 or URL; light/dark pairs.
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.

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	—

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
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.