ultravisor 1.0.2 → 1.0.4

package/source/services/tasks/control/Ultravisor-TaskType-LaunchOperation.cjs

@@ -0,0 +1,187 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * LaunchOperation Task Type
+ *
+ * Executes a child operation within the current operation's graph.
+ * Looks up the target operation by hash from the Hypervisor's state,
+ * creates an isolated execution context for it, and runs it via the
+ * ExecutionEngine.
+ *
+ * The child operation gets its own OperationState (optionally seeded
+ * from InputData) but shares the parent's GlobalState (as a copy).
+ *
+ * Flow:
+ *   Launch -> (execute child operation) -> Completed or Error
+ */
+class UltravisorTaskTypeLaunchOperation extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeLaunchOperation';
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'launch-operation',
+			Type: 'launch-operation',
+			Name: 'Launch Operation',
+			Description: 'Executes a child operation by hash, with isolated operation state.',
+			Category: 'control',
+
+			EventInputs: [
+				{ Name: 'Launch' }
+			],
+			EventOutputs: [
+				{ Name: 'Completed' },
+				{ Name: 'Error', IsError: true }
+			],
+			SettingsInputs: [
+				{ Name: 'OperationHash', DataType: 'String', Required: true },
+				{ Name: 'InputData', DataType: 'String' }
+			],
+			StateOutputs: [
+				{ Name: 'Result', DataType: 'String' },
+				{ Name: 'Status', DataType: 'String' },
+				{ Name: 'ElapsedMs', DataType: 'Number' }
+			],
+
+			DefaultSettings: { OperationHash: '', InputData: '' }
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpOperationHash = pResolvedSettings.OperationHash;
+
+		if (!tmpOperationHash || typeof(tmpOperationHash) !== 'string' || tmpOperationHash.length === 0)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 },
+				Log: ['No OperationHash specified.']
+			});
+		}
+
+		// Get the Hypervisor state service to look up the operation
+		let tmpStateService = this._getService('UltravisorHypervisorState');
+
+		if (!tmpStateService)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 },
+				Log: ['UltravisorHypervisorState service not found.']
+			});
+		}
+
+		// Get the ExecutionEngine to run the child operation
+		let tmpEngine = this._getService('UltravisorExecutionEngine');
+
+		if (!tmpEngine)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 },
+				Log: ['UltravisorExecutionEngine service not found.']
+			});
+		}
+
+		// Look up the target operation
+		tmpStateService.getOperation(tmpOperationHash,
+			(pError, pOperation) =>
+			{
+				if (pError)
+				{
+					return fCallback(null, {
+						EventToFire: 'Error',
+						Outputs: { Result: '', Status: 'Error', ElapsedMs: 0 },
+						Log: [`Operation [${tmpOperationHash}] not found: ${pError.message}`]
+					});
+				}
+
+				// Build initial state for the child operation
+				let tmpInitialState = {
+					// Share a copy of the parent's global state
+					GlobalState: JSON.parse(JSON.stringify(pExecutionContext.GlobalState || {})),
+					// Isolated operation state, optionally seeded from InputData
+					OperationState: {},
+					RunMode: pExecutionContext.RunMode || 'standard'
+				};
+
+				// Parse InputData if provided (expects JSON string)
+				if (pResolvedSettings.InputData && typeof(pResolvedSettings.InputData) === 'string' && pResolvedSettings.InputData.length > 0)
+				{
+					try
+					{
+						let tmpInputData = JSON.parse(pResolvedSettings.InputData);
+						if (typeof(tmpInputData) === 'object' && tmpInputData !== null)
+						{
+							tmpInitialState.OperationState = tmpInputData;
+						}
+					}
+					catch (pParseError)
+					{
+						// If not valid JSON, store as a raw string in OperationState.InputData
+						tmpInitialState.OperationState.InputData = pResolvedSettings.InputData;
+					}
+				}
+
+				let tmpStartTime = Date.now();
+
+				// Execute the child operation
+				tmpEngine.executeOperation(pOperation, tmpInitialState,
+					(pExecError, pContext) =>
+					{
+						let tmpElapsedMs = Date.now() - tmpStartTime;
+
+						if (pExecError)
+						{
+							return fCallback(null, {
+								EventToFire: 'Error',
+								Outputs: {
+									Result: pExecError.message,
+									Status: 'Error',
+									ElapsedMs: tmpElapsedMs
+								},
+								Log: [`Child operation [${tmpOperationHash}] failed: ${pExecError.message}`]
+							});
+						}
+
+						let tmpStatus = pContext.Status || 'Unknown';
+						let tmpResultSummary = JSON.stringify({
+							Status: tmpStatus,
+							TaskOutputs: pContext.TaskOutputs || {},
+							Errors: pContext.Errors || []
+						});
+
+						return fCallback(null, {
+							EventToFire: 'Completed',
+							Outputs: {
+								Result: tmpResultSummary,
+								Status: tmpStatus,
+								ElapsedMs: tmpElapsedMs
+							},
+							Log: [`Child operation [${tmpOperationHash}] completed with status: ${tmpStatus} (${tmpElapsedMs}ms)`]
+						});
+					});
+			});
+	}
+
+	/**
+	 * Get a service instance from the fable services map.
+	 */
+	_getService(pTypeName)
+	{
+		if (this.fable.servicesMap[pTypeName])
+		{
+			return Object.values(this.fable.servicesMap[pTypeName])[0];
+		}
+		return null;
+	}
+}
+
+module.exports = UltravisorTaskTypeLaunchOperation;

