nodejs-runtime

name: nodejs-runtime description: Node.js runtime providers, app-executor sidecar, and graph execution API in packages/node and packages/app-executor

Activation

This skill triggers when editing these files:

• packages/node/src/**
• packages/app-executor/bin/**
• packages/app-executor/scripts/**

Keywords: NodeNativeApi, NodeMCPProvider, NodeDatasetProvider, NodeCodeRunner, createProcessor, startDebuggerServer, app-executor, runGraph

You are working on the Node.js runtime layer of Rivet — providers that back ProcessContext, the public execution API, and the Tauri sidecar executor.

Key Files

• packages/node/src/api.ts — createProcessor() and runGraph(); wraps core with Node defaults
• packages/node/src/native/NodeNativeApi.ts — File I/O; exec() intentionally throws "Not Implemented"
• packages/node/src/native/NodeMCPProvider.ts — MCP via @modelcontextprotocol/sdk; create→connect→call→close per request
• packages/node/src/native/NodeDatasetProvider.ts — Extends InMemoryDatasetProvider; write-through with optional .save flag
• packages/node/src/native/NodeCodeRunner.ts — AsyncFunction with injected require, process, fetch, Rivet, context
• packages/node/src/debugger.ts — WebSocket debugger server; partial outputs throttled to 100ms per node
• packages/node/src/index.ts — Re-exports all of @ironclad/rivet-core plus node-specific exports
• packages/app-executor/bin/executor.mts — Sidecar: WebSocket server receiving set-dynamic-data + run messages

Key Concepts

• Provider injection: createProcessor() defaults nativeApi, mcpProvider, codeRunner to Node implementations if not supplied; always sets processor.executor = 'nodejs'
• Plugin env injection: createProcessor() auto-populates pluginEnv from process.env for any plugin config key with pullEnvironmentVariable
• Sidecar execution: app-executor is compiled via esbuild+pkg to native binaries in dist/app-executor-{target}; receives project+settings dynamically over WebSocket
• Dataset persistence: Pass { save: true } to NodeDatasetProvider; every mutation calls save() after the parent method. Use fromProjectFile() to auto-resolve .rivet-data sibling files
• MCP transports: HTTP uses StreamableHTTP with SSE fallback; STDIO spawns subprocess — client lifecycle is per-call (not shared)

Critical Rules

• packages/node/src/index.ts must re-export @ironclad/rivet-core entirely — consumers use @ironclad/rivet-node as their sole import
• New providers must implement the interface from packages/core/src/model/ProcessContext.ts exactly
• NodeCodeRunner uses createRequire(import.meta.url) — do not use bare require; the file is ESM
• app-executor plugins are loaded from appdata paths (~/.local/share/com.ironcladapp.rivet/plugins/{pkg}-{tag}/package) — do not hardcode paths
• Debugger event broadcasting must remain throttled; removing the 100ms partial-output limit causes UI flooding

References

• Patterns: .claude/skills/packages/skill.md

Last Updated: 2026-04-19