ultravisor 1.0.3 → 1.0.8

package/source/beacon/Ultravisor-Beacon-ProviderRegistry.cjs

@@ -0,0 +1,330 @@
+/**
+ * Ultravisor Beacon Provider Registry
+ *
+ * Manages loaded capability providers, routes work items to the
+ * correct provider based on Capability:Action, and aggregates the
+ * capabilities list for beacon registration.
+ *
+ * Provider loading supports three sources:
+ *   - Built-in name ('Shell', 'FileSystem') → resolves to ./providers/
+ *   - Local file path ('./my-provider.cjs' or absolute) → require(resolved)
+ *   - npm package name ('ultravisor-provider-ml') → require(name)
+ */
+
+const libPath = require('path');
+
+class UltravisorBeaconProviderRegistry
+{
+	constructor()
+	{
+		// Map of 'Capability:Action' → { provider, actionDef }
+		this._ActionHandlers = {};
+
+		// Map of 'Capability' → { provider, defaultAction }
+		this._DefaultHandlers = {};
+
+		// All loaded providers by Name
+		this._Providers = {};
+
+		// Aggregate capabilities list (string[])
+		this._Capabilities = [];
+	}
+
+	/**
+	 * Register a provider instance.
+	 *
+	 * @param {object} pProvider - Provider instance (extends CapabilityProvider or duck-types it)
+	 * @returns {boolean} true if registered successfully
+	 */
+	registerProvider(pProvider)
+	{
+		if (!pProvider || !pProvider.Capability)
+		{
+			console.error('[ProviderRegistry] Provider must have a Capability.');
+			return false;
+		}
+
+		let tmpActions = pProvider.actions || {};
+		let tmpActionNames = Object.keys(tmpActions);
+
+		if (tmpActionNames.length === 0)
+		{
+			console.warn(`[ProviderRegistry] Provider "${pProvider.Name}" declares no actions.`);
+		}
+
+		// Index each action by composite key
+		for (let i = 0; i < tmpActionNames.length; i++)
+		{
+			let tmpKey = pProvider.Capability + ':' + tmpActionNames[i];
+			this._ActionHandlers[tmpKey] = {
+				provider: pProvider,
+				actionDef: tmpActions[tmpActionNames[i]]
+			};
+		}
+
+		// First declared action is the default for capability-only routing
+		if (tmpActionNames.length > 0)
+		{
+			this._DefaultHandlers[pProvider.Capability] = {
+				provider: pProvider,
+				defaultAction: tmpActionNames[0]
+			};
+		}
+
+		// Update aggregate capabilities list
+		let tmpCapabilities = pProvider.getCapabilities();
+		for (let i = 0; i < tmpCapabilities.length; i++)
+		{
+			if (this._Capabilities.indexOf(tmpCapabilities[i]) === -1)
+			{
+				this._Capabilities.push(tmpCapabilities[i]);
+			}
+		}
+
+		this._Providers[pProvider.Name] = pProvider;
+
+		console.log(`[ProviderRegistry] Registered "${pProvider.Name}" → ` +
+			`${pProvider.Capability} [${tmpActionNames.join(', ')}]`);
+
+		return true;
+	}
+
+	/**
+	 * Resolve a Capability+Action to a provider and action name.
+	 *
+	 * @param {string} pCapability - The capability to match
+	 * @param {string} [pAction] - Optional action within the capability
+	 * @returns {{ provider: object, action: string }|null}
+	 */
+	resolve(pCapability, pAction)
+	{
+		// Try exact Capability:Action match first
+		if (pAction)
+		{
+			let tmpKey = pCapability + ':' + pAction;
+			let tmpHandler = this._ActionHandlers[tmpKey];
+			if (tmpHandler)
+			{
+				return { provider: tmpHandler.provider, action: pAction };
+			}
+		}
+
+		// Fall back to default action for the capability
+		let tmpDefault = this._DefaultHandlers[pCapability];
+		if (tmpDefault)
+		{
+			return { provider: tmpDefault.provider, action: tmpDefault.defaultAction };
+		}
+
+		return null;
+	}
+
+	/**
+	 * Get the aggregate capabilities list for beacon registration.
+	 *
+	 * @returns {string[]}
+	 */
+	getCapabilities()
+	{
+		return this._Capabilities.slice();
+	}
+
+	/**
+	 * Get all loaded providers.
+	 *
+	 * @returns {object} Map of provider Name → instance
+	 */
+	getProviders()
+	{
+		return this._Providers;
+	}
+
+	/**
+	 * Load a provider from a source descriptor.
+	 *
+	 * @param {object} pDescriptor - { Source, Config }
+	 *   Source: 'Shell' (built-in), './my-provider.cjs' (local), 'npm-pkg' (npm)
+	 *   Config: per-provider config object (passed to constructor)
+	 * @returns {boolean} true if loaded and registered successfully
+	 */
+	loadProvider(pDescriptor)
+	{
+		let tmpSource = (pDescriptor && pDescriptor.Source) ? pDescriptor.Source : '';
+		let tmpConfig = (pDescriptor && pDescriptor.Config) ? pDescriptor.Config : {};
+
+		if (!tmpSource)
+		{
+			console.error('[ProviderRegistry] Provider descriptor must have a Source.');
+			return false;
+		}
+
+		let tmpProviderModule = null;
+
+		// Built-in providers
+		let tmpBuiltIns = {
+			'Shell': libPath.join(__dirname, 'providers', 'Ultravisor-Beacon-Provider-Shell.cjs'),
+			'FileSystem': libPath.join(__dirname, 'providers', 'Ultravisor-Beacon-Provider-FileSystem.cjs'),
+			'LLM': libPath.join(__dirname, 'providers', 'Ultravisor-Beacon-Provider-LLM.cjs')
+		};
+
+		try
+		{
+			if (tmpBuiltIns[tmpSource])
+			{
+				tmpProviderModule = require(tmpBuiltIns[tmpSource]);
+			}
+			else if (tmpSource.startsWith('.') || tmpSource.startsWith('/'))
+			{
+				// Local file path — resolve relative to cwd
+				tmpProviderModule = require(libPath.resolve(tmpSource));
+			}
+			else
+			{
+				// npm package
+				tmpProviderModule = require(tmpSource);
+			}
+		}
+		catch (pError)
+		{
+			console.error(`[ProviderRegistry] Failed to load provider from "${tmpSource}": ${pError.message}`);
+			return false;
+		}
+
+		if (!tmpProviderModule)
+		{
+			console.error(`[ProviderRegistry] Could not load provider from: ${tmpSource}`);
+			return false;
+		}
+
+		// Support class exports, factory functions, and pre-instantiated singletons
+		let tmpProvider;
+
+		if (typeof tmpProviderModule === 'function' &&
+			tmpProviderModule.prototype &&
+			typeof tmpProviderModule.prototype.execute === 'function')
+		{
+			// Class with execute on prototype — instantiate it
+			tmpProvider = new tmpProviderModule(tmpConfig);
+		}
+		else if (typeof tmpProviderModule === 'function')
+		{
+			// Factory function
+			tmpProvider = tmpProviderModule(tmpConfig);
+		}
+		else if (typeof tmpProviderModule === 'object' &&
+			typeof tmpProviderModule.execute === 'function')
+		{
+			// Pre-instantiated singleton
+			tmpProvider = tmpProviderModule;
+		}
+		else
+		{
+			console.error(`[ProviderRegistry] Invalid provider export from "${tmpSource}": ` +
+				`must be a class, factory function, or object with execute().`);
+			return false;
+		}
+
+		return this.registerProvider(tmpProvider);
+	}
+
+	/**
+	 * Load all providers from a config array.
+	 *
+	 * @param {Array<{ Source: string, Config?: object }>} pDescriptors
+	 * @returns {number} count of successfully loaded providers
+	 */
+	loadProviders(pDescriptors)
+	{
+		if (!Array.isArray(pDescriptors))
+		{
+			return 0;
+		}
+
+		let tmpCount = 0;
+
+		for (let i = 0; i < pDescriptors.length; i++)
+		{
+			if (this.loadProvider(pDescriptors[i]))
+			{
+				tmpCount++;
+			}
+		}
+
+		return tmpCount;
+	}
+
+	/**
+	 * Initialize all loaded providers sequentially.
+	 * Called before the beacon starts polling.
+	 *
+	 * @param {function} fCallback - function(pError)
+	 */
+	initializeAll(fCallback)
+	{
+		let tmpProviderNames = Object.keys(this._Providers);
+		let tmpIndex = 0;
+
+		let fNext = (pError) =>
+		{
+			if (pError)
+			{
+				return fCallback(pError);
+			}
+
+			if (tmpIndex >= tmpProviderNames.length)
+			{
+				return fCallback(null);
+			}
+
+			let tmpProviderName = tmpProviderNames[tmpIndex++];
+			let tmpProvider = this._Providers[tmpProviderName];
+
+			if (typeof tmpProvider.initialize === 'function')
+			{
+				tmpProvider.initialize(fNext);
+			}
+			else
+			{
+				fNext(null);
+			}
+		};
+
+		fNext(null);
+	}
+
+	/**
+	 * Shut down all loaded providers sequentially.
+	 * Called when the beacon is stopping.
+	 *
+	 * @param {function} fCallback - function(pError)
+	 */
+	shutdownAll(fCallback)
+	{
+		let tmpProviderNames = Object.keys(this._Providers);
+		let tmpIndex = 0;
+
+		let fNext = (pError) =>
+		{
+			if (tmpIndex >= tmpProviderNames.length)
+			{
+				return fCallback(pError || null);
+			}
+
+			let tmpProviderName = tmpProviderNames[tmpIndex++];
+			let tmpProvider = this._Providers[tmpProviderName];
+
+			if (typeof tmpProvider.shutdown === 'function')
+			{
+				tmpProvider.shutdown(fNext);
+			}
+			else
+			{
+				fNext(null);
+			}
+		};
+
+		fNext(null);
+	}
+}
+
+module.exports = UltravisorBeaconProviderRegistry;

