ultravisor 1.0.2 → 1.0.4

package/source/services/events/Ultravisor-Hypervisor-Event-Solver.cjs

@@ -1,11 +0,0 @@
-const libUltravisorEventBase = require(`../Ultravisor-Hypervisor-Event-Base.cjs`);
-
-class UltravisorEventSolver extends libUltravisorEventBase
-{
-	constructor(pPict, pOptions, pServiceHash)
-	{
-		super(pPict, pOptions, pServiceHash);
-	}
-}
-
-module.exports = UltravisorEventSolver;

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

@@ -1,264 +0,0 @@
-const libFS = require('fs');
-const libPath = require('path');
-
-class UltravisorTaskBase
-{
-	constructor(pFable)
-	{
-		this.fable = pFable;
-		this.log = pFable.log;
-
-		this._Manyfest = this.fable.newManyfest();
-	}
-
-	/**
-	 * Execute the task type logic.
-	 * Subclasses must override this method.
-	 */
-	execute(pTaskDefinition, pContext, pManifestEntry, fCallback)
-	{
-		pManifestEntry.StopTime = new Date().toISOString();
-		pManifestEntry.Status = 'Unsupported';
-		pManifestEntry.Log.push(`Task type not implemented in base class.`);
-		return fCallback(null, pManifestEntry);
-	}
-
-	/**
-	 * Resolve the staging folder path.
-	 *
-	 * Priority:
-	 *   1. pContext.StagingPath (per-operation override)
-	 *   2. UltravisorFileStorePath from ProgramConfiguration
-	 *   3. ${cwd}/dist/ultravisor_datastore (fallback)
-	 *
-	 * @param {object} pContext - Execution context.
-	 * @returns {string} Absolute path to the staging folder.
-	 */
-	resolveStagingPath(pContext)
-	{
-		if (pContext && pContext.StagingPath && pContext.StagingPath.length > 0)
-		{
-			return pContext.StagingPath;
-		}
-		return (this.fable?.ProgramConfiguration?.UltravisorFileStorePath)
-			|| `${process.cwd()}/dist/ultravisor_datastore`;
-	}
-
-	/**
-	 * Build a full file path inside the staging folder.
-	 * Prevents path traversal by rejecting paths containing "..".
-	 *
-	 * @param {string} pStagingPath - Base staging folder.
-	 * @param {string} pFileName - Relative file name or path.
-	 * @returns {string|false} Full path or false if invalid.
-	 */
-	resolveStagingFilePath(pStagingPath, pFileName)
-	{
-		if (!pFileName || typeof(pFileName) !== 'string' || pFileName.length === 0)
-		{
-			return false;
-		}
-		if (pFileName.indexOf('..') !== -1)
-		{
-			return false;
-		}
-		return libPath.resolve(pStagingPath, pFileName);
-	}
-
-	/**
-	 * Resolve a dot-notation address from the execution context.
-	 *
-	 * Looks up the address in:
-	 *   1. pContext.GlobalState
-	 *   2. pContext.NodeState
-	 *
-	 * @param {string} pAddress - Dot-notation path (e.g. "Flags.Enabled").
-	 * @param {object} pContext - Execution context.
-	 * @returns {*} The resolved value, or undefined if not found.
-	 */
-	resolveAddress(pAddress, pContext)
-	{
-		if (!pAddress || !pContext)
-		{
-			return undefined;
-		}
-
-		let tmpParts = pAddress.split('.');
-
-		// Try GlobalState first
-		let tmpValue = this.walkObject(pContext.GlobalState, tmpParts);
-		if (tmpValue !== undefined)
-		{
-			return tmpValue;
-		}
-
-		// Fall back to NodeState
-		return this.walkObject(pContext.NodeState, tmpParts);
-	}
-
-	/**
-	 * Walk an object by a path array.
-	 *
-	 * @param {object} pObject - Object to walk.
-	 * @param {array} pParts - Array of keys.
-	 * @returns {*} Value at the path, or undefined.
-	 */
-	walkObject(pObject, pParts)
-	{
-		if (!pObject || typeof(pObject) !== 'object')
-		{
-			return undefined;
-		}
-
-		let tmpCurrent = pObject;
-		for (let i = 0; i < pParts.length; i++)
-		{
-			if (tmpCurrent === null || tmpCurrent === undefined || typeof(tmpCurrent) !== 'object')
-			{
-				return undefined;
-			}
-			tmpCurrent = tmpCurrent[pParts[i]];
-		}
-
-		return tmpCurrent;
-	}
-
-	// =========================================================================
-	// Destination -- store task output at a manyfest address in GlobalState
-	// =========================================================================
-
-	/**
-	 * Store the task output at a manyfest address in pContext.GlobalState.
-	 *
-	 * The address is taken from pTaskDefinition.Destination.  If Destination
-	 * is not set, the data is stored at "Output" (the default address).
-	 *
-	 * This provides a consistent way for all Read and Get task types to
-	 * declare where their data goes in the operation's shared state.
-	 *
-	 * @param {object} pTaskDefinition - The task definition (checked for .Destination).
-	 * @param {object} pContext - Execution context (GlobalState).
-	 * @param {object} pManifestEntry - The manifest entry (for logging).
-	 * @param {*} pData - The data to store.
-	 */
-	storeDestination(pTaskDefinition, pContext, pManifestEntry, pData)
-	{
-		let tmpDestination = (pTaskDefinition.Destination && typeof(pTaskDefinition.Destination) === 'string' && pTaskDefinition.Destination.length > 0)
-			? pTaskDefinition.Destination
-			: 'Output';
-
-		if (!pContext.GlobalState || typeof(pContext.GlobalState) !== 'object')
-		{
-			pContext.GlobalState = {};
-		}
-
-		this._Manyfest.setValueAtAddress(pContext.GlobalState, tmpDestination, pData);
-		pManifestEntry.Log.push(`Destination: stored result at "${tmpDestination}".`);
-	}
-
-	// =========================================================================
-	// Persist -- store task output to state address or staging file
-	// =========================================================================
-
-	/**
-	 * Persist task output according to the Persist parameter on the task
-	 * definition.
-	 *
-	 * Persist can be:
-	 *   - A manyfest address string (dot-notation) -- stores pData into
-	 *     pContext.GlobalState at that address.
-	 *   - An object with:
-	 *       { "Address": "Some.State.Path" } -- same as the string form
-	 *       { "File": "relative/path.json" } -- writes pData as JSON to
-	 *           a file relative to the staging folder
-	 *       { "File": "relative/path.bin" } -- writes pData as a Buffer
-	 *           to a file relative to the staging folder (for binary data)
-	 *
-	 * @param {object} pTaskDefinition - The task definition (checked for .Persist).
-	 * @param {object} pContext - Execution context (GlobalState, StagingPath).
-	 * @param {object} pManifestEntry - The manifest entry (for logging).
-	 * @param {*} pData - The data to persist (string, object, or Buffer).
-	 */
-	storeResult(pTaskDefinition, pContext, pManifestEntry, pData)
-	{
-		if (!pTaskDefinition.Persist)
-		{
-			return;
-		}
-
-		let tmpPersist = pTaskDefinition.Persist;
-
-		// String form -- treat as a manyfest address into GlobalState
-		if (typeof(tmpPersist) === 'string' && tmpPersist.length > 0)
-		{
-			if (!pContext.GlobalState || typeof(pContext.GlobalState) !== 'object')
-			{
-				pContext.GlobalState = {};
-			}
-			this._Manyfest.setValueAtAddress(pContext.GlobalState, tmpPersist, pData);
-			pManifestEntry.Log.push(`Persist: stored result at state address "${tmpPersist}".`);
-			return;
-		}
-
-		if (typeof(tmpPersist) !== 'object' || tmpPersist === null)
-		{
-			pManifestEntry.Log.push(`Persist: invalid Persist value (expected string or object).`);
-			return;
-		}
-
-		// Object form with Address -- store in GlobalState
-		if (tmpPersist.Address && typeof(tmpPersist.Address) === 'string')
-		{
-			if (!pContext.GlobalState || typeof(pContext.GlobalState) !== 'object')
-			{
-				pContext.GlobalState = {};
-			}
-			this._Manyfest.setValueAtAddress(pContext.GlobalState, tmpPersist.Address, pData);
-			pManifestEntry.Log.push(`Persist: stored result at state address "${tmpPersist.Address}".`);
-			return;
-		}
-
-		// Object form with File -- write to staging folder
-		if (tmpPersist.File && typeof(tmpPersist.File) === 'string')
-		{
-			let tmpStagingPath = this.resolveStagingPath(pContext);
-			let tmpFilePath = this.resolveStagingFilePath(tmpStagingPath, tmpPersist.File);
-
-			if (!tmpFilePath)
-			{
-				pManifestEntry.Log.push(`Persist: invalid file path "${tmpPersist.File}".`);
-				return;
-			}
-
-			try
-			{
-				let tmpDir = libPath.dirname(tmpFilePath);
-				if (!libFS.existsSync(tmpDir))
-				{
-					libFS.mkdirSync(tmpDir, { recursive: true });
-				}
-
-				if (Buffer.isBuffer(pData))
-				{
-					libFS.writeFileSync(tmpFilePath, pData);
-					pManifestEntry.Log.push(`Persist: wrote ${pData.length} bytes (binary) to "${tmpPersist.File}".`);
-				}
-				else
-				{
-					let tmpContent = (typeof(pData) === 'string') ? pData : JSON.stringify(pData, null, 4);
-					libFS.writeFileSync(tmpFilePath, tmpContent, 'utf8');
-					pManifestEntry.Log.push(`Persist: wrote ${tmpContent.length} bytes to "${tmpPersist.File}".`);
-				}
-			}
-			catch (pError)
-			{
-				pManifestEntry.Log.push(`Persist: error writing to file: ${pError.message}`);
-			}
-			return;
-		}
-
-		pManifestEntry.Log.push(`Persist: object must have an "Address" or "File" property.`);
-	}
-}
-
-module.exports = UltravisorTaskBase;

