ultravisor 1.0.2 → 1.0.4

package/source/services/tasks/file-io/Ultravisor-TaskType-ReadFile.cjs

@@ -0,0 +1,103 @@
+const libUltravisorTaskType = require('../Ultravisor-TaskType-Base.cjs');
+const libFS = require('fs');
+
+/**
+ * Read File task type.
+ *
+ * Reads a file from disk into state. The file path can be absolute or
+ * relative to the operation's staging folder.
+ */
+class UltravisorTaskTypeReadFile extends libUltravisorTaskType
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'read-file',
+			Name: 'Read File',
+			Description: 'Reads a file from disk into state.',
+			Category: 'file-io',
+
+			EventInputs:
+			[
+				{ Name: 'BeginRead', Description: 'Triggers the file read' }
+			],
+			EventOutputs:
+			[
+				{ Name: 'ReadComplete', Description: 'Fires when file is read successfully' },
+				{ Name: 'Error', Description: 'Fires on read failure', IsError: true }
+			],
+			SettingsInputs:
+			[
+				{ Name: 'FilePath', DataType: 'String', Required: true, Description: 'Path to the file to read' },
+				{ Name: 'Encoding', DataType: 'String', Required: false, Default: 'utf8', Description: 'File encoding' }
+			],
+			StateOutputs:
+			[
+				{ Name: 'FileContent', DataType: 'String', Description: 'Contents of the file' },
+				{ Name: 'BytesRead', DataType: 'Number', Description: 'Number of bytes read' }
+			],
+
+			DefaultSettings:
+			{
+				FilePath: '',
+				Encoding: 'utf8'
+			}
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpFilePath = pResolvedSettings.FilePath || '';
+		let tmpEncoding = pResolvedSettings.Encoding || 'utf8';
+
+		if (!tmpFilePath)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: ['ReadFile: no FilePath specified.']
+			});
+		}
+
+		// Resolve relative paths against the staging folder
+		tmpFilePath = this.resolveFilePath(tmpFilePath, pExecutionContext.StagingPath);
+
+		try
+		{
+			let tmpContent = libFS.readFileSync(tmpFilePath, tmpEncoding);
+
+			// Write output to the configured address if specified
+			let tmpStateWrites = {};
+			if (pResolvedSettings.OutputAddress)
+			{
+				tmpStateWrites[pResolvedSettings.OutputAddress] = tmpContent;
+			}
+
+			return fCallback(null, {
+				EventToFire: 'ReadComplete',
+				Outputs:
+				{
+					FileContent: tmpContent,
+					BytesRead: Buffer.byteLength(tmpContent, tmpEncoding)
+				},
+				StateWrites: tmpStateWrites,
+				Log: [`ReadFile: read ${Buffer.byteLength(tmpContent, tmpEncoding)} bytes from ${tmpFilePath}`]
+			});
+		}
+		catch (pError)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: [`ReadFile: failed to read ${tmpFilePath}: ${pError.message}`]
+			});
+		}
+	}
+}
+
+module.exports = UltravisorTaskTypeReadFile;

package/source/services/tasks/file-io/Ultravisor-TaskType-WriteFile.cjs

@@ -0,0 +1,117 @@
+const libUltravisorTaskType = require('../Ultravisor-TaskType-Base.cjs');
+const libFS = require('fs');
+const libPath = require('path');
+
+/**
+ * Write File task type.
+ *
+ * Writes content from state to a file on disk. The file path can be
+ * absolute or relative to the operation's staging folder.
+ */
+class UltravisorTaskTypeWriteFile extends libUltravisorTaskType
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'write-file',
+			Name: 'Write File',
+			Description: 'Writes content to a file on disk.',
+			Category: 'file-io',
+
+			EventInputs:
+			[
+				{ Name: 'BeginWrite', Description: 'Triggers the file write' }
+			],
+			EventOutputs:
+			[
+				{ Name: 'WriteComplete', Description: 'Fires when file is written successfully' },
+				{ Name: 'Error', Description: 'Fires on write failure', IsError: true }
+			],
+			SettingsInputs:
+			[
+				{ 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, Default: 'utf8', Description: 'File encoding' }
+			],
+			StateOutputs:
+			[
+				{ Name: 'BytesWritten', DataType: 'Number', Description: 'Number of bytes written' }
+			],
+
+			DefaultSettings:
+			{
+				FilePath: '',
+				Content: '',
+				Encoding: 'utf8'
+			}
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpFilePath = pResolvedSettings.FilePath || '';
+		let tmpContent = pResolvedSettings.Content;
+		let tmpEncoding = pResolvedSettings.Encoding || 'utf8';
+
+		if (!tmpFilePath)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: ['WriteFile: no FilePath specified.']
+			});
+		}
+
+		if (tmpContent === undefined || tmpContent === null)
+		{
+			tmpContent = '';
+		}
+
+		// Ensure content is a string
+		if (typeof(tmpContent) !== 'string')
+		{
+			tmpContent = JSON.stringify(tmpContent, null, '\t');
+		}
+
+		// Resolve relative paths against the staging folder
+		tmpFilePath = this.resolveFilePath(tmpFilePath, pExecutionContext.StagingPath);
+
+		try
+		{
+			// Ensure the directory exists
+			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, {
+				EventToFire: 'WriteComplete',
+				Outputs:
+				{
+					BytesWritten: tmpBytesWritten
+				},
+				Log: [`WriteFile: wrote ${tmpBytesWritten} bytes to ${tmpFilePath}`]
+			});
+		}
+		catch (pError)
+		{
+			return fCallback(null, {
+				EventToFire: 'Error',
+				Outputs: {},
+				Log: [`WriteFile: failed to write ${tmpFilePath}: ${pError.message}`]
+			});
+		}
+	}
+}
+
+module.exports = UltravisorTaskTypeWriteFile;