package/source/beacon/providers/Ultravisor-Beacon-Provider-FileSystem.cjs

@@ -0,0 +1,331 @@
+/**
+ * Ultravisor Beacon Provider — FileSystem
+ *
+ * Built-in provider for local file operations on the Beacon worker.
+ *
+ * Capability: 'FileSystem'
+ * Actions:    'Read', 'Write', 'List', 'Copy'
+ *
+ * Provider config:
+ *   AllowedPaths     {string[]} — path prefixes the provider may access (empty = allow all)
+ *   MaxFileSizeBytes {number}   — max file size for read/write (default: 100MB)
+ */
+
+const libFS = require('fs');
+const libPath = require('path');
+
+const libBeaconCapabilityProvider = require('../Ultravisor-Beacon-CapabilityProvider.cjs');
+
+class UltravisorBeaconProviderFileSystem extends libBeaconCapabilityProvider
+{
+	constructor(pProviderConfig)
+	{
+		super(pProviderConfig);
+
+		this.Name = 'FileSystem';
+		this.Capability = 'FileSystem';
+
+		this._AllowedPaths = this._ProviderConfig.AllowedPaths || [];
+		this._MaxFileSizeBytes = this._ProviderConfig.MaxFileSizeBytes || 104857600;
+	}
+
+	get actions()
+	{
+		return {
+			'Read':
+			{
+				Description: 'Read a file from disk.',
+				SettingsSchema:
+				[
+					{ Name: 'FilePath', DataType: 'String', Required: true, Description: 'Path to the file to read' },
+					{ Name: 'Encoding', DataType: 'String', Required: false, Description: 'File encoding (default: utf8)' }
+				]
+			},
+			'Write':
+			{
+				Description: 'Write content to a file on disk.',
+				SettingsSchema:
+				[
+					{ Name: 'FilePath', DataType: 'String', Required: true, Description: 'Path to the output file' },
+					{ Name: 'Content', DataType: 'String', Required: true, Description: 'Content to write' },
+					{ Name: 'Encoding', DataType: 'String', Required: false, Description: 'File encoding (default: utf8)' }
+				]
+			},
+			'List':
+			{
+				Description: 'List files in a directory.',
+				SettingsSchema:
+				[
+					{ Name: 'Folder', DataType: 'String', Required: true, Description: 'Directory path to list' },
+					{ Name: 'Pattern', DataType: 'String', Required: false, Description: 'Glob-style pattern filter (e.g. *.txt)' }
+				]
+			},
+			'Copy':
+			{
+				Description: 'Copy a file from source to target.',
+				SettingsSchema:
+				[
+					{ Name: 'Source', DataType: 'String', Required: true, Description: 'Source file path' },
+					{ Name: 'TargetFile', DataType: 'String', Required: true, Description: 'Target file path' }
+				]
+			}
+		};
+	}
+
+	execute(pAction, pWorkItem, pContext, fCallback, fReportProgress)
+	{
+		switch (pAction)
+		{
+			case 'Read':
+				return this._executeRead(pWorkItem, pContext, fCallback);
+			case 'Write':
+				return this._executeWrite(pWorkItem, pContext, fCallback);
+			case 'List':
+				return this._executeList(pWorkItem, pContext, fCallback);
+			case 'Copy':
+				return this._executeCopy(pWorkItem, pContext, fCallback);
+			default:
+				return fCallback(null, {
+					Outputs: { StdOut: `Unknown FileSystem action: ${pAction}`, ExitCode: -1, Result: '' },
+					Log: [`FileSystem Provider: unsupported action [${pAction}].`]
+				});
+		}
+	}
+
+	// ================================================================
+	// Path helpers
+	// ================================================================
+
+	_resolvePath(pFilePath, pStagingPath)
+	{
+		if (!pFilePath) return '';
+		if (libPath.isAbsolute(pFilePath)) return pFilePath;
+		return libPath.resolve(pStagingPath || process.cwd(), pFilePath);
+	}
+
+	_isPathAllowed(pResolvedPath)
+	{
+		if (this._AllowedPaths.length === 0) return true;
+		for (let i = 0; i < this._AllowedPaths.length; i++)
+		{
+			if (pResolvedPath.startsWith(this._AllowedPaths[i])) return true;
+		}
+		return false;
+	}
+
+	// ================================================================
+	// Actions
+	// ================================================================
+
+	_executeRead(pWorkItem, pContext, fCallback)
+	{
+		let tmpSettings = pWorkItem.Settings || {};
+		let tmpFilePath = tmpSettings.FilePath || '';
+		let tmpEncoding = tmpSettings.Encoding || 'utf8';
+
+		if (!tmpFilePath)
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: 'No FilePath specified.', ExitCode: -1, Result: '' },
+				Log: ['FileSystem Read: no FilePath specified.']
+			});
+		}
+
+		tmpFilePath = this._resolvePath(tmpFilePath, pContext.StagingPath);
+
+		if (!this._isPathAllowed(tmpFilePath))
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: `Path not allowed: ${tmpFilePath}`, ExitCode: -1, Result: '' },
+				Log: [`FileSystem Read: path not in AllowedPaths: ${tmpFilePath}`]
+			});
+		}
+
+		try
+		{
+			let tmpContent = libFS.readFileSync(tmpFilePath, tmpEncoding);
+			let tmpBytesRead = Buffer.byteLength(tmpContent, tmpEncoding);
+
+			return fCallback(null, {
+				Outputs: {
+					StdOut: `Read ${tmpBytesRead} bytes from ${tmpFilePath}`,
+					ExitCode: 0,
+					Result: tmpContent
+				},
+				Log: [`FileSystem Read: read ${tmpBytesRead} bytes from ${tmpFilePath}`]
+			});
+		}
+		catch (pError)
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: `Read failed: ${pError.message}`, ExitCode: 1, Result: '' },
+				Log: [`FileSystem Read: failed to read ${tmpFilePath}: ${pError.message}`]
+			});
+		}
+	}
+
+	_executeWrite(pWorkItem, pContext, fCallback)
+	{
+		let tmpSettings = pWorkItem.Settings || {};
+		let tmpFilePath = tmpSettings.FilePath || '';
+		let tmpContent = tmpSettings.Content;
+		let tmpEncoding = tmpSettings.Encoding || 'utf8';
+
+		if (!tmpFilePath)
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: 'No FilePath specified.', ExitCode: -1, Result: '' },
+				Log: ['FileSystem Write: no FilePath specified.']
+			});
+		}
+
+		if (tmpContent === undefined || tmpContent === null) { tmpContent = ''; }
+		if (typeof tmpContent !== 'string') { tmpContent = JSON.stringify(tmpContent, null, '\t'); }
+
+		tmpFilePath = this._resolvePath(tmpFilePath, pContext.StagingPath);
+
+		if (!this._isPathAllowed(tmpFilePath))
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: `Path not allowed: ${tmpFilePath}`, ExitCode: -1, Result: '' },
+				Log: [`FileSystem Write: path not in AllowedPaths: ${tmpFilePath}`]
+			});
+		}
+
+		try
+		{
+			let tmpDir = libPath.dirname(tmpFilePath);
+			if (!libFS.existsSync(tmpDir)) { libFS.mkdirSync(tmpDir, { recursive: true }); }
+			libFS.writeFileSync(tmpFilePath, tmpContent, tmpEncoding);
+			let tmpBytesWritten = Buffer.byteLength(tmpContent, tmpEncoding);
+
+			return fCallback(null, {
+				Outputs: {
+					StdOut: `Wrote ${tmpBytesWritten} bytes to ${tmpFilePath}`,
+					ExitCode: 0,
+					Result: tmpFilePath
+				},
+				Log: [`FileSystem Write: wrote ${tmpBytesWritten} bytes to ${tmpFilePath}`]
+			});
+		}
+		catch (pError)
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: `Write failed: ${pError.message}`, ExitCode: 1, Result: '' },
+				Log: [`FileSystem Write: failed to write ${tmpFilePath}: ${pError.message}`]
+			});
+		}
+	}
+
+	_executeList(pWorkItem, pContext, fCallback)
+	{
+		let tmpSettings = pWorkItem.Settings || {};
+		let tmpFolder = tmpSettings.Folder || '';
+		let tmpPattern = tmpSettings.Pattern || '*';
+
+		if (!tmpFolder)
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: 'No Folder specified.', ExitCode: -1, Result: '' },
+				Log: ['FileSystem List: no Folder specified.']
+			});
+		}
+
+		tmpFolder = this._resolvePath(tmpFolder, pContext.StagingPath);
+
+		if (!this._isPathAllowed(tmpFolder))
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: `Path not allowed: ${tmpFolder}`, ExitCode: -1, Result: '' },
+				Log: [`FileSystem List: path not in AllowedPaths: ${tmpFolder}`]
+			});
+		}
+
+		try
+		{
+			let tmpFiles = libFS.readdirSync(tmpFolder);
+
+			// Simple glob: convert * and ? to regex
+			if (tmpPattern && tmpPattern !== '*')
+			{
+				let tmpRegex = new RegExp('^' + tmpPattern.replace(/\*/g, '.*').replace(/\?/g, '.') + '$');
+				tmpFiles = tmpFiles.filter(function (pFile) { return tmpRegex.test(pFile); });
+			}
+
+			return fCallback(null, {
+				Outputs: {
+					StdOut: `Found ${tmpFiles.length} files in ${tmpFolder}`,
+					ExitCode: 0,
+					Result: JSON.stringify(tmpFiles)
+				},
+				Log: [`FileSystem List: found ${tmpFiles.length} files in ${tmpFolder}`]
+			});
+		}
+		catch (pError)
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: `List failed: ${pError.message}`, ExitCode: 1, Result: '' },
+				Log: [`FileSystem List: failed: ${pError.message}`]
+			});
+		}
+	}
+
+	_executeCopy(pWorkItem, pContext, fCallback)
+	{
+		let tmpSettings = pWorkItem.Settings || {};
+		let tmpSource = tmpSettings.Source || '';
+		let tmpTarget = tmpSettings.TargetFile || '';
+
+		if (!tmpSource || !tmpTarget)
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: 'Source and TargetFile are required.', ExitCode: -1, Result: '' },
+				Log: ['FileSystem Copy: Source and TargetFile are required.']
+			});
+		}
+
+		tmpSource = this._resolvePath(tmpSource, pContext.StagingPath);
+		tmpTarget = this._resolvePath(tmpTarget, pContext.StagingPath);
+
+		if (!this._isPathAllowed(tmpSource))
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: `Source path not allowed: ${tmpSource}`, ExitCode: -1, Result: '' },
+				Log: [`FileSystem Copy: source not in AllowedPaths: ${tmpSource}`]
+			});
+		}
+
+		if (!this._isPathAllowed(tmpTarget))
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: `Target path not allowed: ${tmpTarget}`, ExitCode: -1, Result: '' },
+				Log: [`FileSystem Copy: target not in AllowedPaths: ${tmpTarget}`]
+			});
+		}
+
+		try
+		{
+			let tmpDir = libPath.dirname(tmpTarget);
+			if (!libFS.existsSync(tmpDir)) { libFS.mkdirSync(tmpDir, { recursive: true }); }
+			libFS.copyFileSync(tmpSource, tmpTarget);
+
+			return fCallback(null, {
+				Outputs: {
+					StdOut: `Copied ${tmpSource} → ${tmpTarget}`,
+					ExitCode: 0,
+					Result: tmpTarget
+				},
+				Log: [`FileSystem Copy: copied ${tmpSource} → ${tmpTarget}`]
+			});
+		}
+		catch (pError)
+		{
+			return fCallback(null, {
+				Outputs: { StdOut: `Copy failed: ${pError.message}`, ExitCode: 1, Result: '' },
+				Log: [`FileSystem Copy: failed: ${pError.message}`]
+			});
+		}
+	}
+}
+
+module.exports = UltravisorBeaconProviderFileSystem;