package/source/services/tasks/Ultravisor-Task-CollectValues.cjs

@@ -1,188 +0,0 @@
-const libUltravisorTaskBase = require('./Ultravisor-Task-Base.cjs');
-
-class UltravisorTaskCollectValues extends libUltravisorTaskBase
-{
-	constructor(pFable)
-	{
-		super(pFable);
-	}
-
-	/**
-	 * Collect and extract field values from arrays in GlobalState.
-	 *
-	 * Designed to work with GeneratePagedOperation output but is
-	 * general-purpose.  Iterates over a source array, optionally
-	 * navigates into each element via RecordPath, then plucks the
-	 * specified Field from every record found.
-	 *
-	 * Task definition fields:
-	 *   - Address: manyfest address in GlobalState pointing to the
-	 *       source array (e.g. "Pages").
-	 *   - Field: the field name to extract from each record.  Supports
-	 *       dot-notation for nested fields (e.g. "Details.ID").
-	 *   - RecordPath (optional): dot-notation path within each element
-	 *       to reach the array of records (e.g. "JSON.records" for
-	 *       RestRequest results).  If omitted, each element is treated
-	 *       as the array itself (or as a single record if it is an
-	 *       object).
-	 *   - Unique (optional, default false): if true, deduplicate the
-	 *       output array.
-	 *   - Flatten (optional, default true): if true, flatten nested
-	 *       arrays into a single flat array.
-	 *   - Destination (optional): manyfest address in GlobalState
-	 *       where the result array is stored (default: "Output").
-	 *   - Persist (optional): standard persist options (file or address).
-	 */
-	execute(pTaskDefinition, pContext, pManifestEntry, fCallback)
-	{
-		// --- Validate required fields ---
-		if (!pTaskDefinition.Address || typeof(pTaskDefinition.Address) !== 'string' || pTaskDefinition.Address.length === 0)
-		{
-			pManifestEntry.StopTime = new Date().toISOString();
-			pManifestEntry.Status = 'Error';
-			pManifestEntry.Log.push(`CollectValues: missing or empty Address field.`);
-			return fCallback(null, pManifestEntry);
-		}
-
-		if (!pTaskDefinition.Field || typeof(pTaskDefinition.Field) !== 'string' || pTaskDefinition.Field.length === 0)
-		{
-			pManifestEntry.StopTime = new Date().toISOString();
-			pManifestEntry.Status = 'Error';
-			pManifestEntry.Log.push(`CollectValues: missing or empty Field field.`);
-			return fCallback(null, pManifestEntry);
-		}
-
-		// --- Resolve source data ---
-		let tmpSource = this.resolveAddress(pTaskDefinition.Address, pContext);
-
-		if (tmpSource === undefined || tmpSource === null)
-		{
-			pManifestEntry.StopTime = new Date().toISOString();
-			pManifestEntry.Status = 'Complete';
-			pManifestEntry.Success = true;
-			pManifestEntry.Output = '[]';
-			pManifestEntry.Log.push(`CollectValues: Address "${pTaskDefinition.Address}" resolved to null or undefined; treating as empty set.`);
-			this.storeDestination(pTaskDefinition, pContext, pManifestEntry, []);
-			return fCallback(null, pManifestEntry);
-		}
-
-		// If the source is not an array, wrap it so we can iterate uniformly
-		if (!Array.isArray(tmpSource))
-		{
-			if (typeof(tmpSource) === 'object')
-			{
-				tmpSource = [tmpSource];
-				pManifestEntry.Log.push(`CollectValues: source is a single object; wrapped in array.`);
-			}
-			else
-			{
-				pManifestEntry.StopTime = new Date().toISOString();
-				pManifestEntry.Status = 'Error';
-				pManifestEntry.Log.push(`CollectValues: Address "${pTaskDefinition.Address}" did not resolve to an array or object.`);
-				return fCallback(null, pManifestEntry);
-			}
-		}
-
-		pManifestEntry.Log.push(`CollectValues: source has ${tmpSource.length} element(s).`);
-
-		let tmpFieldParts = pTaskDefinition.Field.split('.');
-		let tmpRecordPathParts = (pTaskDefinition.RecordPath && typeof(pTaskDefinition.RecordPath) === 'string' && pTaskDefinition.RecordPath.length > 0)
-			? pTaskDefinition.RecordPath.split('.')
-			: null;
-
-		let tmpFlatten = (pTaskDefinition.Flatten !== false);
-		let tmpUnique = (pTaskDefinition.Unique === true);
-
-		// --- Iterate over each element in the source ---
-		let tmpCollected = [];
-
-		for (let i = 0; i < tmpSource.length; i++)
-		{
-			let tmpElement = tmpSource[i];
-
-			if (tmpElement === null || tmpElement === undefined)
-			{
-				pManifestEntry.Log.push(`CollectValues: skipping null/undefined element at index ${i}.`);
-				continue;
-			}
-
-			// If RecordPath is set, navigate into the element to find the records
-			let tmpRecords = tmpElement;
-
-			if (tmpRecordPathParts)
-			{
-				tmpRecords = this.walkObject(tmpElement, tmpRecordPathParts);
-
-				if (tmpRecords === undefined || tmpRecords === null)
-				{
-					pManifestEntry.Log.push(`CollectValues: RecordPath "${pTaskDefinition.RecordPath}" resolved to null at index ${i}, skipping.`);
-					continue;
-				}
-			}
-
-			// Normalize to an array of records
-			if (!Array.isArray(tmpRecords))
-			{
-				if (typeof(tmpRecords) === 'object')
-				{
-					tmpRecords = [tmpRecords];
-				}
-				else
-				{
-					pManifestEntry.Log.push(`CollectValues: element at index ${i} is not an array or object after RecordPath, skipping.`);
-					continue;
-				}
-			}
-
-			// Pluck the field from each record
-			for (let j = 0; j < tmpRecords.length; j++)
-			{
-				let tmpRecord = tmpRecords[j];
-
-				if (tmpRecord === null || tmpRecord === undefined || typeof(tmpRecord) !== 'object')
-				{
-					continue;
-				}
-
-				let tmpValue = this.walkObject(tmpRecord, tmpFieldParts);
-
-				if (tmpValue !== undefined)
-				{
-					tmpCollected.push(tmpValue);
-				}
-			}
-		}
-
-		pManifestEntry.Log.push(`CollectValues: collected ${tmpCollected.length} value(s) from field "${pTaskDefinition.Field}".`);
-
-		// --- Flatten ---
-		if (tmpFlatten)
-		{
-			tmpCollected = tmpCollected.flat(Infinity);
-		}
-
-		// --- Deduplicate ---
-		if (tmpUnique)
-		{
-			let tmpBefore = tmpCollected.length;
-			tmpCollected = [...new Set(tmpCollected)];
-			if (tmpCollected.length < tmpBefore)
-			{
-				pManifestEntry.Log.push(`CollectValues: deduplicated from ${tmpBefore} to ${tmpCollected.length} value(s).`);
-			}
-		}
-
-		// --- Store results ---
-		pManifestEntry.StopTime = new Date().toISOString();
-		pManifestEntry.Status = 'Complete';
-		pManifestEntry.Success = true;
-		pManifestEntry.Output = JSON.stringify(tmpCollected);
-
-		this.storeDestination(pTaskDefinition, pContext, pManifestEntry, tmpCollected);
-		this.storeResult(pTaskDefinition, pContext, pManifestEntry, tmpCollected);
-
-		return fCallback(null, pManifestEntry);
-	}
-}
-
-module.exports = UltravisorTaskCollectValues;