package/source/services/tasks/control/Ultravisor-TaskType-SplitExecute.cjs

@@ -0,0 +1,184 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * SplitExecute Task Type
+ *
+ * Splits an input string by a delimiter and fires an event for each token.
+ * Operates as a state machine: each invocation processes exactly one token.
+ *
+ * Flow (driven by graph connections):
+ *   PerformSplit  -> split input, store tokens, emit first token via TokenDataSent
+ *   StepComplete  -> advance to next token, emit via TokenDataSent
+ *                    (or fire CompletedAllSubtasks when all tokens are done)
+ *
+ * The loop is driven by explicit graph connections:
+ *   SplitExecute.TokenDataSent -> downstream tasks -> ... -> SplitExecute.StepComplete
+ *
+ * State is persisted between invocations in TaskOutputs[NodeHash]:
+ *   _Tokens        {Array}  - the split token array (internal)
+ *   CurrentToken   {string} - the current token being processed
+ *   TokenIndex     {number} - 0-based index of the current token
+ *   TokenCount     {number} - total number of tokens
+ *   CompletedCount {number} - number of tokens fully processed
+ */
+class UltravisorTaskTypeSplitExecute extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeSplitExecute';
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'split-execute',
+			Type: 'split-execute',
+			Name: 'Split Execute',
+			Description: 'Splits a string by delimiter and processes each token through a sub-graph.',
+			Category: 'control',
+
+			EventInputs: [
+				{ Name: 'PerformSplit' },
+				{ Name: 'StepComplete' }
+			],
+			EventOutputs: [
+				{ Name: 'TokenDataSent' },
+				{ Name: 'CompletedAllSubtasks' },
+				{ Name: 'Error', IsError: true }
+			],
+			SettingsInputs: [
+				{ Name: 'InputString', DataType: 'String', Required: true },
+				{ Name: 'SplitDelimiter', DataType: 'String', Required: true }
+			],
+			StateOutputs: [
+				{ Name: 'CurrentToken', DataType: 'String' },
+				{ Name: 'TokenIndex', DataType: 'Number' },
+				{ Name: 'TokenCount', DataType: 'Number' },
+				{ Name: 'CompletedCount', DataType: 'Number' }
+			],
+
+			DefaultSettings: { InputString: '', SplitDelimiter: '\n' }
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpTriggeringEvent = pExecutionContext.TriggeringEventName;
+
+		if (tmpTriggeringEvent === 'StepComplete')
+		{
+			return this._handleStepComplete(pExecutionContext, fCallback);
+		}
+
+		// Default: PerformSplit (initial trigger)
+		return this._handlePerformSplit(pResolvedSettings, pExecutionContext, fCallback);
+	}
+
+	/**
+	 * Handle the PerformSplit event: split input and emit the first token.
+	 */
+	_handlePerformSplit(pResolvedSettings, pExecutionContext, fCallback)
+	{
+		let tmpInputString = pResolvedSettings.InputString;
+		let tmpDelimiter = pResolvedSettings.SplitDelimiter;
+
+		if (typeof(tmpInputString) !== 'string')
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: { CurrentToken: '', TokenIndex: 0, TokenCount: 0, CompletedCount: 0 },
+				Log: ['InputString is not a string.']
+			});
+		}
+
+		if (tmpDelimiter === undefined || tmpDelimiter === null)
+		{
+			tmpDelimiter = '\n';
+		}
+
+		let tmpTokens = tmpInputString.split(tmpDelimiter);
+		let tmpTokenCount = tmpTokens.length;
+		let tmpLog = [`Splitting input (${tmpInputString.length} chars) by "${tmpDelimiter}" into ${tmpTokenCount} tokens.`];
+
+		if (tmpTokenCount === 0)
+		{
+			return fCallback(null, {
+				EventToFire: 'CompletedAllSubtasks',
+				Outputs: { CurrentToken: '', TokenIndex: 0, TokenCount: 0, CompletedCount: 0 },
+				Log: tmpLog.concat(['No tokens to process.'])
+			});
+		}
+
+		let tmpFirstToken = tmpTokens[0];
+		tmpLog.push(`Emitting token 1/${tmpTokenCount}: "${tmpFirstToken.substring(0, 50)}"`);
+
+		return fCallback(null, {
+			EventToFire: 'TokenDataSent',
+			Outputs: {
+				_Tokens: tmpTokens,
+				CurrentToken: tmpFirstToken,
+				TokenIndex: 0,
+				TokenCount: tmpTokenCount,
+				CompletedCount: 0
+			},
+			Log: tmpLog
+		});
+	}
+
+	/**
+	 * Handle the StepComplete event: advance to the next token or finish.
+	 */
+	_handleStepComplete(pExecutionContext, fCallback)
+	{
+		let tmpStoredState = pExecutionContext.TaskOutputs[pExecutionContext.NodeHash] || {};
+		let tmpTokens = tmpStoredState._Tokens;
+
+		if (!Array.isArray(tmpTokens))
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: { CurrentToken: '', TokenIndex: 0, TokenCount: 0, CompletedCount: 0 },
+				Log: ['StepComplete received but no stored tokens found. Was PerformSplit called first?']
+			});
+		}
+
+		let tmpTokenCount = tmpTokens.length;
+		let tmpPreviousIndex = tmpStoredState.TokenIndex || 0;
+		let tmpCompletedCount = (tmpStoredState.CompletedCount || 0) + 1;
+		let tmpNextIndex = tmpPreviousIndex + 1;
+
+		if (tmpNextIndex >= tmpTokenCount)
+		{
+			// All tokens processed
+			return fCallback(null, {
+				EventToFire: 'CompletedAllSubtasks',
+				Outputs: {
+					_Tokens: tmpTokens,
+					CurrentToken: tmpTokens[tmpTokenCount - 1],
+					TokenIndex: tmpTokenCount - 1,
+					TokenCount: tmpTokenCount,
+					CompletedCount: tmpCompletedCount
+				},
+				Log: [`All ${tmpTokenCount} tokens processed (${tmpCompletedCount} completed).`]
+			});
+		}
+
+		let tmpNextToken = tmpTokens[tmpNextIndex];
+
+		return fCallback(null, {
+			EventToFire: 'TokenDataSent',
+			Outputs: {
+				_Tokens: tmpTokens,
+				CurrentToken: tmpNextToken,
+				TokenIndex: tmpNextIndex,
+				TokenCount: tmpTokenCount,
+				CompletedCount: tmpCompletedCount
+			},
+			Log: [`Emitting token ${tmpNextIndex + 1}/${tmpTokenCount}: "${tmpNextToken.substring(0, 50)}"`]
+		});
+	}
+}
+
+module.exports = UltravisorTaskTypeSplitExecute;

