@bonsae/nrg 0.19.0 → 0.20.0

package/types/test-server-integration.d.ts

@@ -0,0 +1,523 @@
+// Generated by dts-bundle-generator v9.5.1
+
+import { SchemaOptions, Static, TObject, TOptional, TProperties, TSchema, TString } from '@sinclair/typebox';
+import { EventEmitter } from 'events';
+import { Express as Express$1 } from 'express';
+import { Http2ServerRequest } from 'http2';
+
+interface NodeRedRuntimeSettings {
+	userDir?: string;
+	nodesDir?: string | string[];
+	flowFile?: string;
+	flowFilePretty?: boolean;
+	credentialSecret?: string | false;
+	requireHttps?: boolean;
+	https?: {
+		key: string;
+		cert: string;
+	} | (() => Promise<{
+		key: string;
+		cert: string;
+	}> | {
+		key: string;
+		cert: string;
+	});
+	httpsRefreshInterval?: number;
+	httpAdminRoot?: string;
+	httpNodeRoot?: string;
+	httpNodeCors?: {
+		origin: string;
+		methods: string;
+	};
+	httpStatic?: string | {
+		path: string;
+		root: string;
+	}[];
+	httpStaticRoot?: string;
+	httpAdminMiddleware?: (req: unknown, res: unknown, next: () => void) => void;
+	httpNodeMiddleware?: (req: unknown, res: unknown, next: () => void) => void;
+	httpServerOptions?: Record<string, unknown>;
+	adminAuth?: {
+		type?: "credentials" | "strategy";
+		users?: {
+			username: string;
+			password: string;
+			permissions?: string | string[];
+		}[];
+		default?: {
+			permissions?: string | string[];
+		};
+		tokens?: (token: string) => Promise<{
+			user: string;
+			permissions: string | string[];
+		} | null>;
+		tokenHeader: "string";
+		sessionExpiryTime?: number;
+		[key: string]: unknown;
+	};
+	httpNodeAuth?: {
+		user?: string;
+		pass?: string;
+	};
+	httpStaticAuth?: {
+		user?: string;
+		pass?: string;
+	};
+	lang?: "en-US" | "de" | "es-ES" | "fr" | "ko" | "pt-BR" | "ru" | "ja" | "zh-CN" | "zh-TW";
+	diagnostics?: {
+		enabled?: boolean;
+		ui?: boolean;
+	};
+	runtimeState?: {
+		enabled?: boolean;
+		ui?: boolean;
+	};
+	disableEditor?: boolean;
+	editorTheme?: {
+		page?: {
+			title?: string;
+			favicon?: string;
+			css?: string | string[];
+			scripts?: string | string[];
+		};
+		header?: {
+			title?: string;
+			image?: string;
+			url?: string;
+		};
+		deployButton?: {
+			type?: "simple" | "default";
+			label?: string;
+			icon?: string;
+		};
+		menu?: {
+			"menu-item-import-library"?: boolean;
+			"menu-item-export-library"?: boolean;
+			"menu-item-keyboard-shortcuts"?: boolean;
+			"menu-item-help"?: {
+				label?: string;
+				url?: string;
+			};
+			[menuItem: string]: boolean | {
+				label?: string;
+				url?: string;
+			} | undefined;
+		};
+		userMenu?: boolean;
+		login?: {
+			image?: string;
+		};
+		logout?: {
+			redirect?: string;
+		};
+		palette?: {
+			catalogues?: string[];
+			categories?: string[];
+			theme?: {
+				category: string;
+				type: string;
+				color: string;
+			}[];
+		};
+		projects?: {
+			enabled?: boolean;
+			workflow?: {
+				mode: "manual" | "auto";
+			};
+		};
+		codeEditor?: {
+			lib?: "monaco" | "ace";
+			options?: Record<string, unknown>;
+		};
+		mermaid?: {
+			theme?: string;
+		};
+		tours?: boolean;
+		theme?: string;
+		[key: string]: unknown;
+	};
+	contextStorage?: {
+		default?: {
+			module?: "memory" | "localfilesystem" | object;
+			config?: Record<string, unknown>;
+		};
+		[store: string]: {
+			module?: "memory" | "localfilesystem" | object;
+			config?: Record<string, unknown>;
+		} | undefined;
+	};
+	exportGlobalContextKeys?: boolean;
+	logging?: {
+		console?: {
+			level?: "fatal" | "error" | "warn" | "info" | "debug" | "trace" | "off";
+			metrics?: boolean;
+			audit?: boolean;
+		};
+	};
+	fileWorkingDirectory?: string;
+	functionExternalModules?: boolean;
+	functionGlobalContext?: Record<string, unknown>;
+	nodeMessageBufferMaxLength?: number;
+	functionTimeout?: number;
+	externalModules?: {
+		autoInstall?: boolean;
+		autoInstallRetry?: number;
+		palette?: {
+			allowInstall?: boolean;
+			allowUpdate?: boolean;
+			allowUpload?: boolean;
+			allowList?: string[];
+			denyList?: string[];
+			allowUpdateList?: string[];
+			denyUpdateList?: string[];
+		};
+		modules?: {
+			allowInstall?: boolean;
+			allowList?: string[];
+			denyList?: string[];
+		};
+	};
+	execMaxBufferSize?: number;
+	debugMaxLength?: number;
+	debugUseColors?: boolean;
+	httpRequestTimeout?: number;
+	mqttReconnectTime?: number;
+	serialReconnectTime?: number;
+	socketReconnectTime?: number;
+	socketTimeout?: number;
+	tcpMsgQueueSize?: number;
+	inboundWebSocketTimeout?: number;
+	tlsConfigDisableLocalFiles?: boolean;
+	webSocketNodeVerifyClient?: (info: {
+		origin: string;
+		req: Http2ServerRequest;
+		secure: boolean;
+	}) => boolean;
+	apiMaxLength?: string;
+	[key: string]: unknown;
+}
+declare const NodeConfigSchema: import("@sinclair/typebox").TObject<{
+	id: import("@sinclair/typebox").TString;
+	type: import("@sinclair/typebox").TString;
+	name: import("@sinclair/typebox").TString;
+	z: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+interface NodeRedLog {
+	info(msg: any): void;
+	warn(msg: any): void;
+	error(msg: any, error?: any): void;
+	debug(msg: any): void;
+	trace(msg: any): void;
+	log(msg: {
+		level: number;
+		msg: string;
+	}): void;
+	metric(): boolean;
+	audit(msg: Record<string, any>, req?: any): void;
+	addHandler(handler: (msg: any) => void): void;
+	removeHandler(handler: (msg: any) => void): void;
+	FATAL: 10;
+	ERROR: 20;
+	WARN: 30;
+	INFO: 40;
+	DEBUG: 50;
+	TRACE: 60;
+	AUDIT: 98;
+	METRIC: 99;
+}
+interface NodeRedNode {
+	id: string;
+	type: string;
+	name?: string;
+	z?: string;
+	x: number;
+	y: number;
+	g?: string;
+	wires: string[][];
+	credentials: any;
+	_node?: INode;
+	send(msg: any): void;
+	receive(msg: any): void;
+	status(status: string | {
+		fill?: string;
+		shape?: string;
+		text?: string;
+	}): void;
+	updateWires(wires: string[][]): void;
+	on(event: string, callback: (...args: any[]) => void): void;
+	log(msg: any): void;
+	warn(msg: any): void;
+	error(msg: any, errorMsg?: any): void;
+	context(): NodeRedNodeContext;
+	[key: string]: any;
+}
+interface NodeRedNodeContext extends NodeRedContextStore {
+	flow: NodeRedContextStore;
+	global: NodeRedContextStore;
+}
+interface NodeRedNodes {
+	registerType(type: string, constructor: any, opts?: any): void;
+	getNode(id: string): (NodeRedNode & {
+		_node?: INode;
+	}) | undefined;
+	createNode(node: NodeRedNode, config: Record<string, any>): void;
+	getCredentials(id: string): Record<string, any> | undefined;
+	/** Merge credentials into a node's stored credential set (runtime API). */
+	addCredentials(id: string, credentials: Record<string, any>): void;
+	eachNode(callback: (node: any) => void): void;
+	getType(type: string): any;
+	getNodeInfo(type: string): any;
+	getNodeList(filter?: any): any[];
+	getModuleInfo(module: string): any;
+	installModule(module: string, version?: string): Promise<any>;
+	uninstallModule(module: string): Promise<any>;
+	enableNode(id: string): Promise<any>;
+	disableNode(id: string): Promise<any>;
+}
+interface NodeRedUtil {
+	evaluateNodeProperty(value: any, type: string, node: any, msg: Record<string, any> | undefined, callback: (err: Error | null, result: any) => void): void;
+	generateId(): string;
+	cloneMessage<T = any>(msg: T): T;
+	ensureString(o: any): string;
+	ensureBuffer(o: any): Buffer;
+	compareObjects(obj1: any, obj2: any): boolean;
+	getMessageProperty(msg: any, expr: string): any;
+	setMessageProperty(msg: any, prop: string, value: any, createMissing?: boolean): void;
+	getObjectProperty(obj: any, expr: string): any;
+	setObjectProperty(obj: any, prop: string, value: any, createMissing?: boolean): void;
+	normalisePropertyExpression(str: string, msg?: any, toString?: boolean): string[];
+	normaliseNodeTypeName(name: string): string;
+	prepareJSONataExpression(value: string, node: any): any;
+	evaluateJSONataExpression(expr: any, msg: any, callback: (err: Error | null, result: any) => void): void;
+	parseContextStore(key: string): {
+		store: string | undefined;
+		key: string;
+	};
+	getSetting(node: any, name: string, flow?: any): any;
+	encodeObject(obj: any): any;
+}
+interface NodeRedHooks {
+	add(hookId: string, callback: (event: any) => void | Promise<void>): void;
+	remove(hookId: string): void;
+	trigger(hookId: string, event: any, callback?: (err?: Error) => void): void | Promise<void>;
+	has(hookId: string): boolean;
+	clear(): void;
+}
+type NodeRedExpressApp = Express;
+interface RED {
+	/** Internationalization function */
+	_(key: string, substitutions?: Record<string, string>): string;
+	/** Logging API */
+	log: NodeRedLog;
+	/** Node registry and management */
+	nodes: NodeRedNodes;
+	/** Utility functions */
+	util: NodeRedUtil;
+	/** Hook system for message lifecycle and module events */
+	hooks: NodeRedHooks;
+	/** Runtime event emitter */
+	events: EventEmitter;
+	/** Express app for admin HTTP endpoints */
+	httpAdmin: NodeRedExpressApp;
+	/** Express app for node HTTP endpoints */
+	httpNode: NodeRedExpressApp;
+	/** Runtime settings (user-provided settings plus node-registered settings) */
+	settings: NodeRedRuntimeSettings & Record<string, any>;
+	/** Node-RED version string */
+	version(): string;
+}
+interface NodeRedContextStore {
+	get(key: string, store: string | undefined, callback: (err: Error | null, value: any) => void): void;
+	set(key: string, value: any, store: string | undefined, callback: (err: Error | null) => void): void;
+	keys(store: string | undefined, callback: (err: Error | null, keys: string[]) => void): void;
+}
+type Schema<T extends TProperties = TProperties> = TObject<T>;
+interface NodeContextStore {
+	get<T = any>(key: string): Promise<T>;
+	set<T = any>(key: string, value: T): Promise<void>;
+	keys(): Promise<string[]>;
+}
+interface NodeConstructor<T = any, TConfig = any, TCredentials = any> {
+	readonly type: string;
+	readonly category: string;
+	readonly color?: string;
+	readonly align?: "left" | "right";
+	readonly inputs?: number;
+	readonly outputs?: number;
+	readonly configSchema?: Schema;
+	readonly credentialsSchema?: Schema;
+	readonly settingsSchema?: Schema;
+	readonly inputSchema?: Schema;
+	readonly outputsSchema?: TSchema | TSchema[] | Record<string, TSchema>;
+	readonly validateInput?: boolean;
+	readonly validateOutput?: boolean;
+	readonly name: string;
+	registered?(RED: RED): void | Promise<void>;
+	register(RED: RED): void | Promise<void>;
+	validateSettings(RED: RED): void;
+	new (RED: RED, node: NodeRedNode, config: NodeConfig<TConfig>, credentials: NodeCredentials<TCredentials>): T;
+}
+type NodeConfig<TConfig = any> = TConfig & Static<typeof NodeConfigSchema>;
+type NodeCredentials<TCredentials = any> = TCredentials;
+interface INode<TConfig = any, TCredentials = any, TSettings = any> {
+	readonly config: NodeConfig<TConfig>;
+	readonly id: string;
+	readonly name: string | undefined;
+	readonly z: string | undefined;
+	readonly credentials: NodeCredentials<TCredentials> | undefined;
+	readonly settings: TSettings;
+	i18n(key: string, substitutions?: Record<string, string>): string;
+	setTimeout(fn: () => void, ms: number): NodeJS.Timeout;
+	setInterval(fn: () => void, ms: number): NodeJS.Timeout;
+	clearTimeout(timer: NodeJS.Timeout): void;
+	clearInterval(interval: NodeJS.Timeout): void;
+	on(event: string, callback: (...args: any[]) => void): void;
+	log(msg: any): void;
+	warn(message: string): void;
+	error(message: string, msg?: any): void;
+	created?(): void | Promise<void>;
+	closed?(removed?: boolean): void | Promise<void>;
+}
+type Channel = "sent" | "received";
+declare class Recorder {
+	#private;
+	recordSent(id: string, port: number, msg: unknown): void;
+	recordReceived(id: string | undefined, msg: unknown): void;
+	/** Snapshot of all messages on a channel for a node (optionally one port). */
+	snapshot(channel: Channel, id: string, port?: number): unknown[];
+	/** Resolve the message at `index` on a channel, awaiting it if not yet seen. */
+	next(channel: Channel, id: string, port: number | undefined, index: number, timeoutMs: number): Promise<unknown>;
+	clear(): void;
+}
+interface NodeContext {
+	node: NodeContextStore;
+	flow: NodeContextStore;
+	global: NodeContextStore;
+}
+export interface AddNodeOptions {
+	/** Override the generated node id. */
+	id?: string;
+	/** Node name (the `name` field). */
+	name?: string;
+	/** Credentials for the node (stored by the runtime, exposed as `this.credentials`). */
+	credentials?: Record<string, unknown>;
+}
+export interface ReadOptions {
+	/** Reject if no message arrives within this many ms. @default 5000 */
+	timeout?: number;
+}
+/**
+ * A handle to one node in a deployed flow. Wraps a generated id; the live
+ * instance lives inside the runtime, so harness methods (`receive`/`read`/…)
+ * never collide with the node's own methods.
+ */
+export declare class NodeRef {
+	#private;
+	readonly id: string;
+	readonly type: string;
+	readonly isConfig: boolean;
+	readonly name: string;
+	readonly config: Record<string, unknown>;
+	readonly credentials?: Record<string, unknown>;
+	readonly wires: string[][];
+	constructor(flow: Flow, type: string, isConfig: boolean, config: Record<string, unknown>, opts: AddNodeOptions);
+	/** Wire this node's output `port` to `target`'s input. */
+	wire(target: NodeRef, port?: number): this;
+	/** Deliver a message to this node's input (Node-RED's upstream path). */
+	receive(msg: unknown): Promise<void>;
+	/** Snapshot of everything this node has emitted (optionally one port). */
+	sent(port?: number): unknown[];
+	/** Snapshot of everything delivered to this node's input. */
+	received(port?: number): unknown[];
+	/**
+	 * Promise-based access to this node's context stores (`node` / `flow` /
+	 * `global`) — preset values before `receive`, and assert them afterward.
+	 */
+	get context(): NodeContext;
+	/**
+	 * Consume the next un-read message this node emitted (FIFO cursor), awaiting
+	 * it if not yet sent. Call repeatedly to walk multiple emissions.
+	 */
+	read(port?: number, opts?: ReadOptions): Promise<unknown>;
+}
+/**
+ * Builds a flow from nrg node classes and deploys it into a running runtime.
+ * Use `addNode` for every node — config nodes included.
+ */
+export declare class Flow {
+	#private;
+	readonly recorder: Recorder;
+	constructor(RED: NodeRedApi, recorder: Recorder);
+	/** Add any node — regular or config (detected via `category === "config"`). */
+	addNode(Cls: NodeConstructor, config?: Record<string, unknown>, opts?: AddNodeOptions): NodeRef;
+	/** Build the flow JSON and deploy it; resolves once the flow has started. */
+	deploy(): Promise<void>;
+	/** Drop the built nodes and clear captured messages (reset between tests). */
+	clear(): Promise<void>;
+	runtimeNode(id: string): RuntimeNode | null;
+}
+export interface StartRuntimeOptions {
+	/** Node classes (IONode / ConfigNode subclasses) to register in the runtime. */
+	nodes: NodeConstructor[];
+	/** Extra Node-RED settings merged over the headless defaults. */
+	settings?: Record<string, unknown>;
+}
+/**
+ * Boot a real, in-process Node-RED runtime with the given node types
+ * registered. One runtime per test file (the runtime is a process-wide
+ * singleton); each test deploys a flow into it and `flow.clear()`s between.
+ */
+export declare function startRuntime(options: StartRuntimeOptions): Promise<Runtime>;
+export declare class Runtime {
+	#private;
+	constructor(RED: NodeRedApi, server: http.Server, userDir: string, recorder: Recorder);
+	/** Start a fresh flow to build, deploy, drive and inspect. */
+	flow(): Flow;
+	/** Stop Node-RED, close the server and remove the temp user dir. */
+	stop(): Promise<void>;
+}
+interface NodeRedApi {
+	init(server: http.Server, settings: Record<string, unknown>): void;
+	start(): Promise<void>;
+	stop(): Promise<void>;
+	hooks: {
+		add(name: "onReceive", fn: (event: {
+			destination?: {
+				id?: string;
+			};
+			msg: unknown;
+		}) => void): void;
+	};
+	nodes: {
+		getNode(id: string): RuntimeNode | null;
+	};
+	events: {
+		on(event: string, fn: (...args: unknown[]) => void): void;
+		removeListener(event: string, fn: (...args: unknown[]) => void): void;
+	};
+	runtime: {
+		flows: {
+			setFlows(opts: {
+				flows: {
+					flows: unknown[];
+				};
+				deploymentType?: string;
+			}): Promise<{
+				rev: string;
+			}>;
+		};
+	};
+}
+interface RuntimeNodeContext extends NodeRedContextStore {
+	flow: NodeRedContextStore;
+	global: NodeRedContextStore;
+}
+interface RuntimeNode {
+	id: string;
+	type: string;
+	receive(msg: unknown): void;
+	send(msg: unknown): void;
+	context(): RuntimeNodeContext;
+}
+
+export {};

package/types/test-server-unit.d.ts

@@ -203,6 +203,11 @@ declare const NodeConfigSchema: import("@sinclair/typebox").TObject<{
 	z: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 type Schema<T extends TProperties = TProperties> = TObject<T>;
+interface NodeContextStore {
+	get<T = any>(key: string): Promise<T>;
+	set<T = any>(key: string, value: T): Promise<void>;
+	keys(): Promise<string[]>;
+}
 interface NodeConstructor<T = any, TConfig = any, TCredentials = any> {
 	readonly type: string;
 	readonly category: string;
@@ -409,6 +414,13 @@ interface TestNodeHelpers<TInput = any, TOutput = any> {
 	logged(level?: "info" | "warn" | "error" | "debug"): string[];
 	warned(): string[];
 	errored(): string[];
+	/** Promise-based access to the node's context stores (node / flow / global). */
+	context: TestNodeContext;
+}
+interface TestNodeContext {
+	node: NodeContextStore;
+	flow?: NodeContextStore;
+	global: NodeContextStore;
 }
 interface CreateNodeResult<T> {
 	node: T & TestNodeHelpers<ExtractInput<T>, ExtractOutput<T>>;

package/types/vite.d.ts

@@ -80,15 +80,6 @@ export interface NodeRedLauncherOptions {
 export interface ServerOptions {
 	/** Options for the Node-RED dev server launcher. */
 	nodeRed?: NodeRedLauncherOptions;
-	/**
-	 * URL-safe path slug the dev server mounts the Node-RED editor under, so
-	 * several `nrg dev` instances can be told apart by path (e.g. behind a
-	 * shared reverse proxy) — the editor is served at
-	 * `http://host:port/<slug>/`. Must match `/^[a-z0-9]+(?:-[a-z0-9]+)*$/`;
-	 * an invalid value is rejected rather than rewritten.
-	 * @default the slugified project folder name
-	 */
-	slug?: string;
 }
 /**
  * Options for building the distributable Node-RED package.
@@ -111,7 +102,7 @@ export interface BuildOptions {
  * `build` for the production bundle.
  */
 export interface NrgPluginOptions {
-	/** Dev server options (Node-RED launcher, editor path slug). */
+	/** Dev server options (Node-RED launcher). */
 	server?: ServerOptions;
 	/** Production build options (output dir, server/client bundles, copies). */
 	build?: BuildOptions;
@@ -177,10 +168,6 @@ export interface NodeRedLauncher {
 	cleanup(): void;
 	flushLogs(): void;
 	readonly preferredPort: number;
-	/** URL-safe path slug the editor is mounted under (empty for root). */
-	readonly slug: string;
-	/** Path prefix derived from the slug — `/<slug>/`, or `/` when no slug. */
-	readonly basePath: string;
 	readonly restartDelay: number;
 	readonly pid: number | null;
 }