ultravisor 1.0.2 → 1.0.4

package/source/services/Ultravisor-StateManager.cjs

@@ -0,0 +1,241 @@
+const libPictService = require('pict-serviceproviderbase');
+
+/**
+ * Manages three-level state (Global, Operation, Task) and provides
+ * address resolution through Manyfest.
+ *
+ * Address prefixes:
+ *   Global.X            -> GlobalState.X
+ *   Operation.X         -> OperationState.X
+ *   Task.X              -> TaskOutputs[currentNodeHash].X
+ *   TaskOutput.{Hash}.X -> TaskOutputs[Hash].X
+ *   Staging.Path        -> StagingPath string
+ */
+class UltravisorStateManager extends libPictService
+{
+	constructor(pPict, pOptions, pServiceHash)
+	{
+		super(pPict, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorStateManager';
+
+		this._Manyfest = this.fable.newManyfest();
+	}
+
+	/**
+	 * Resolve an address against the execution context.
+	 *
+	 * @param {string} pAddress - The address to resolve (e.g. 'Operation.InputFilePath').
+	 * @param {object} pExecutionContext - The runtime execution context.
+	 * @param {string} [pCurrentNodeHash] - The current task node's hash (for Task.X resolution).
+	 * @returns {*} The resolved value, or undefined if not found.
+	 */
+	resolveAddress(pAddress, pExecutionContext, pCurrentNodeHash)
+	{
+		if (!pAddress || typeof(pAddress) !== 'string')
+		{
+			return undefined;
+		}
+
+		let tmpDotIndex = pAddress.indexOf('.');
+		let tmpPrefix;
+		let tmpRemainder;
+
+		if (tmpDotIndex > -1)
+		{
+			tmpPrefix = pAddress.substring(0, tmpDotIndex);
+			tmpRemainder = pAddress.substring(tmpDotIndex + 1);
+		}
+		else
+		{
+			tmpPrefix = pAddress;
+			tmpRemainder = '';
+		}
+
+		switch (tmpPrefix)
+		{
+			case 'Global':
+				return this._resolveFromObject(pExecutionContext.GlobalState, tmpRemainder);
+
+			case 'Operation':
+				return this._resolveFromObject(pExecutionContext.OperationState, tmpRemainder);
+
+			case 'Task':
+				if (!pCurrentNodeHash)
+				{
+					this.log.warn(`UltravisorStateManager: resolveAddress for Task.X requires a current node hash.`);
+					return undefined;
+				}
+				return this._resolveFromObject(
+					pExecutionContext.TaskOutputs[pCurrentNodeHash] || {},
+					tmpRemainder);
+
+			case 'TaskOutput':
+			{
+				// TaskOutput.{NodeHash}.{Path}
+				let tmpSecondDot = tmpRemainder.indexOf('.');
+				if (tmpSecondDot < 0)
+				{
+					// Just TaskOutput.{NodeHash} -- return the whole output object
+					return pExecutionContext.TaskOutputs[tmpRemainder] || {};
+				}
+				let tmpNodeHash = tmpRemainder.substring(0, tmpSecondDot);
+				let tmpPath = tmpRemainder.substring(tmpSecondDot + 1);
+				return this._resolveFromObject(
+					pExecutionContext.TaskOutputs[tmpNodeHash] || {},
+					tmpPath);
+			}
+
+			case 'Staging':
+				if (tmpRemainder === 'Path' || tmpRemainder === '')
+				{
+					return pExecutionContext.StagingPath || '';
+				}
+				return undefined;
+
+			default:
+				// Fall through: try the full address against OperationState first,
+				// then GlobalState. This allows shorthand like 'InputFilePath'
+				// to resolve from Operation state.
+				let tmpValue = this._resolveFromObject(pExecutionContext.OperationState, pAddress);
+				if (tmpValue !== undefined)
+				{
+					return tmpValue;
+				}
+				return this._resolveFromObject(pExecutionContext.GlobalState, pAddress);
+		}
+	}
+
+	/**
+	 * Set a value at an address in the execution context.
+	 *
+	 * @param {string} pAddress - The address to set (e.g. 'Operation.InputFilePath').
+	 * @param {*} pValue - The value to set.
+	 * @param {object} pExecutionContext - The runtime execution context.
+	 * @param {string} [pCurrentNodeHash] - The current task node's hash (for Task.X).
+	 * @returns {boolean} True if the value was set successfully.
+	 */
+	setAddress(pAddress, pValue, pExecutionContext, pCurrentNodeHash)
+	{
+		if (!pAddress || typeof(pAddress) !== 'string')
+		{
+			return false;
+		}
+
+		let tmpDotIndex = pAddress.indexOf('.');
+		let tmpPrefix;
+		let tmpRemainder;
+
+		if (tmpDotIndex > -1)
+		{
+			tmpPrefix = pAddress.substring(0, tmpDotIndex);
+			tmpRemainder = pAddress.substring(tmpDotIndex + 1);
+		}
+		else
+		{
+			tmpPrefix = pAddress;
+			tmpRemainder = '';
+		}
+
+		switch (tmpPrefix)
+		{
+			case 'Global':
+				return this._setOnObject(pExecutionContext.GlobalState, tmpRemainder, pValue);
+
+			case 'Operation':
+				return this._setOnObject(pExecutionContext.OperationState, tmpRemainder, pValue);
+
+			case 'Task':
+				if (!pCurrentNodeHash)
+				{
+					this.log.warn(`UltravisorStateManager: setAddress for Task.X requires a current node hash.`);
+					return false;
+				}
+				if (!pExecutionContext.TaskOutputs[pCurrentNodeHash])
+				{
+					pExecutionContext.TaskOutputs[pCurrentNodeHash] = {};
+				}
+				return this._setOnObject(
+					pExecutionContext.TaskOutputs[pCurrentNodeHash],
+					tmpRemainder, pValue);
+
+			case 'TaskOutput':
+			{
+				let tmpSecondDot = tmpRemainder.indexOf('.');
+				if (tmpSecondDot < 0)
+				{
+					// Setting the entire TaskOutput for a node
+					pExecutionContext.TaskOutputs[tmpRemainder] = pValue;
+					return true;
+				}
+				let tmpNodeHash = tmpRemainder.substring(0, tmpSecondDot);
+				let tmpPath = tmpRemainder.substring(tmpSecondDot + 1);
+				if (!pExecutionContext.TaskOutputs[tmpNodeHash])
+				{
+					pExecutionContext.TaskOutputs[tmpNodeHash] = {};
+				}
+				return this._setOnObject(
+					pExecutionContext.TaskOutputs[tmpNodeHash],
+					tmpPath, pValue);
+			}
+
+			default:
+				// Default: write to OperationState
+				return this._setOnObject(pExecutionContext.OperationState, pAddress, pValue);
+		}
+	}
+
+	/**
+	 * Build a root data object for Pict template resolution.
+	 * This object can be passed to pict.parseTemplate as the record.
+	 *
+	 * @param {object} pExecutionContext - The runtime execution context.
+	 * @param {*} [pSourceValue] - An optional source value (e.g. for state connection resolution).
+	 * @returns {object} Root data object with all state levels.
+	 */
+	buildTemplateContext(pExecutionContext, pSourceValue)
+	{
+		return {
+			Value: pSourceValue,
+			Global: pExecutionContext.GlobalState || {},
+			Operation: pExecutionContext.OperationState || {},
+			TaskOutput: pExecutionContext.TaskOutputs || {},
+			Staging: { Path: pExecutionContext.StagingPath || '' }
+		};
+	}
+
+	// --- Internal helpers ---
+
+	_resolveFromObject(pObject, pPath)
+	{
+		if (!pObject || typeof(pObject) !== 'object')
+		{
+			return undefined;
+		}
+
+		if (!pPath || pPath === '')
+		{
+			return pObject;
+		}
+
+		return this._Manyfest.getValueAtAddress(pObject, pPath);
+	}
+
+	_setOnObject(pObject, pPath, pValue)
+	{
+		if (!pObject || typeof(pObject) !== 'object')
+		{
+			return false;
+		}
+
+		if (!pPath || pPath === '')
+		{
+			return false;
+		}
+
+		this._Manyfest.setValueAtAddress(pObject, pPath, pValue);
+		return true;
+	}
+}
+
+module.exports = UltravisorStateManager;

package/source/services/Ultravisor-TaskTypeRegistry.cjs

@@ -0,0 +1,143 @@
+const libPictService = require('pict-serviceproviderbase');
+
+/**
+ * Registry of all available task type classes.
+ *
+ * Task types are registered by hash and can be instantiated on demand
+ * by the ExecutionEngine when a task node needs to execute.
+ */
+class UltravisorTaskTypeRegistry extends libPictService
+{
+	constructor(pPict, pOptions, pServiceHash)
+	{
+		super(pPict, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeRegistry';
+
+		// Map of task type hash -> task type class
+		this._TaskTypes = {};
+
+		// Map of task type hash -> definition (cached from class instances)
+		this._Definitions = {};
+	}
+
+	/**
+	 * Register a task type class.
+	 *
+	 * @param {Function} pTaskTypeClass - A class extending UltravisorTaskType.
+	 * @returns {object} The task type definition.
+	 */
+	registerTaskType(pTaskTypeClass)
+	{
+		if (typeof(pTaskTypeClass) !== 'function')
+		{
+			this.log.error('UltravisorTaskTypeRegistry: registerTaskType requires a constructor function.');
+			return false;
+		}
+
+		// Instantiate temporarily to read the definition
+		let tmpInstance = new pTaskTypeClass(this.fable, {}, `TaskType-Probe-${Date.now()}`);
+		let tmpDefinition = tmpInstance.definition;
+
+		if (!tmpDefinition || !tmpDefinition.Hash)
+		{
+			this.log.error('UltravisorTaskTypeRegistry: task type class must have a definition with a Hash.');
+			return false;
+		}
+
+		this._TaskTypes[tmpDefinition.Hash] = pTaskTypeClass;
+		this._Definitions[tmpDefinition.Hash] = tmpDefinition;
+
+		this.log.info(`UltravisorTaskTypeRegistry: registered task type [${tmpDefinition.Hash}] "${tmpDefinition.Name}"`);
+
+		return tmpDefinition;
+	}
+
+	/**
+	 * Create a new instance of a task type by hash.
+	 *
+	 * @param {string} pHash - The task type hash (e.g. 'read-file').
+	 * @returns {object|null} A new instance of the task type, or null if not found.
+	 */
+	instantiateTaskType(pHash)
+	{
+		let tmpTaskTypeClass = this._TaskTypes[pHash];
+
+		if (!tmpTaskTypeClass)
+		{
+			this.log.error(`UltravisorTaskTypeRegistry: unknown task type hash [${pHash}]`);
+			return null;
+		}
+
+		return new tmpTaskTypeClass(this.fable, {}, `TaskType-${pHash}-${Date.now()}`);
+	}
+
+	/**
+	 * Get the definition for a task type by hash.
+	 *
+	 * @param {string} pHash - The task type hash.
+	 * @returns {object|null} The definition, or null if not found.
+	 */
+	getDefinition(pHash)
+	{
+		return this._Definitions[pHash] || null;
+	}
+
+	/**
+	 * Get all registered task type definitions.
+	 *
+	 * @returns {Array} Array of definition objects.
+	 */
+	listDefinitions()
+	{
+		let tmpDefinitions = [];
+		let tmpKeys = Object.keys(this._Definitions);
+
+		for (let i = 0; i < tmpKeys.length; i++)
+		{
+			tmpDefinitions.push(this._Definitions[tmpKeys[i]]);
+		}
+
+		return tmpDefinitions;
+	}
+
+	/**
+	 * Check if a task type hash is registered.
+	 *
+	 * @param {string} pHash - The task type hash.
+	 * @returns {boolean}
+	 */
+	hasTaskType(pHash)
+	{
+		return this._TaskTypes.hasOwnProperty(pHash);
+	}
+
+	/**
+	 * Register all built-in task types.
+	 * Called during application initialization.
+	 */
+	registerBuiltInTaskTypes()
+	{
+		// File I/O
+		this.registerTaskType(require('./tasks/file-io/Ultravisor-TaskType-ReadFile.cjs'));
+		this.registerTaskType(require('./tasks/file-io/Ultravisor-TaskType-WriteFile.cjs'));
+
+		// Data
+		this.registerTaskType(require('./tasks/data/Ultravisor-TaskType-SetValues.cjs'));
+		this.registerTaskType(require('./tasks/data/Ultravisor-TaskType-ReplaceString.cjs'));
+		this.registerTaskType(require('./tasks/data/Ultravisor-TaskType-StringAppender.cjs'));
+
+		// Control
+		this.registerTaskType(require('./tasks/control/Ultravisor-TaskType-IfConditional.cjs'));
+		this.registerTaskType(require('./tasks/control/Ultravisor-TaskType-SplitExecute.cjs'));
+		this.registerTaskType(require('./tasks/control/Ultravisor-TaskType-LaunchOperation.cjs'));
+
+		// Interaction
+		this.registerTaskType(require('./tasks/interaction/Ultravisor-TaskType-ValueInput.cjs'));
+		this.registerTaskType(require('./tasks/interaction/Ultravisor-TaskType-ErrorMessage.cjs'));
+
+		this.log.info(`UltravisorTaskTypeRegistry: ${Object.keys(this._TaskTypes).length} built-in task types registered.`);
+	}
+}
+
+module.exports = UltravisorTaskTypeRegistry;

package/source/services/tasks/Ultravisor-TaskType-Base.cjs

@@ -0,0 +1,105 @@
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+/**
+ * Base class for all Ultravisor task types.
+ *
+ * Subclasses override `definition` to declare their port schema
+ * (EventInputs, EventOutputs, SettingsInputs, StateOutputs)
+ * and `execute` to implement the task logic.
+ */
+class UltravisorTaskType extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskType';
+	}
+
+	/**
+	 * Port schema and metadata for this task type.
+	 * Subclasses MUST override this getter.
+	 *
+	 * @returns {object} Task type definition with:
+	 *   Hash            {string}   - unique type identifier (e.g. 'read-file')
+	 *   Name            {string}   - display name
+	 *   Description     {string}   - what the task does
+	 *   Category        {string}   - grouping key (file-io, data, control, interaction)
+	 *   EventInputs     {Array}    - [{ Name, Description? }]
+	 *   EventOutputs    {Array}    - [{ Name, Description?, IsError? }]
+	 *   SettingsInputs  {Array}    - [{ Name, DataType, Required?, Default?, Description? }]
+	 *   StateOutputs    {Array}    - [{ Name, DataType?, Description? }]
+	 *   DefaultSettings {object}   - default values for SettingsInputs
+	 */
+	get definition()
+	{
+		return {
+			Hash: 'base',
+			Name: 'Base Task',
+			Description: 'Override this in subclasses.',
+			Category: 'internal',
+			EventInputs: [],
+			EventOutputs: [],
+			SettingsInputs: [],
+			StateOutputs: [],
+			DefaultSettings: {}
+		};
+	}
+
+	/**
+	 * Execute the task.
+	 *
+	 * @param {object} pResolvedSettings - The task's Settings with incoming
+	 *   State connections already resolved by the engine.
+	 * @param {object} pExecutionContext - Runtime context:
+	 *   GlobalState     {object}  - state shared across all operations
+	 *   OperationState  {object}  - state shared across tasks in this run
+	 *   TaskOutputs     {object}  - keyed by NodeHash, per-task output state
+	 *   StagingPath     {string}  - path to the operation's staging folder
+	 *   OperationHash   {string}  - the operation being executed
+	 *   NodeHash        {string}  - this task node's hash in the graph
+	 *   RunHash         {string}  - the execution run hash
+	 *   RunMode         {string}  - 'production' | 'standard' | 'debug'
+	 *   StateManager    {object}  - reference to the StateManager service
+	 *   TriggeringEventName {string} - the event that triggered this execution
+	 *     (e.g. 'PerformSplit', 'StepComplete') — lets state-machine tasks
+	 *     distinguish which input event caused the current invocation.
+	 * @param {function} fCallback - function(pError, pResult) where pResult is:
+	 *   EventToFire  {string}  - which output event to fire (e.g. 'ReadComplete')
+	 *   Outputs      {object}  - key/value pairs written to TaskOutputs[NodeHash]
+	 *   Log          {Array}   - array of log message strings
+	 * @param {function} [fFireIntermediateEvent] - Optional. For re-entrant
+	 *   tasks (like split-execute) that fire events multiple times.
+	 *   Signature: fFireIntermediateEvent(pEventName, pOutputs, fResumeCallback)
+	 */
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		return fCallback(new Error(`Task type "${this.definition.Hash}" has not implemented execute().`));
+	}
+
+	/**
+	 * Resolve a file path relative to the staging folder if it is not absolute.
+	 *
+	 * @param {string} pFilePath - The file path from settings.
+	 * @param {string} pStagingPath - The operation's staging folder.
+	 * @returns {string} Resolved absolute path.
+	 */
+	resolveFilePath(pFilePath, pStagingPath)
+	{
+		if (!pFilePath || typeof(pFilePath) !== 'string')
+		{
+			return pStagingPath || '';
+		}
+
+		const libPath = require('path');
+
+		if (libPath.isAbsolute(pFilePath))
+		{
+			return pFilePath;
+		}
+
+		return libPath.resolve(pStagingPath || process.cwd(), pFilePath);
+	}
+}
+
+module.exports = UltravisorTaskType;

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