package/source/services/tasks/data/Ultravisor-TaskType-ReplaceString.cjs

@@ -0,0 +1,82 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * ReplaceString Task Type
+ *
+ * Performs string find-and-replace on InputString.
+ * Replaces all occurrences of SearchString with ReplaceString.
+ */
+class UltravisorTaskTypeReplaceString extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeReplaceString';
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'replace-string',
+			Type: 'replace-string',
+			Name: 'Replace String',
+			Description: 'Replaces all occurrences of a search string within the input.',
+			Category: 'data',
+
+			EventInputs: [{ Name: 'Replace' }],
+			EventOutputs: [
+				{ Name: 'ReplaceComplete' },
+				{ Name: 'Error', IsError: true }
+			],
+			SettingsInputs: [
+				{ Name: 'InputString', DataType: 'String', Required: true },
+				{ Name: 'SearchString', DataType: 'String', Required: true },
+				{ Name: 'ReplaceString', DataType: 'String', Required: false }
+			],
+			StateOutputs: [
+				{ Name: 'ReplacedString', DataType: 'String' }
+			],
+
+			DefaultSettings: { InputString: '', SearchString: '', ReplaceString: '' }
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpInputString = pResolvedSettings.InputString;
+		let tmpSearchString = pResolvedSettings.SearchString;
+		let tmpReplaceString = pResolvedSettings.ReplaceString || '';
+
+		if (typeof(tmpInputString) !== 'string')
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: ['InputString is not a string.']
+			});
+		}
+
+		if (!tmpSearchString || typeof(tmpSearchString) !== 'string')
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: ['SearchString is empty or not a string.']
+			});
+		}
+
+		// Replace all occurrences
+		let tmpResult = tmpInputString.split(tmpSearchString).join(tmpReplaceString);
+
+		return fCallback(null, {
+			EventToFire: 'ReplaceComplete',
+			Outputs: {
+				ReplacedString: tmpResult
+			},
+			Log: [`Replaced "${tmpSearchString}" with "${tmpReplaceString}" (${tmpInputString.split(tmpSearchString).length - 1} occurrences).`]
+		});
+	}
+}
+
+module.exports = UltravisorTaskTypeReplaceString;

