@bonsae/nrg 0.18.5 → 0.19.0

package/types/shims/schema-options.d.ts

@@ -1,11 +1,24 @@
-export interface NrgSchemaExtensions {
-  format?: "node-id" | "flow-id" | "topic-path" | (string & {});
-  exportable?: boolean;
-  "x-nrg-node-type"?: string;
-  "x-nrg-form"?: {
-    icon?: string;
-    typedInputTypes?: string[];
-    editorLanguage?: string;
-    toggle?: boolean;
-  };
+/**
+ * NRG's JSON Schema vocabulary — the custom keywords the server emits onto
+ * serialized schemas and the client consumes for form rendering and
+ * validation. Shared at the core root (like brands.ts) so both planes derive
+ * from one definition instead of drifting copies.
+ */
+export interface JsonSchemaObjectExtensions {
+    format?: "node-id" | "flow-id" | "topic-path" | (string & {});
+    /** expose this settings property to the editor via RED.settings */
+    exportable?: boolean;
+    /** set by SchemaType.NodeRef — the referenced config node type */
+    "x-nrg-node-type"?: string;
+    /** set by SchemaType.TypedInput — marks a TypedInput value/type pair */
+    "x-nrg-typed-input"?: boolean;
+    /** set by markNonValidatable — ajv skips this property */
+    "x-nrg-skip-validation"?: boolean;
+    /** form rendering hints consumed by the auto-generated editor form */
+    "x-nrg-form"?: {
+        icon?: string;
+        typedInputTypes?: string[];
+        editorLanguage?: string;
+        toggle?: boolean;
+    };
 }

package/types/shims/typebox.d.ts

@@ -2,9 +2,9 @@
 // TypeScript module augmentation (declare module) to work correctly.
 // Without it, the file is treated as a global script and the
 // augmentation silently fails.
-import type { NrgSchemaExtensions } from "./schema-options";
+import type { JsonSchemaObjectExtensions } from "./schema-options";
 
 declare module "@sinclair/typebox" {
   // eslint-disable-next-line @typescript-eslint/no-empty-object-type
-  interface SchemaOptions extends NrgSchemaExtensions {}
+  interface SchemaOptions extends JsonSchemaObjectExtensions {}
 }

package/types/test-client-component.d.ts

@@ -1,55 +1,36 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { SchemaOptions, Static, TSchema } from '@sinclair/typebox';
+import { Static, TSchema } from '@sinclair/typebox';
+import { SchemaObject } from 'ajv';
 import { App } from 'vue';
 
-export interface MockEditor {
-	getValue(): string;
-	setValue(val: string): void;
-	getSession(): {
-		on(event: string, cb: (...args: any[]) => any): void;
-	};
-	focus(): void;
-	destroy(): void;
-	saveView(): void;
-	restoreView(): void;
-}
-export interface MockRED {
-	_(key: string): string;
-	editor: {
-		createEditor(options: any): MockEditor;
-		prepareConfigNodeSelect(...args: any[]): void;
-		validateNode(...args: any[]): boolean;
-	};
-	tray: {
-		show(...args: any[]): void;
-		close(): void;
-	};
-	popover: {
-		tooltip(...args: any[]): {
-			delete(): void;
-			setAction(...args: any[]): void;
-		};
-	};
-	nodes: {
-		registerType(...args: any[]): void;
-		node(...args: any[]): null;
-		dirty(...args: any[]): boolean;
-	};
-	events: {
-		on(...args: any[]): void;
-		off(...args: any[]): void;
-		emit(...args: any[]): void;
-	};
-	settings: Record<string, any>;
-	notify(...args: any[]): void;
-}
-export declare function createRED(): MockRED;
-export declare function createJQuery(): (selector: any, attrs?: Record<string, any>) => any;
 interface NodeRefResolved<T = any> {
 	readonly __nrg_node_ref: true;
 	readonly __instance: T;
 }
+interface TypedInputResolved {
+	resolve(...args: any[]): any;
+	value: unknown;
+	type: string;
+}
+interface JsonSchemaObjectExtensions {
+	format?: "node-id" | "flow-id" | "topic-path" | (string & {});
+	/** expose this settings property to the editor via RED.settings */
+	exportable?: boolean;
+	/** set by SchemaType.NodeRef — the referenced config node type */
+	"x-nrg-node-type"?: string;
+	/** set by SchemaType.TypedInput — marks a TypedInput value/type pair */
+	"x-nrg-typed-input"?: boolean;
+	/** set by markNonValidatable — ajv skips this property */
+	"x-nrg-skip-validation"?: boolean;
+	/** form rendering hints consumed by the auto-generated editor form */
+	"x-nrg-form"?: {
+		icon?: string;
+		typedInputTypes?: string[];
+		editorLanguage?: string;
+		toggle?: boolean;
+	};
+}
 interface NodeRedNodeButtonDefinition {
 	toggle: string;
 	onclick: () => void;
@@ -95,22 +76,143 @@ interface NodeRedNode {
 	_newState?: NodeRedNode;
 	_app?: App | null;
 	_: (str: string) => string;
+	/** dynamic port count (base outputs + enabled built-in ports) */
+	outputs?: number;
+	/** injected when the node has an inputSchema */
+	validateInput?: boolean;
+	/** injected when the node has an outputsSchema */
+	validateOutput?: boolean;
+	/** present when the node's configSchema declares SchemaType.ReturnProperty() */
+	returnProperty?: string;
+	/** built-in port toggles, present when declared in the configSchema */
+	errorPort?: boolean;
+	completePort?: boolean;
+	statusPort?: boolean;
 	[key: string]: any;
 }
+interface JsonPropertySchema extends JsonSchemaObjectExtensions {
+	type?: string | string[];
+	properties?: Record<string, JsonPropertySchema>;
+	required?: string[];
+	enum?: unknown[];
+	anyOf?: JsonPropertySchema[];
+	const?: unknown;
+	items?: JsonPropertySchema;
+	title?: string;
+	description?: string;
+	default?: unknown;
+}
+interface JsonSchemaObject extends SchemaObject {
+	type: "object";
+	properties?: Record<string, JsonPropertySchema>;
+	required?: string[];
+}
 interface TypedInputValue {
 	value: string;
 	type: string;
 }
-type _ToClient<T> = T extends NodeRefResolved<any> ? string : T extends {
-	resolve(...args: any[]): any;
-	value: unknown;
-	type: string;
-} ? TypedInputValue : T extends (...args: any[]) => any ? T : T extends Array<infer I> ? _ToClient<I>[] : T extends object ? {
-	[K in keyof T]: _ToClient<T[K]>;
+type EditorStatic<T> = T extends NodeRefResolved<any> ? string : T extends TypedInputResolved ? TypedInputValue : T extends (...args: any[]) => any ? T : T extends Array<infer I> ? EditorStatic<I>[] : T extends object ? {
+	[K in keyof T]: EditorStatic<T[K]>;
 } : T;
+export interface MockEditor {
+	getValue(): string;
+	setValue(val: string): void;
+	getSession(): {
+		on(event: string, cb: (...args: any[]) => any): void;
+	};
+	focus(): void;
+	destroy(): void;
+	saveView(): void;
+	restoreView(): void;
+}
+export interface MockNotification {
+	update(msg: string, options?: Record<string, any>): void;
+	close(): void;
+}
+export interface MockPopover {
+	readonly element: null;
+	open(): MockPopover;
+	close(): MockPopover;
+	setContent(content: any): MockPopover;
+	move(options: Record<string, any>): void;
+}
+export interface MockTooltip extends MockPopover {
+	delete(): void;
+	setAction(action: string): void;
+}
+/**
+ * Mirrors the real RED.settings: exportable settings appear as direct
+ * properties, and get/set/remove manage user settings on the same store.
+ */
+export interface MockSettings {
+	get(key: string): any;
+	set(key: string, value: any): any;
+	remove(key: string): any;
+	[key: string]: any;
+}
+export interface MockRED {
+	_(key: string, substitutions?: Record<string, string>): string;
+	editor: {
+		createEditor(options: any): MockEditor;
+		prepareConfigNodeSelect(...args: any[]): void;
+		validateNode(...args: any[]): boolean;
+	};
+	tray: {
+		show(...args: any[]): void;
+		close(): void;
+	};
+	popover: {
+		create(options: any): MockPopover;
+		tooltip(...args: any[]): MockTooltip;
+	};
+	nodes: {
+		registerType(type: string, definition: any): void;
+		getType(type: string): any;
+		node(id: string): any;
+		add(node: any): any;
+		remove(id: string): {
+			links: any[];
+			nodes: any[];
+		};
+		/** Test-only: empties the node registry. */
+		clear(): void;
+		eachNode(callback: (node: any) => void | false): void;
+		eachConfig(callback: (node: any) => void | false): void;
+		filterNodes(filter: {
+			z?: string;
+			type?: string;
+		}): any[];
+		filterLinks(filter: {
+			source?: any;
+			target?: any;
+		}): any[];
+		/** Test-only: registers a link for filterLinks lookups. */
+		addLink(link: {
+			source: any;
+			target: any;
+			sourcePort?: number;
+		}): void;
+		dirty(): boolean;
+		dirty(dirty: boolean): void;
+		id(): string;
+	};
+	events: {
+		on(event: string, listener: (...args: any[]) => void): void;
+		off(event: string, listener?: (...args: any[]) => void): void;
+		emit(event: string, ...args: any[]): void;
+	};
+	comms: {
+		subscribe(topic: string, callback: (topic: string, msg: any) => void): void;
+		unsubscribe(topic: string, callback: (topic: string, msg: any) => void): void;
+		/** Test-only: simulates a runtime message. Supports `+` and `#` wildcards in subscriptions. */
+		publish(topic: string, msg: any): void;
+	};
+	settings: MockSettings;
+	notify(message: any, options?: Record<string, any>): MockNotification;
+}
 interface FormNode<TConfig extends TSchema = TSchema, TCredentials extends TSchema = TSchema> {
-	node: NodeRedNode & _ToClient<Static<TConfig>> & {
-		credentials: _ToClient<Static<TCredentials>> & Record<string, any>;
+	node: NodeRedNode & EditorStatic<Static<TConfig>> & {
+		credentials: EditorStatic<Static<TCredentials>> & Record<string, any>;
 	};
 	schema: Record<string, any>;
 	errors: Record<string, string>;
@@ -138,18 +240,31 @@ export interface TestNode {
 	changed: boolean;
 	_def: Record<string, any>;
 	_: (key: string) => string;
+	credentials?: Record<string, any>;
 	[key: string]: any;
 }
-interface FormProvide {
+export interface FormProvide {
 	__nrg_form_node: TestNode;
 	__nrg_form_schema: Record<string, any>;
 	__nrg_form_errors: Record<string, string>;
 }
-interface CreateNodeResult {
+export interface CreateNodeResult {
 	node: TestNode;
+	errors: Record<string, string>;
 	RED: MockRED;
 	provide: FormProvide;
 }
-export declare function createNode(overrides?: Record<string, any>): CreateNodeResult;
+export interface CreateNodeOptions {
+	configs?: Record<string, any>;
+	credentials?: Record<string, any>;
+	configSchema?: JsonSchemaObject;
+	credentialsSchema?: JsonSchemaObject;
+	/** Fake config nodes resolvable via RED.nodes.node(id) — required for NodeRef field validation. */
+	nodes?: Array<{
+		id: string;
+		type: string;
+	} & Record<string, any>>;
+}
+export declare function createNode(options?: CreateNodeOptions | Record<string, any>): CreateNodeResult;
 
 export {};

package/types/test-client-e2e.d.ts

@@ -93,6 +93,7 @@ export declare const defaultConfig: {
 export declare function setup(options?: SetupOptions): Promise<void>;
 export declare function teardown(): Promise<void>;
 export declare class NodeRedEditor {
+	#private;
 	readonly page: Page;
 	readonly port: number;
 	readonly errors: string[];
@@ -106,7 +107,43 @@ export declare class NodeRedEditor {
 	editNode(nodeId: string): Promise<void>;
 	clickDone(): Promise<void>;
 	clickCancel(): Promise<void>;
+	/**
+	 * Best-effort close of every open tray — call from afterEach so a failed
+	 * test never leaves a tray open for the next one.
+	 */
+	closeAllTrays(): Promise<void>;
+	/**
+	 * Closes the config-node tray (stacked above the node tray) with its own
+	 * Done button. The node tray underneath stays open — use clickDone() for it.
+	 */
+	clickConfigDone(): Promise<void>;
+	clickConfigCancel(): Promise<void>;
 	field(label: string): NodeRedField;
+	/**
+	 * Returns a JSON-safe snapshot of a node in the editor's model — use it to
+	 * assert values persisted after clickDone(). Functions, internals
+	 * (underscore-prefixed keys like `_def`), config `users` back-references,
+	 * and any circular references are stripped.
+	 */
+	getNode(nodeId: string): Promise<Record<string, any> | null>;
+	/**
+	 * Clicks the editor's Deploy button and waits until the workspace is clean.
+	 * Flows with invalid or unused nodes trigger a confirmation dialog — it is
+	 * confirmed automatically.
+	 */
+	clickDeploy(): Promise<void>;
+	/** Fetches the currently deployed flow from the runtime (GET /flows). */
+	getDeployedFlow(): Promise<Record<string, unknown>[]>;
+	/** Counts the output ports rendered for a node on the canvas. */
+	getNodePortCount(nodeId: string): Promise<number>;
+	/** Returns the node's label text as rendered on the canvas. */
+	getNodeLabel(nodeId: string): Promise<string>;
+	/** Returns the status text rendered under a node, or "" when none is set. */
+	getNodeStatus(nodeId: string): Promise<string>;
+	/**
+	 * Asserts no uncaught page errors occurred, then clears the collected list
+	 * so each test only fails for its own errors — call it from afterEach.
+	 */
 	expectNoPageErrors(): void;
 	get tray(): Locator;
 }
@@ -134,10 +171,23 @@ export declare class NodeRedField {
 	get select(): Locator;
 	get editButton(): Locator;
 	get addButton(): Locator;
+	/** Clicks the + button of a config field and waits for the config tray. */
+	openAddConfig(): Promise<void>;
+	/** Clicks the pencil button of a config field and waits for the config tray. */
+	openEditConfig(): Promise<void>;
 	getSelectedOption(): Promise<string>;
 	getSelectedOptionLabel(): Promise<string>;
 	getOptions(): Promise<string[]>;
 	get editorWrapper(): Locator;
+	/** Reads the value of the field's code editor (Monaco, ACE fallback). */
+	getEditorValue(): Promise<string>;
+	/** Sets the value of the field's code editor (Monaco, ACE fallback). */
+	setEditorValue(value: string): Promise<void>;
+	/**
+	 * Types into the field and returns the labels of the autocomplete
+	 * suggestions that appear (TypedInput types with an `autoComplete` source).
+	 */
+	getAutoCompleteSuggestions(prefix: string): Promise<string[]>;
 	get expandButton(): Locator;
 	get textarea(): Locator;
 	get requiredIndicator(): Locator;

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

@@ -1,6 +1,6 @@
 // Generated by dts-bundle-generator v9.5.1
 
-import { SchemaOptions, Static, TSchema } from '@sinclair/typebox';
+import { Static, TSchema } from '@sinclair/typebox';
 import { App } from 'vue';
 
 export interface MockEditor {
@@ -14,8 +14,29 @@ export interface MockEditor {
 	saveView(): void;
 	restoreView(): void;
 }
+interface MockNotification {
+	update(msg: string, options?: Record<string, any>): void;
+	close(): void;
+}
+interface MockPopover {
+	readonly element: null;
+	open(): MockPopover;
+	close(): MockPopover;
+	setContent(content: any): MockPopover;
+	move(options: Record<string, any>): void;
+}
+interface MockTooltip extends MockPopover {
+	delete(): void;
+	setAction(action: string): void;
+}
+interface MockSettings {
+	get(key: string): any;
+	set(key: string, value: any): any;
+	remove(key: string): any;
+	[key: string]: any;
+}
 export interface MockRED {
-	_(key: string): string;
+	_(key: string, substitutions?: Record<string, string>): string;
 	editor: {
 		createEditor(options: any): MockEditor;
 		prepareConfigNodeSelect(...args: any[]): void;
@@ -26,23 +47,53 @@ export interface MockRED {
 		close(): void;
 	};
 	popover: {
-		tooltip(...args: any[]): {
-			delete(): void;
-			setAction(...args: any[]): void;
-		};
+		create(options: any): MockPopover;
+		tooltip(...args: any[]): MockTooltip;
 	};
 	nodes: {
-		registerType(...args: any[]): void;
-		node(...args: any[]): null;
-		dirty(...args: any[]): boolean;
+		registerType(type: string, definition: any): void;
+		getType(type: string): any;
+		node(id: string): any;
+		add(node: any): any;
+		remove(id: string): {
+			links: any[];
+			nodes: any[];
+		};
+		/** Test-only: empties the node registry. */
+		clear(): void;
+		eachNode(callback: (node: any) => void | false): void;
+		eachConfig(callback: (node: any) => void | false): void;
+		filterNodes(filter: {
+			z?: string;
+			type?: string;
+		}): any[];
+		filterLinks(filter: {
+			source?: any;
+			target?: any;
+		}): any[];
+		/** Test-only: registers a link for filterLinks lookups. */
+		addLink(link: {
+			source: any;
+			target: any;
+			sourcePort?: number;
+		}): void;
+		dirty(): boolean;
+		dirty(dirty: boolean): void;
+		id(): string;
 	};
 	events: {
-		on(...args: any[]): void;
-		off(...args: any[]): void;
-		emit(...args: any[]): void;
+		on(event: string, listener: (...args: any[]) => void): void;
+		off(event: string, listener?: (...args: any[]) => void): void;
+		emit(event: string, ...args: any[]): void;
 	};
-	settings: Record<string, any>;
-	notify(...args: any[]): void;
+	comms: {
+		subscribe(topic: string, callback: (topic: string, msg: any) => void): void;
+		unsubscribe(topic: string, callback: (topic: string, msg: any) => void): void;
+		/** Test-only: simulates a runtime message. Supports `+` and `#` wildcards in subscriptions. */
+		publish(topic: string, msg: any): void;
+	};
+	settings: MockSettings;
+	notify(message: any, options?: Record<string, any>): MockNotification;
 }
 export declare function createRED(): MockRED;
 export declare function createJQuery(): (selector: any, attrs?: Record<string, any>) => any;
@@ -50,6 +101,11 @@ interface NodeRefResolved<T = any> {
 	readonly __nrg_node_ref: true;
 	readonly __instance: T;
 }
+interface TypedInputResolved {
+	resolve(...args: any[]): any;
+	value: unknown;
+	type: string;
+}
 interface NodeRedNodeButtonDefinition {
 	toggle: string;
 	onclick: () => void;
@@ -95,22 +151,30 @@ interface NodeRedNode {
 	_newState?: NodeRedNode;
 	_app?: App | null;
 	_: (str: string) => string;
+	/** dynamic port count (base outputs + enabled built-in ports) */
+	outputs?: number;
+	/** injected when the node has an inputSchema */
+	validateInput?: boolean;
+	/** injected when the node has an outputsSchema */
+	validateOutput?: boolean;
+	/** present when the node's configSchema declares SchemaType.ReturnProperty() */
+	returnProperty?: string;
+	/** built-in port toggles, present when declared in the configSchema */
+	errorPort?: boolean;
+	completePort?: boolean;
+	statusPort?: boolean;
 	[key: string]: any;
 }
 interface TypedInputValue {
 	value: string;
 	type: string;
 }
-type _ToClient<T> = T extends NodeRefResolved<any> ? string : T extends {
-	resolve(...args: any[]): any;
-	value: unknown;
-	type: string;
-} ? TypedInputValue : T extends (...args: any[]) => any ? T : T extends Array<infer I> ? _ToClient<I>[] : T extends object ? {
-	[K in keyof T]: _ToClient<T[K]>;
+type EditorStatic<T> = T extends NodeRefResolved<any> ? string : T extends TypedInputResolved ? TypedInputValue : T extends (...args: any[]) => any ? T : T extends Array<infer I> ? EditorStatic<I>[] : T extends object ? {
+	[K in keyof T]: EditorStatic<T[K]>;
 } : T;
 interface FormNode<TConfig extends TSchema = TSchema, TCredentials extends TSchema = TSchema> {
-	node: NodeRedNode & _ToClient<Static<TConfig>> & {
-		credentials: _ToClient<Static<TCredentials>> & Record<string, any>;
+	node: NodeRedNode & EditorStatic<Static<TConfig>> & {
+		credentials: EditorStatic<Static<TCredentials>> & Record<string, any>;
 	};
 	schema: Record<string, any>;
 	errors: Record<string, string>;

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

@@ -214,7 +214,7 @@ interface NodeConstructor<T = any, TConfig = any, TCredentials = any> {
 	readonly credentialsSchema?: Schema;
 	readonly settingsSchema?: Schema;
 	readonly inputSchema?: Schema;
-	readonly outputsSchema?: Schema | Schema[] | Record<string, Schema>;
+	readonly outputsSchema?: TSchema | TSchema[] | Record<string, TSchema>;
 	readonly validateInput?: boolean;
 	readonly validateOutput?: boolean;
 	readonly name: string;
@@ -304,6 +304,8 @@ interface NodeRedNodes {
 	}) | 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;

package/types/vite.d.ts

@@ -75,22 +75,47 @@ export interface NodeRedLauncherOptions {
 	args?: string[];
 }
 /**
- * Options for the `nodeRed()` Vite plugin.
- *
- * All options are optional — defaults work for the standard `src/` directory layout.
+ * Options for the dev server that runs and fronts the local Node-RED instance.
+ */
+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.
  */
-export interface NodeRedPluginOptions {
+export interface BuildOptions {
 	/** Output directory for the built Node-RED package. @default "./dist" */
 	outDir?: string;
-	/** Options for building the client-side editor UI. */
-	clientBuildOptions?: ClientBuildOptions;
 	/** Options for building the server-side node runtime. */
-	serverBuildOptions?: ServerBuildOptions;
-	/** Options for the Node-RED dev server launcher. */
-	nodeRedLauncherOptions?: NodeRedLauncherOptions;
+	server?: ServerBuildOptions;
+	/** Options for building the client-side editor UI. */
+	client?: ClientBuildOptions;
 	/** Extra files to copy into the output directory (e.g., LICENSE, README). */
 	extraFilesCopyTargets?: CopyTarget[];
 }
+/**
+ * Options for the `nrg()` Vite plugin.
+ *
+ * All options are optional — defaults work for the standard `src/` directory
+ * layout. Options are grouped by concern: `server` for the dev server and
+ * `build` for the production bundle.
+ */
+export interface NrgPluginOptions {
+	/** Dev server options (Node-RED launcher, editor path slug). */
+	server?: ServerOptions;
+	/** Production build options (output dir, server/client bundles, copies). */
+	build?: BuildOptions;
+}
 export interface PackageJson {
 	name: string;
 	version: string;
@@ -152,6 +177,10 @@ 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;
 }