package/source/services/tasks/interaction/Ultravisor-TaskType-ErrorMessage.cjs

@@ -0,0 +1,54 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * ErrorMessage Task Type
+ *
+ * Logs an error/warning message to the execution context.
+ * Useful for dead-end branches or error handling paths.
+ * The MessageTemplate can contain {~D:Address~} patterns
+ * that are resolved against the execution context.
+ */
+class UltravisorTaskTypeErrorMessage extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeErrorMessage';
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'error-message',
+			Type: 'error-message',
+			Name: 'Error Message',
+			Description: 'Logs an error or warning message to the execution log.',
+			Category: 'interaction',
+
+			EventInputs: [{ Name: 'Trigger' }],
+			EventOutputs: [{ Name: 'Complete' }],
+			SettingsInputs: [
+				{ Name: 'MessageTemplate', DataType: 'String', Required: true }
+			],
+			StateOutputs: [],
+
+			DefaultSettings: { MessageTemplate: 'An error occurred.' }
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpMessage = pResolvedSettings.MessageTemplate || 'An error occurred.';
+
+		this.log.error(`ErrorMessage task [${pExecutionContext.NodeHash}]: ${tmpMessage}`);
+
+		return fCallback(null, {
+			EventToFire: 'Complete',
+			Outputs: {},
+			Log: [`ERROR: ${tmpMessage}`]
+		});
+	}
+}
+
+module.exports = UltravisorTaskTypeErrorMessage;

package/source/services/tasks/interaction/Ultravisor-TaskType-ValueInput.cjs

@@ -0,0 +1,62 @@
+const libTaskTypeBase = require('../Ultravisor-TaskType-Base.cjs');
+
+/**
+ * ValueInput Task Type
+ *
+ * Pauses operation execution and waits for user input.
+ * When triggered, sets the run to WaitingForInput status.
+ * The ExecutionEngine resumes when input is provided via
+ * POST /Run/:RunHash/Input/:NodeHash.
+ *
+ * The provided value is written to the specified OutputAddress.
+ */
+class UltravisorTaskTypeValueInput extends libTaskTypeBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'UltravisorTaskTypeValueInput';
+	}
+
+	get definition()
+	{
+		return {
+			Hash: 'value-input',
+			Type: 'value-input',
+			Name: 'Value Input',
+			Description: 'Pauses execution and waits for user-provided input.',
+			Category: 'interaction',
+
+			EventInputs: [{ Name: 'RequestInput' }],
+			EventOutputs: [{ Name: 'ValueInputComplete' }],
+			SettingsInputs: [
+				{ Name: 'PromptMessage', DataType: 'String', Required: false },
+				{ Name: 'OutputAddress', DataType: 'String', Required: true }
+			],
+			StateOutputs: [
+				{ Name: 'InputValue', DataType: 'String' }
+			],
+
+			DefaultSettings: { PromptMessage: 'Please provide a value:', OutputAddress: '' }
+		};
+	}
+
+	execute(pResolvedSettings, pExecutionContext, fCallback, fFireIntermediateEvent)
+	{
+		let tmpPromptMessage = pResolvedSettings.PromptMessage || 'Please provide a value:';
+		let tmpOutputAddress = pResolvedSettings.OutputAddress || '';
+
+		// Signal that this task is waiting for input
+		// The ExecutionEngine will set the run to WaitingForInput status
+		return fCallback(null, {
+			WaitingForInput: true,
+			PromptMessage: tmpPromptMessage,
+			OutputAddress: tmpOutputAddress,
+			Outputs: {},
+			Log: [`Waiting for input: "${tmpPromptMessage}" (-> ${tmpOutputAddress})`]
+		});
+	}
+}
+
+module.exports = UltravisorTaskTypeValueInput;