package/source/services/tasks/data/Ultravisor-TaskType-SetValues.cjs

@@ -0,0 +1,81 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * SetValues Task Type
+ *
+ * Sets one or more values in state at specified addresses.
+ * Used for initializing state, transforming data between levels, or
+ * setting computed values.
+ *
+ * Settings.Mappings is an array of { Address, Value } objects.
+ * Each mapping sets the value at the given state address.
+ */
+class UltravisorTaskTypeSetValues extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeSetValues';
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'set-values',
+			Type: 'set-values',
+			Name: 'Set Values',
+			Description: 'Sets one or more values in state at specified addresses.',
+			Category: 'data',
+
+			EventInputs: [{ Name: 'Execute' }],
+			EventOutputs: [{ Name: 'Complete' }],
+			SettingsInputs: [
+				{ Name: 'Mappings', DataType: 'Array', Required: true }
+			],
+			StateOutputs: [],
+
+			DefaultSettings: { Mappings: [] }
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpMappings = pResolvedSettings.Mappings;
+
+		if (!Array.isArray(tmpMappings))
+		{
+			return fCallback(null, {
+				EventToFire: 'Complete',
+				Outputs: {},
+				Log: ['No mappings provided or Mappings is not an array.']
+			});
+		}
+
+		let tmpStateWrites = {};
+		let tmpLog = [];
+
+		for (let i = 0; i < tmpMappings.length; i++)
+		{
+			let tmpMapping = tmpMappings[i];
+
+			if (!tmpMapping || !tmpMapping.Address)
+			{
+				tmpLog.push(`Mapping ${i}: skipped (no Address).`);
+				continue;
+			}
+
+			tmpStateWrites[tmpMapping.Address] = tmpMapping.Value;
+			tmpLog.push(`Set [${tmpMapping.Address}] = ${JSON.stringify(tmpMapping.Value)}`);
+		}
+
+		return fCallback(null, {
+			EventToFire: 'Complete',
+			Outputs: {},
+			StateWrites: tmpStateWrites,
+			Log: tmpLog
+		});
+	}
+}
+
+module.exports = UltravisorTaskTypeSetValues;