package/source/services/tasks/Ultravisor-Task-Command.cjs

@@ -1,65 +0,0 @@
-const libUltravisorTaskBase = require('./Ultravisor-Task-Base.cjs');
-
-const libChildProcess = require('child_process');
-
-class UltravisorTaskCommand extends libUltravisorTaskBase
-{
-	constructor(pFable)
-	{
-		super(pFable);
-	}
-
-	/**
-	 * Execute a shell command task.
-	 */
-	execute(pTaskDefinition, pContext, pManifestEntry, fCallback)
-	{
-		let tmpCommand = pTaskDefinition.Command || pTaskDefinition.Parameters || '';
-
-		if (!tmpCommand || tmpCommand.length === 0)
-		{
-			pManifestEntry.StopTime = new Date().toISOString();
-			pManifestEntry.Status = 'Error';
-			pManifestEntry.Log.push(`Command task has no command to execute.`);
-			return fCallback(null, pManifestEntry);
-		}
-
-		pManifestEntry.Log.push(`Executing command: ${tmpCommand}`);
-
-		let tmpTimeout = (this.fable?.ProgramConfiguration?.UltravisorCommandTimeoutMilliseconds) || 300000;
-		let tmpMaxBuffer = (this.fable?.ProgramConfiguration?.UltravisorCommandMaxBufferBytes) || 10485760;
-
-		libChildProcess.exec(tmpCommand, { timeout: tmpTimeout, maxBuffer: tmpMaxBuffer },
-			(pError, pStdOut, pStdErr) =>
-			{
-				pManifestEntry.StopTime = new Date().toISOString();
-
-				if (pStdOut)
-				{
-					pManifestEntry.Output = pStdOut;
-					pManifestEntry.Log.push(`stdout: ${pStdOut.substring(0, 500)}`);
-				}
-				if (pStdErr)
-				{
-					pManifestEntry.Log.push(`stderr: ${pStdErr.substring(0, 500)}`);
-				}
-
-				if (pError)
-				{
-					pManifestEntry.Status = 'Error';
-					pManifestEntry.Success = false;
-					pManifestEntry.Log.push(`Command failed: ${pError.message}`);
-				}
-				else
-				{
-					pManifestEntry.Status = 'Complete';
-					pManifestEntry.Success = true;
-					pManifestEntry.Log.push(`Command completed successfully.`);
-				}
-
-				return fCallback(null, pManifestEntry);
-			});
-	}
-}
-
-module.exports = UltravisorTaskCommand;