ultravisor-beacon 0.0.1

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "ultravisor-beacon",
+	"version": "0.0.1",
+	"description": "Ultravisor Beacon: lightweight beacon client and Fable service for remote task execution",
+	"main": "source/Ultravisor-Beacon-Service.cjs",
+	"scripts": {
+		"test": "npx mocha -u tdd --exit --timeout 10000 ./test/*_tests*",
+		"coverage": "npx nyc --reporter=lcov --reporter=text-summary npx mocha -- -u tdd --exit --timeout 10000 ./test/*_tests*"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/stevenvelozo/ultravisor-beacon.git"
+	},
+	"keywords": [
+		"ultravisor",
+		"beacon",
+		"remote",
+		"task",
+		"orchestration",
+		"fable"
+	],
+	"author": "Steven Velozo <steven@velozo.com>",
+	"license": "MIT",
+	"dependencies": {
+		"fable-serviceproviderbase": "^3.0.0"
+	},
+	"devDependencies": {
+		"mocha": "^10.0.0"
+	}
+}

package/source/Ultravisor-Beacon-CLI.cjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Ultravisor Beacon CLI
+ *
+ * Usage:
+ *   node Ultravisor-Beacon-CLI.cjs --server http://localhost:54321 --name GPU-Worker-1 --capabilities Shell,FileSystem
+ *
+ * Options:
+ *   --server URL          Ultravisor server URL (default: http://localhost:54321)
+ *   --name NAME           Beacon worker name (default: beacon-worker)
+ *   --capabilities LIST   Comma-separated capabilities (default: Shell)
+ *   --password PASSWORD    Authentication password for server connection
+ *
+ * For advanced provider configuration, use a .ultravisor-beacon.json file
+ * with a "Providers" array instead of --capabilities.
+ *   --max-concurrent N    Max concurrent work items (default: 1)
+ *   --poll-interval MS    Poll interval in ms (default: 5000)
+ *   --staging-path PATH   Local staging directory (default: cwd)
+ */
+
+const libPath = require('path');
+const libFS = require('fs');
+
+const libBeaconClient = require('./Ultravisor-Beacon-Client.cjs');
+
+// Parse command-line arguments
+let tmpConfig = {
+	ServerURL: 'http://localhost:54321',
+	Name: 'beacon-worker',
+	Capabilities: ['Shell'],
+	MaxConcurrent: 1,
+	PollIntervalMs: 5000,
+	HeartbeatIntervalMs: 30000,
+	StagingPath: process.cwd(),
+	Password: '',
+	Tags: {}
+};
+
+// Check for config file
+let tmpConfigFilePath = libPath.resolve(process.cwd(), '.ultravisor-beacon.json');
+if (libFS.existsSync(tmpConfigFilePath))
+{
+	try
+	{
+		let tmpFileConfig = JSON.parse(libFS.readFileSync(tmpConfigFilePath, 'utf8'));
+		tmpConfig = Object.assign(tmpConfig, tmpFileConfig);
+		console.log(`[Beacon CLI] Loaded config from ${tmpConfigFilePath}`);
+	}
+	catch (pError)
+	{
+		console.warn(`[Beacon CLI] Warning: could not parse ${tmpConfigFilePath}: ${pError.message}`);
+	}
+}
+
+// Parse CLI arguments (override config file)
+for (let i = 2; i < process.argv.length; i++)
+{
+	switch (process.argv[i])
+	{
+		case '--server':
+			tmpConfig.ServerURL = process.argv[++i] || tmpConfig.ServerURL;
+			break;
+		case '--name':
+			tmpConfig.Name = process.argv[++i] || tmpConfig.Name;
+			break;
+		case '--capabilities':
+			tmpConfig.Capabilities = (process.argv[++i] || 'Shell').split(',').map(s => s.trim());
+			break;
+		case '--max-concurrent':
+			tmpConfig.MaxConcurrent = parseInt(process.argv[++i]) || 1;
+			break;
+		case '--poll-interval':
+			tmpConfig.PollIntervalMs = parseInt(process.argv[++i]) || 5000;
+			break;
+		case '--staging-path':
+			tmpConfig.StagingPath = process.argv[++i] || process.cwd();
+			break;
+		case '--password':
+			tmpConfig.Password = process.argv[++i] || '';
+			break;
+		case '--help':
+		case '-h':
+			console.log('Ultravisor Beacon Worker');
+			console.log('');
+			console.log('Usage: node Ultravisor-Beacon-CLI.cjs [options]');
+			console.log('');
+			console.log('Options:');
+			console.log('  --server URL          Ultravisor server URL (default: http://localhost:54321)');
+			console.log('  --name NAME           Beacon worker name (default: beacon-worker)');
+			console.log('  --capabilities LIST   Comma-separated capabilities (default: Shell)');
+			console.log('  --max-concurrent N    Max concurrent work items (default: 1)');
+			console.log('  --poll-interval MS    Poll interval in ms (default: 5000)');
+			console.log('  --staging-path PATH   Local staging directory (default: cwd)');
+			console.log('  --password PASSWORD   Authentication password for server connection');
+			console.log('  --help, -h            Show this help');
+			console.log('');
+			console.log('Provider Configuration:');
+			console.log('  For advanced provider configuration, create a .ultravisor-beacon.json');
+			console.log('  file with a "Providers" array:');
+			console.log('');
+			console.log('  {');
+			console.log('    "Providers": [');
+			console.log('      { "Source": "Shell" },');
+			console.log('      { "Source": "FileSystem", "Config": { "AllowedPaths": ["/data"] } },');
+			console.log('      { "Source": "./my-custom-provider.cjs", "Config": {} }');
+			console.log('    ]');
+			console.log('  }');
+			process.exit(0);
+	}
+}
+
+// Create and start the Beacon client
+let tmpClient = new libBeaconClient(tmpConfig);
+
+tmpClient.start((pError) =>
+{
+	if (pError)
+	{
+		console.error(`[Beacon CLI] Failed to start: ${pError.message}`);
+		process.exit(1);
+	}
+
+	console.log(`[Beacon CLI] Beacon is running. Polling every ${tmpConfig.PollIntervalMs}ms.`);
+	console.log(`[Beacon CLI] Press Ctrl+C to stop.`);
+});
+
+// Handle graceful shutdown
+process.on('SIGINT', () =>
+{
+	console.log('\n[Beacon CLI] Shutting down...');
+	tmpClient.stop(() =>
+	{
+		process.exit(0);
+	});
+});
+
+process.on('SIGTERM', () =>
+{
+	tmpClient.stop(() =>
+	{
+		process.exit(0);
+	});
+});

package/source/Ultravisor-Beacon-CapabilityAdapter.cjs

@@ -0,0 +1,116 @@
+/**
+ * Ultravisor Beacon Capability Adapter
+ *
+ * Bridges Fable-world capability descriptors to the thin client's
+ * CapabilityProvider interface.  One adapter instance is created per
+ * capability registered with the Beacon Service.
+ *
+ * The adapter extends the thin-client base class so it can be loaded
+ * by the ProviderRegistry exactly like a built-in provider (Shell,
+ * FileSystem, etc.).
+ *
+ * Lifecycle:
+ *   1. Constructed by CapabilityManager with a capability descriptor
+ *   2. Registered with the thin client's ProviderRegistry
+ *   3. execute() delegates to the descriptor's Handler functions
+ *   4. initialize()/shutdown() delegate to descriptor hooks if present
+ */
+
+const libCapabilityProvider = require('./Ultravisor-Beacon-CapabilityProvider.cjs');
+
+class UltravisorBeaconCapabilityAdapter extends libCapabilityProvider
+{
+	constructor(pDescriptor)
+	{
+		super(pDescriptor.Config || {});
+
+		this._Descriptor = pDescriptor;
+
+		// Set identity from the descriptor
+		this.Name = pDescriptor.Name || pDescriptor.Capability || 'AdaptedProvider';
+		this.Capability = pDescriptor.Capability || 'Unknown';
+	}
+
+	/**
+	 * Return the actions map from the descriptor, stripping Handler
+	 * functions (which are internal) and keeping only Description
+	 * and SettingsSchema for introspection.
+	 */
+	get actions()
+	{
+		let tmpDescriptorActions = (this._Descriptor && this._Descriptor.actions) ? this._Descriptor.actions : {};
+		let tmpActionNames = Object.keys(tmpDescriptorActions);
+		let tmpActions = {};
+
+		for (let i = 0; i < tmpActionNames.length; i++)
+		{
+			let tmpName = tmpActionNames[i];
+			let tmpSrc = tmpDescriptorActions[tmpName];
+
+			tmpActions[tmpName] = {
+				Description: tmpSrc.Description || '',
+				SettingsSchema: tmpSrc.SettingsSchema || []
+			};
+		}
+
+		return tmpActions;
+	}
+
+	/**
+	 * Execute a work item by delegating to the descriptor's Handler.
+	 *
+	 * @param {string} pAction - Action name (e.g. 'ReadFile')
+	 * @param {object} pWorkItem - Full work item from the server
+	 * @param {object} pContext - Execution context: { StagingPath }
+	 * @param {function} fCallback - function(pError, pResult)
+	 * @param {function} [fReportProgress] - Optional progress callback
+	 */
+	execute(pAction, pWorkItem, pContext, fCallback, fReportProgress)
+	{
+		let tmpDescriptorActions = (this._Descriptor && this._Descriptor.actions) ? this._Descriptor.actions : {};
+		let tmpActionDef = tmpDescriptorActions[pAction];
+
+		if (!tmpActionDef || typeof tmpActionDef.Handler !== 'function')
+		{
+			return fCallback(new Error(
+				`CapabilityAdapter "${this.Name}" has no Handler for action "${pAction}".`));
+		}
+
+		try
+		{
+			tmpActionDef.Handler(pWorkItem, pContext, fCallback, fReportProgress);
+		}
+		catch (pError)
+		{
+			return fCallback(pError);
+		}
+	}
+
+	/**
+	 * Delegate initialization to the descriptor if present.
+	 */
+	initialize(fCallback)
+	{
+		if (this._Descriptor && typeof this._Descriptor.initialize === 'function')
+		{
+			return this._Descriptor.initialize(fCallback);
+		}
+
+		return fCallback(null);
+	}
+
+	/**
+	 * Delegate shutdown to the descriptor if present.
+	 */
+	shutdown(fCallback)
+	{
+		if (this._Descriptor && typeof this._Descriptor.shutdown === 'function')
+		{
+			return this._Descriptor.shutdown(fCallback);
+		}
+
+		return fCallback(null);
+	}
+}
+
+module.exports = UltravisorBeaconCapabilityAdapter;

package/source/Ultravisor-Beacon-CapabilityManager.cjs

@@ -0,0 +1,132 @@
+/**
+ * Ultravisor Beacon Capability Manager
+ *
+ * Manages capabilities registered by a host application.  Each
+ * capability descriptor declares a Capability name, actions with
+ * Handler functions, and optional lifecycle hooks.
+ *
+ * When the Beacon Service calls enable(), the CapabilityManager
+ * converts all registered descriptors into provider descriptors
+ * that the thin client's ProviderRegistry can load.
+ *
+ * Capability Descriptor shape:
+ * {
+ *   Capability: 'ContentSystem',
+ *   Name: 'ContentSystemProvider',
+ *   actions: {
+ *     'ReadFile': {
+ *       Description: 'Read a content file',
+ *       SettingsSchema: [{ Name: 'FilePath', DataType: 'String', Required: true }],
+ *       Handler: function(pWorkItem, pContext, fCallback, fReportProgress) { ... }
+ *     }
+ *   },
+ *   initialize: function(fCallback) { ... },   // optional
+ *   shutdown: function(fCallback) { ... }       // optional
+ * }
+ */
+
+const libCapabilityAdapter = require('./Ultravisor-Beacon-CapabilityAdapter.cjs');
+
+class UltravisorBeaconCapabilityManager
+{
+	constructor()
+	{
+		// Map of Capability name -> descriptor
+		this._Capabilities = {};
+	}
+
+	/**
+	 * Register a capability from the host application.
+	 *
+	 * @param {object} pDescriptor - Capability descriptor
+	 * @returns {boolean} true if registered successfully
+	 */
+	registerCapability(pDescriptor)
+	{
+		if (!pDescriptor || !pDescriptor.Capability)
+		{
+			console.error('[CapabilityManager] Descriptor must have a Capability name.');
+			return false;
+		}
+
+		if (!pDescriptor.actions || Object.keys(pDescriptor.actions).length === 0)
+		{
+			console.warn(`[CapabilityManager] Capability "${pDescriptor.Capability}" has no actions.`);
+		}
+
+		this._Capabilities[pDescriptor.Capability] = pDescriptor;
+		return true;
+	}
+
+	/**
+	 * Remove a previously registered capability.
+	 *
+	 * @param {string} pCapabilityName - The capability to remove
+	 * @returns {boolean} true if removed
+	 */
+	removeCapability(pCapabilityName)
+	{
+		if (this._Capabilities[pCapabilityName])
+		{
+			delete this._Capabilities[pCapabilityName];
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Get the list of registered capability names.
+	 *
+	 * @returns {string[]}
+	 */
+	getCapabilityNames()
+	{
+		return Object.keys(this._Capabilities);
+	}
+
+	/**
+	 * Get all registered capability descriptors.
+	 *
+	 * @returns {object} Map of capability name -> descriptor
+	 */
+	getCapabilities()
+	{
+		return this._Capabilities;
+	}
+
+	/**
+	 * Build provider descriptors for the thin client.
+	 *
+	 * Creates a CapabilityAdapter instance per registered capability
+	 * and returns them as provider descriptors compatible with
+	 * ProviderRegistry.loadProvider().
+	 *
+	 * The descriptors use a pre-instantiated object format (the adapter
+	 * instances already have execute() on them), which ProviderRegistry
+	 * supports as a direct registration path.
+	 *
+	 * @returns {Array<object>} Provider descriptors for the thin client
+	 */
+	buildProviderDescriptors()
+	{
+		let tmpDescriptors = [];
+		let tmpCapabilityNames = Object.keys(this._Capabilities);
+
+		for (let i = 0; i < tmpCapabilityNames.length; i++)
+		{
+			let tmpCapName = tmpCapabilityNames[i];
+			let tmpCapDescriptor = this._Capabilities[tmpCapName];
+
+			// Create an adapter instance that bridges this descriptor
+			// to the CapabilityProvider interface
+			let tmpAdapter = new libCapabilityAdapter(tmpCapDescriptor);
+
+			tmpDescriptors.push(tmpAdapter);
+		}
+
+		return tmpDescriptors;
+	}
+}
+
+module.exports = UltravisorBeaconCapabilityManager;

package/source/Ultravisor-Beacon-CapabilityProvider.cjs

@@ -0,0 +1,129 @@
+/**
+ * Ultravisor Beacon Capability Provider — Base Class
+ *
+ * Providers extend this class to implement a specific capability
+ * (Shell, FileSystem, MediaProcessing, etc.) that the Beacon can
+ * advertise and execute work items for.
+ *
+ * This is a plain JavaScript class — no Fable dependency — keeping
+ * the Beacon lightweight and deployable with minimal dependencies.
+ *
+ * Lifecycle:
+ *   1. constructor(pProviderConfig) — receive per-provider config
+ *   2. initialize(fCallback)        — async init (validate prereqs)
+ *   3. execute(...)                  — called per work item
+ *   4. shutdown(fCallback)           — cleanup on beacon stop
+ */
+
+class UltravisorBeaconCapabilityProvider
+{
+	constructor(pProviderConfig)
+	{
+		this._ProviderConfig = pProviderConfig || {};
+
+		// Subclasses MUST set these
+		this.Name = 'BaseProvider';
+		this.Capability = 'Unknown';
+	}
+
+	/**
+	 * Return the actions this provider supports.
+	 *
+	 * Override in subclasses. Each key is an action name, value is
+	 * an object with Description and optional SettingsSchema.
+	 *
+	 * @returns {object} Map of ActionName → { Description, SettingsSchema? }
+	 *
+	 * Example:
+	 * {
+	 *   'Execute': { Description: 'Run a shell command.' },
+	 *   'Script':  { Description: 'Run a script file.',
+	 *                SettingsSchema: [{ Name: 'ScriptPath', DataType: 'String', Required: true }] }
+	 * }
+	 */
+	get actions()
+	{
+		return {};
+	}
+
+	/**
+	 * Return the list of capability strings this provider advertises.
+	 *
+	 * Usually just [this.Capability]. Override for multi-capability
+	 * providers.
+	 *
+	 * @returns {string[]}
+	 */
+	getCapabilities()
+	{
+		return [this.Capability];
+	}
+
+	/**
+	 * Return a structured description of all supported actions.
+	 * Used for logging and introspection.
+	 *
+	 * @returns {Array<{ Capability: string, Action: string, Description: string }>}
+	 */
+	describeActions()
+	{
+		let tmpResult = [];
+		let tmpActions = this.actions;
+		let tmpActionNames = Object.keys(tmpActions);
+
+		for (let i = 0; i < tmpActionNames.length; i++)
+		{
+			tmpResult.push({
+				Capability: this.Capability,
+				Action: tmpActionNames[i],
+				Description: tmpActions[tmpActionNames[i]].Description || ''
+			});
+		}
+
+		return tmpResult;
+	}
+
+	/**
+	 * Execute a work item for the given action.
+	 *
+	 * @param {string} pAction - The action to perform (e.g. 'Execute', 'Read')
+	 * @param {object} pWorkItem - The full work item from the server:
+	 *   { WorkItemHash, Capability, Action, Settings, TimeoutMs, OperationHash }
+	 * @param {object} pContext - Execution context: { StagingPath }
+	 * @param {function} fCallback - function(pError, pResult)
+	 *   pResult = { Outputs: { ... }, Log: [...] }
+	 * @param {function} [fReportProgress] - Optional progress callback:
+	 *   function({ Percent, Message, Step, TotalSteps, Log })
+	 *   All fields optional. Call during long-running operations.
+	 */
+	execute(pAction, pWorkItem, pContext, fCallback, fReportProgress)
+	{
+		return fCallback(new Error(
+			`Provider "${this.Name}" has not implemented execute() for action "${pAction}".`));
+	}
+
+	/**
+	 * Optional lifecycle hook: called after provider is loaded,
+	 * before the beacon starts polling. Use for async initialization
+	 * (e.g. verifying that ffmpeg exists, connecting to a local API).
+	 *
+	 * @param {function} fCallback - function(pError)
+	 */
+	initialize(fCallback)
+	{
+		return fCallback(null);
+	}
+
+	/**
+	 * Optional lifecycle hook: called when the beacon is shutting down.
+	 * Use for cleanup (e.g. closing connections, flushing buffers).
+	 *
+	 * @param {function} fCallback - function(pError)
+	 */
+	shutdown(fCallback)
+	{
+		return fCallback(null);
+	}
+}
+
+module.exports = UltravisorBeaconCapabilityProvider;