package/source/services/tasks/data/Ultravisor-TaskType-StringAppender.cjs

@@ -0,0 +1,101 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * StringAppender Task Type
+ *
+ * Appends InputString to the value at OutputAddress.
+ * If the target address is empty/undefined, sets it to InputString.
+ * Useful for accumulating results across loop iterations (e.g., split-execute).
+ */
+class UltravisorTaskTypeStringAppender extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeStringAppender';
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'string-appender',
+			Type: 'string-appender',
+			Name: 'String Appender',
+			Description: 'Appends a string to a value at a specified state address.',
+			Category: 'data',
+
+			EventInputs: [{ Name: 'Append' }],
+			EventOutputs: [{ Name: 'Completed' }],
+			SettingsInputs: [
+				{ Name: 'InputString', DataType: 'String', Required: true },
+				{ Name: 'OutputAddress', DataType: 'String', Required: true },
+				{ Name: 'AppendNewline', DataType: 'Boolean', Required: false, Description: 'When true, append a newline after each InputString.' }
+			],
+			StateOutputs: [
+				{ Name: 'AppendedString', DataType: 'String' }
+			],
+
+			DefaultSettings: { InputString: '', OutputAddress: '', AppendNewline: false }
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpInputString = pResolvedSettings.InputString;
+		let tmpOutputAddress = pResolvedSettings.OutputAddress;
+
+		if (typeof(tmpInputString) !== 'string')
+		{
+			tmpInputString = String(tmpInputString !== undefined ? tmpInputString : '');
+		}
+
+		if (!tmpOutputAddress || typeof(tmpOutputAddress) !== 'string')
+		{
+			// No output address — just pass through as output
+			return fCallback(null, {
+				EventToFire: 'Completed',
+				Outputs: {
+					AppendedString: tmpInputString
+				},
+				Log: ['No OutputAddress specified, returning InputString as AppendedString.']
+			});
+		}
+
+		// Read the existing value at the output address
+		let tmpStateManager = pExecutionContext.StateManager;
+		let tmpExistingValue = '';
+
+		if (tmpStateManager)
+		{
+			let tmpResolved = tmpStateManager.resolveAddress(tmpOutputAddress, pExecutionContext, pExecutionContext.NodeHash);
+
+			if (tmpResolved !== undefined && tmpResolved !== null)
+			{
+				tmpExistingValue = String(tmpResolved);
+			}
+		}
+
+		// Optionally add a newline after the input string
+		if (pResolvedSettings.AppendNewline)
+		{
+			tmpInputString = tmpInputString + '\n';
+		}
+
+		let tmpAppendedValue = tmpExistingValue + tmpInputString;
+
+		let tmpStateWrites = {};
+		tmpStateWrites[tmpOutputAddress] = tmpAppendedValue;
+
+		return fCallback(null, {
+			EventToFire: 'Completed',
+			Outputs: {
+				AppendedString: tmpAppendedValue
+			},
+			StateWrites: tmpStateWrites,
+			Log: [`Appended ${tmpInputString.length} chars to [${tmpOutputAddress}] (total: ${tmpAppendedValue.length}).`]
+		});
+	}
+}
+
+module.exports = UltravisorTaskTypeStringAppender;