@@ -0,0 +1,148 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * IfConditional Task Type
+ *
+ * Evaluates a simple expression and fires either the True or False event.
+ * Supports comparisons via DataAddress and CompareValue, or a direct Expression string.
+ *
+ * If DataAddress is set, reads the value at that address and compares
+ * it to CompareValue using the Operator (default: '==').
+ *
+ * If Expression is set instead, evaluates it using fable.ExpressionParser.
+ */
+class UltravisorTaskTypeIfConditional extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeIfConditional';
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'if-conditional',
+			Type: 'if-conditional',
+			Name: 'If Conditional',
+			Description: 'Evaluates a condition and branches execution to True or False.',
+			Category: 'control',
+
+			EventInputs: [{ Name: 'Evaluate' }],
+			EventOutputs: [
+				{ Name: 'True' },
+				{ Name: 'False' }
+			],
+			SettingsInputs: [
+				{ Name: 'DataAddress', DataType: 'String', Required: false },
+				{ Name: 'CompareValue', DataType: 'String', Required: false },
+				{ Name: 'Operator', DataType: 'String', Required: false },
+				{ Name: 'Expression', DataType: 'String', Required: false }
+			],
+			StateOutputs: [
+				{ Name: 'Result', DataType: 'Boolean' }
+			],
+
+			DefaultSettings: { DataAddress: '', CompareValue: '', Operator: '==', Expression: '' }
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpResult = false;
+
+		if (pResolvedSettings.Expression && typeof(pResolvedSettings.Expression) === 'string')
+		{
+			// Expression-based evaluation using Fable's ExpressionParser
+			try
+			{
+				if (this.fable.ExpressionParser)
+				{
+					tmpResult = this.fable.ExpressionParser.resolve(pResolvedSettings.Expression, pExecutionContext);
+				}
+				else
+				{
+					// Simple truthy evaluation fallback
+					tmpResult = !!pResolvedSettings.Expression;
+				}
+			}
+			catch (pError)
+			{
+				return fCallback(null, {
+					EventToFire: 'False',
+					Outputs: { Result: false },
+					Log: [`Expression error: ${pError.message}`]
+				});
+			}
+		}
+		else if (pResolvedSettings.DataAddress)
+		{
+			// Address-based comparison
+			let tmpDataValue = undefined;
+			let tmpStateManager = pExecutionContext.StateManager;
+
+			if (tmpStateManager)
+			{
+				tmpDataValue = tmpStateManager.resolveAddress(
+					pResolvedSettings.DataAddress, pExecutionContext, pExecutionContext.NodeHash);
+			}
+
+			let tmpCompareValue = pResolvedSettings.CompareValue;
+			let tmpOperator = pResolvedSettings.Operator || '==';
+
+			tmpResult = this._compare(tmpDataValue, tmpCompareValue, tmpOperator);
+		}
+
+		return fCallback(null, {
+			EventToFire: tmpResult ? 'True' : 'False',
+			Outputs: { Result: tmpResult },
+			Log: [`Condition evaluated to ${tmpResult}.`]
+		});
+	}
+
+	/**
+	 * Compare two values using an operator.
+	 *
+	 * @param {*} pLeft - Left operand.
+	 * @param {*} pRight - Right operand.
+	 * @param {string} pOperator - The comparison operator.
+	 * @returns {boolean} Result of comparison.
+	 */
+	_compare(pLeft, pRight, pOperator)
+	{
+		switch (pOperator)
+		{
+			case '==':
+				return String(pLeft) == String(pRight);
+			case '===':
+				return pLeft === pRight;
+			case '!=':
+				return String(pLeft) != String(pRight);
+			case '!==':
+				return pLeft !== pRight;
+			case '>':
+				return Number(pLeft) > Number(pRight);
+			case '<':
+				return Number(pLeft) < Number(pRight);
+			case '>=':
+				return Number(pLeft) >= Number(pRight);
+			case '<=':
+				return Number(pLeft) <= Number(pRight);
+			case 'contains':
+				return String(pLeft).indexOf(String(pRight)) > -1;
+			case 'startsWith':
+				return String(pLeft).startsWith(String(pRight));
+			case 'endsWith':
+				return String(pLeft).endsWith(String(pRight));
+			case 'truthy':
+				return !!pLeft;
+			case 'falsy':
+				return !pLeft;
+			default:
+				return String(pLeft) == String(pRight);
+		}
+	}
+}
+
+module.exports = UltravisorTaskTypeIfConditional;