ultravisor 1.0.3 → 1.0.8

package/webinterface/source/data/ExampleFlow-FileProcessor.js

@@ -0,0 +1,315 @@
+/**
+ * Example Flow: File Processor (Search & Replace)
+ *
+ * Demonstrates a complete file processing pipeline with user input, looping,
+ * and error handling:
+ *
+ *   Start
+ *     -> Value Input (ask user for file path, stores to Operation.InputFilePath)
+ *     -> Read File (loads the file at the user-provided path)
+ *         -> [Error] -> Error Message -> End
+ *     -> Split Execute (split file into lines)
+ *         -> [per line] Replace String ("John" -> "Jane")
+ *         -> String Appender (accumulate into Operation.OutputFileContents)
+ *         -> [loop back: Append Completed -> Split StepComplete]
+ *     -> [all lines done] Write File (save to original path + ".ultracopy")
+ *     -> End
+ *
+ * This example showcases:
+ *   - Value input pausing execution for user interaction
+ *   - State connections (data flow between task settings/outputs)
+ *   - The split-execute looping pattern with StepComplete feedback
+ *   - Error branching
+ *   - Pict template expressions for dynamic file paths
+ */
+module.exports =
+{
+	Nodes:
+	[
+		// ── Start ────────────────────────────────────────────────
+		{
+			Hash: 'fp-start',
+			Type: 'start',
+			X: 50,
+			Y: 200,
+			Width: 140,
+			Height: 80,
+			Title: 'Start',
+			Ports:
+			[
+				{ Hash: 'fp-start-out', Direction: 'output', Side: 'right', Label: 'Out' }
+			],
+			Data: {}
+		},
+		// ── Ask user for file path ───────────────────────────────
+		{
+			Hash: 'fp-input',
+			Type: 'value-input',
+			X: 280,
+			Y: 180,
+			Width: 220,
+			Height: 100,
+			Title: 'Enter File Path',
+			Ports:
+			[
+				{ Hash: 'fp-input-req', Direction: 'input', Side: 'left-bottom', Label: 'RequestInput' },
+				{ Hash: 'fp-input-done', Direction: 'output', Side: 'right', Label: 'ValueInputComplete' },
+				{ Hash: 'fp-input-filepath', Direction: 'output', Side: 'right-top', Label: 'InputFilePath' }
+			],
+			Data: { PromptMessage: 'Enter a file path and name', OutputAddress: 'Operation.InputFilePath' }
+		},
+		// ── Load the file ────────────────────────────────────────
+		{
+			Hash: 'fp-read',
+			Type: 'read-file',
+			X: 590,
+			Y: 180,
+			Width: 200,
+			Height: 100,
+			Title: 'Load File',
+			Ports:
+			[
+				{ Hash: 'fp-read-begin', Direction: 'input', Side: 'left-bottom', Label: 'BeginRead' },
+				{ Hash: 'fp-read-filepath', Direction: 'input', Side: 'left-top', Label: 'FilePath' },
+				{ Hash: 'fp-read-done', Direction: 'output', Side: 'right', Label: 'ReadComplete' },
+				{ Hash: 'fp-read-content', Direction: 'output', Side: 'right-top', Label: 'FileContent' },
+				{ Hash: 'fp-read-err', Direction: 'output', Side: 'bottom', Label: 'Error' }
+			],
+			Data: { FilePath: '{~D:Record.Operation.InputFilePath~}', Encoding: 'utf8' }
+		},
+		// ── Error handler for file read ──────────────────────────
+		{
+			Hash: 'fp-error',
+			Type: 'error-message',
+			X: 590,
+			Y: 420,
+			Width: 220,
+			Height: 80,
+			Title: 'Read Error',
+			Ports:
+			[
+				{ Hash: 'fp-error-in', Direction: 'input', Side: 'left-bottom', Label: 'Trigger' },
+				{ Hash: 'fp-error-done', Direction: 'output', Side: 'right', Label: 'Complete' }
+			],
+			Data: { MessageTemplate: 'Failed to read file: {~D:Record.Operation.InputFilePath~}' }
+		},
+		// ── Split file into lines ────────────────────────────────
+		{
+			Hash: 'fp-split',
+			Type: 'split-execute',
+			X: 890,
+			Y: 160,
+			Width: 240,
+			Height: 120,
+			Title: 'Split Lines',
+			Ports:
+			[
+				{ Hash: 'fp-split-begin', Direction: 'input', Side: 'left-bottom', Label: 'PerformSplit' },
+				{ Hash: 'fp-split-step', Direction: 'input', Side: 'left-bottom', Label: 'StepComplete' },
+				{ Hash: 'fp-split-inputstr', Direction: 'input', Side: 'left-top', Label: 'InputString' },
+				{ Hash: 'fp-split-token', Direction: 'output', Side: 'right', Label: 'TokenDataSent' },
+				{ Hash: 'fp-split-alldone', Direction: 'output', Side: 'right-bottom', Label: 'CompletedAllSubtasks' }
+			],
+			Data: { InputString: '{~D:Record.TaskOutput.fp-read.FileContent~}', SplitDelimiter: '\n' }
+		},
+		// ── Replace "John" with "Jane" in each line ──────────────
+		{
+			Hash: 'fp-replace',
+			Type: 'replace-string',
+			X: 1230,
+			Y: 160,
+			Width: 220,
+			Height: 100,
+			Title: 'Replace John with Jane',
+			Ports:
+			[
+				{ Hash: 'fp-replace-in', Direction: 'input', Side: 'left-bottom', Label: 'Replace' },
+				{ Hash: 'fp-replace-done', Direction: 'output', Side: 'right', Label: 'ReplaceComplete' },
+				{ Hash: 'fp-replace-result', Direction: 'output', Side: 'right-top', Label: 'ReplacedString' }
+			],
+			Data: { InputString: '{~D:Record.TaskOutput.fp-split.CurrentToken~}', SearchString: 'John', ReplaceString: 'Jane' }
+		},
+		// ── Append each processed line to output ─────────────────
+		{
+			Hash: 'fp-append',
+			Type: 'string-appender',
+			X: 1540,
+			Y: 160,
+			Width: 220,
+			Height: 100,
+			Title: 'Append Line',
+			Ports:
+			[
+				{ Hash: 'fp-append-in', Direction: 'input', Side: 'left-bottom', Label: 'Append' },
+				{ Hash: 'fp-append-inputstr', Direction: 'input', Side: 'left-top', Label: 'InputString' },
+				{ Hash: 'fp-append-done', Direction: 'output', Side: 'right', Label: 'Completed' }
+			],
+			Data: { InputString: '{~D:Record.TaskOutput.fp-replace.ReplacedString~}', OutputAddress: 'Operation.OutputFileContents', AppendNewline: true }
+		},
+		// ── Write the processed file ─────────────────────────────
+		{
+			Hash: 'fp-write',
+			Type: 'write-file',
+			X: 1230,
+			Y: 420,
+			Width: 220,
+			Height: 80,
+			Title: 'Save File',
+			Ports:
+			[
+				{ Hash: 'fp-write-begin', Direction: 'input', Side: 'left-bottom', Label: 'BeginWrite' },
+				{ Hash: 'fp-write-done', Direction: 'output', Side: 'right', Label: 'WriteComplete' },
+				{ Hash: 'fp-write-err', Direction: 'output', Side: 'bottom', Label: 'Error' }
+			],
+			Data: { FilePath: '{~D:Record.Operation.InputFilePath~}.ultracopy', Content: '{~D:Record.Operation.OutputFileContents~}', Encoding: 'utf8' }
+		},
+		// ── End ──────────────────────────────────────────────────
+		{
+			Hash: 'fp-end',
+			Type: 'end',
+			X: 1540,
+			Y: 420,
+			Width: 140,
+			Height: 80,
+			Title: 'End',
+			Ports:
+			[
+				{ Hash: 'fp-end-in', Direction: 'input', Side: 'left-bottom', Label: 'In' }
+			],
+			Data: {}
+		}
+	],
+	Connections:
+	[
+		// ── Event connections (execution flow) ───────────────────
+
+		// Start -> Enter File Path (step 22)
+		{
+			Hash: 'fp-ev1',
+			SourceNodeHash: 'fp-start',
+			SourcePortHash: 'fp-start-out',
+			TargetNodeHash: 'fp-input',
+			TargetPortHash: 'fp-input-req',
+			Data: {}
+		},
+		// Enter File Path -> Load File (step 23)
+		{
+			Hash: 'fp-ev2',
+			SourceNodeHash: 'fp-input',
+			SourcePortHash: 'fp-input-done',
+			TargetNodeHash: 'fp-read',
+			TargetPortHash: 'fp-read-begin',
+			Data: {}
+		},
+		// Load File ReadComplete -> Split Lines PerformSplit (step 24)
+		{
+			Hash: 'fp-ev3',
+			SourceNodeHash: 'fp-read',
+			SourcePortHash: 'fp-read-done',
+			TargetNodeHash: 'fp-split',
+			TargetPortHash: 'fp-split-begin',
+			Data: {}
+		},
+		// Load File Error -> Read Error (step 10)
+		{
+			Hash: 'fp-ev4',
+			SourceNodeHash: 'fp-read',
+			SourcePortHash: 'fp-read-err',
+			TargetNodeHash: 'fp-error',
+			TargetPortHash: 'fp-error-in',
+			Data: {}
+		},
+		// Read Error -> End
+		{
+			Hash: 'fp-ev5',
+			SourceNodeHash: 'fp-error',
+			SourcePortHash: 'fp-error-done',
+			TargetNodeHash: 'fp-end',
+			TargetPortHash: 'fp-end-in',
+			Data: {}
+		},
+		// Split Lines TokenDataSent -> Replace (step 25)
+		{
+			Hash: 'fp-ev6',
+			SourceNodeHash: 'fp-split',
+			SourcePortHash: 'fp-split-token',
+			TargetNodeHash: 'fp-replace',
+			TargetPortHash: 'fp-replace-in',
+			Data: {}
+		},
+		// Replace ReplaceComplete -> Append (step 26)
+		{
+			Hash: 'fp-ev7',
+			SourceNodeHash: 'fp-replace',
+			SourcePortHash: 'fp-replace-done',
+			TargetNodeHash: 'fp-append',
+			TargetPortHash: 'fp-append-in',
+			Data: {}
+		},
+		// Append Completed -> Split StepComplete (loop back for next token)
+		{
+			Hash: 'fp-ev8',
+			SourceNodeHash: 'fp-append',
+			SourcePortHash: 'fp-append-done',
+			TargetNodeHash: 'fp-split',
+			TargetPortHash: 'fp-split-step',
+			Data: {}
+		},
+		// Split Lines CompletedAllSubtasks -> Save File
+		{
+			Hash: 'fp-ev9',
+			SourceNodeHash: 'fp-split',
+			SourcePortHash: 'fp-split-alldone',
+			TargetNodeHash: 'fp-write',
+			TargetPortHash: 'fp-write-begin',
+			Data: {}
+		},
+		// Save File WriteComplete -> End (step 21)
+		{
+			Hash: 'fp-ev10',
+			SourceNodeHash: 'fp-write',
+			SourcePortHash: 'fp-write-done',
+			TargetNodeHash: 'fp-end',
+			TargetPortHash: 'fp-end-in',
+			Data: {}
+		},
+
+		// ── State connections (data flow) ────────────────────────
+
+		// Enter File Path OutputAddress -> Load File FilePath (step 8)
+		{
+			Hash: 'fp-st1',
+			SourceNodeHash: 'fp-input',
+			SourcePortHash: 'fp-input-filepath',
+			TargetNodeHash: 'fp-read',
+			TargetPortHash: 'fp-read-filepath',
+			Data: {}
+		},
+		// Load File FileContent -> Split Lines InputString (step 13)
+		{
+			Hash: 'fp-st2',
+			SourceNodeHash: 'fp-read',
+			SourcePortHash: 'fp-read-content',
+			TargetNodeHash: 'fp-split',
+			TargetPortHash: 'fp-split-inputstr',
+			Data: {}
+		},
+		// Replace ReplacedString -> Append InputString (step 15)
+		{
+			Hash: 'fp-st3',
+			SourceNodeHash: 'fp-replace',
+			SourcePortHash: 'fp-replace-result',
+			TargetNodeHash: 'fp-append',
+			TargetPortHash: 'fp-append-inputstr',
+			Data: {}
+		}
+	],
+	ViewState:
+	{
+		PanX: 0,
+		PanY: 0,
+		Zoom: 1,
+		SelectedNodeHash: null,
+		SelectedConnectionHash: null
+	}
+};

package/webinterface/source/data/ExampleFlow-MeadowPipeline.js

@@ -0,0 +1,328 @@
+/**
+ * Example Flow: Template Processor
+ *
+ * Demonstrates a multi-step text processing pipeline using the new engine task types:
+ *   Start -> Set Values (initialize project metadata)
+ *         -> Read File (template)
+ *         -> Replace String (project name)
+ *         -> Replace String (version)
+ *         -> If Conditional (check for remaining placeholders)
+ *           -> True:  Error Message (warn about unresolved placeholders) -> End
+ *           -> False: String Appender (add header comment) -> Write File (output) -> End
+ *
+ * Shows chained string operations, state management, and conditional validation.
+ */
+module.exports =
+{
+	Nodes:
+	[
+		// ── Entry ────────────────────────────────────────────────
+		{
+			Hash: 'tpl-start',
+			Type: 'start',
+			X: 50,
+			Y: 220,
+			Width: 140,
+			Height: 80,
+			Title: 'Start',
+			Ports:
+			[
+				{ Hash: 'tpl-start-out', Direction: 'output', Side: 'right', Label: 'Out' }
+			],
+			Data: {}
+		},
+		// ── Initialize project metadata ─────────────────────────
+		{
+			Hash: 'tpl-setvals',
+			Type: 'set-values',
+			X: 270,
+			Y: 200,
+			Width: 200,
+			Height: 80,
+			Title: 'Set Project Info',
+			Ports:
+			[
+				{ Hash: 'tpl-sv-in', Direction: 'input', Side: 'left', Label: 'Execute' },
+				{ Hash: 'tpl-sv-out', Direction: 'output', Side: 'right', Label: 'Complete' }
+			],
+			Data:
+			{
+				Mappings:
+				[
+					{ Address: 'Operation.ProjectName', Value: 'Retold' },
+					{ Address: 'Operation.Version', Value: '3.0.0' },
+					{ Address: 'Operation.Author', Value: 'Steven Velozo' }
+				]
+			}
+		},
+		// ── Read the template file ──────────────────────────────
+		{
+			Hash: 'tpl-read',
+			Type: 'read-file',
+			X: 550,
+			Y: 200,
+			Width: 200,
+			Height: 80,
+			Title: 'Read Template',
+			Ports:
+			[
+				{ Hash: 'tpl-read-in', Direction: 'input', Side: 'left', Label: 'BeginRead' },
+				{ Hash: 'tpl-read-done', Direction: 'output', Side: 'right', Label: 'ReadComplete' },
+				{ Hash: 'tpl-read-err', Direction: 'output', Side: 'bottom', Label: 'Error' }
+			],
+			Data: { FilePath: 'readme.template.md', Encoding: 'utf8' }
+		},
+		// ── Replace project name placeholder ────────────────────
+		{
+			Hash: 'tpl-replace-name',
+			Type: 'replace-string',
+			X: 830,
+			Y: 180,
+			Width: 220,
+			Height: 80,
+			Title: 'Set Project Name',
+			Ports:
+			[
+				{ Hash: 'tpl-rn-in', Direction: 'input', Side: 'left', Label: 'Replace' },
+				{ Hash: 'tpl-rn-done', Direction: 'output', Side: 'right', Label: 'ReplaceComplete' },
+				{ Hash: 'tpl-rn-err', Direction: 'output', Side: 'bottom', Label: 'Error' }
+			],
+			Data: { InputString: '{~D:Record.TaskOutput.tpl-read.FileContent~}', SearchString: '${PROJECT_NAME}', ReplaceString: '{~D:Record.Operation.ProjectName~}' }
+		},
+		// ── Replace version placeholder ─────────────────────────
+		{
+			Hash: 'tpl-replace-ver',
+			Type: 'replace-string',
+			X: 1130,
+			Y: 180,
+			Width: 220,
+			Height: 80,
+			Title: 'Set Version',
+			Ports:
+			[
+				{ Hash: 'tpl-rv-in', Direction: 'input', Side: 'left', Label: 'Replace' },
+				{ Hash: 'tpl-rv-done', Direction: 'output', Side: 'right', Label: 'ReplaceComplete' },
+				{ Hash: 'tpl-rv-err', Direction: 'output', Side: 'bottom', Label: 'Error' }
+			],
+			Data: { InputString: '{~D:Record.TaskOutput.tpl-replace-name.ReplacedString~}', SearchString: '${VERSION}', ReplaceString: '{~D:Record.Operation.Version~}' }
+		},
+		// ── Check for remaining unresolved placeholders ─────────
+		{
+			Hash: 'tpl-validate',
+			Type: 'if-conditional',
+			X: 1430,
+			Y: 160,
+			Width: 240,
+			Height: 100,
+			Title: 'Unresolved Placeholders?',
+			Ports:
+			[
+				{ Hash: 'tpl-val-in', Direction: 'input', Side: 'left', Label: 'Evaluate' },
+				{ Hash: 'tpl-val-true', Direction: 'output', Side: 'bottom', Label: 'True' },
+				{ Hash: 'tpl-val-false', Direction: 'output', Side: 'right', Label: 'False' }
+			],
+			Data: { DataAddress: 'TaskOutput.tpl-replace-ver.ReplacedString', CompareValue: '${', Operator: 'contains' }
+		},
+		// ── Error: unresolved placeholders remain ────────────────
+		{
+			Hash: 'tpl-warn',
+			Type: 'error-message',
+			X: 1430,
+			Y: 380,
+			Width: 240,
+			Height: 80,
+			Title: 'Warn: Unresolved',
+			Ports:
+			[
+				{ Hash: 'tpl-warn-in', Direction: 'input', Side: 'left', Label: 'Trigger' },
+				{ Hash: 'tpl-warn-done', Direction: 'output', Side: 'right', Label: 'Complete' }
+			],
+			Data: { MessageTemplate: 'Warning: Template still contains unresolved ${...} placeholders after processing' }
+		},
+		// ── Prepend a generated-by header comment ───────────────
+		{
+			Hash: 'tpl-header',
+			Type: 'string-appender',
+			X: 1750,
+			Y: 160,
+			Width: 220,
+			Height: 80,
+			Title: 'Add Header',
+			Ports:
+			[
+				{ Hash: 'tpl-hdr-in', Direction: 'input', Side: 'left', Label: 'Append' },
+				{ Hash: 'tpl-hdr-done', Direction: 'output', Side: 'right', Label: 'Completed' }
+			],
+			Data: { InputString: '{~D:Record.TaskOutput.tpl-replace-ver.ReplacedString~}', OutputAddress: 'Operation.FinalContent' }
+		},
+		// ── Write the processed output ──────────────────────────
+		{
+			Hash: 'tpl-write',
+			Type: 'write-file',
+			X: 2050,
+			Y: 160,
+			Width: 200,
+			Height: 80,
+			Title: 'Write Output',
+			Ports:
+			[
+				{ Hash: 'tpl-write-in', Direction: 'input', Side: 'left', Label: 'BeginWrite' },
+				{ Hash: 'tpl-write-done', Direction: 'output', Side: 'right', Label: 'WriteComplete' },
+				{ Hash: 'tpl-write-err', Direction: 'output', Side: 'bottom', Label: 'Error' }
+			],
+			Data: { FilePath: 'README.md', Content: '{~D:Record.Operation.FinalContent~}', Encoding: 'utf8' }
+		},
+		// ── Exit ─────────────────────────────────────────────────
+		{
+			Hash: 'tpl-end',
+			Type: 'end',
+			X: 2330,
+			Y: 260,
+			Width: 140,
+			Height: 80,
+			Title: 'End',
+			Ports:
+			[
+				{ Hash: 'tpl-end-in', Direction: 'input', Side: 'left', Label: 'In' }
+			],
+			Data: {}
+		}
+	],
+	Connections:
+	[
+		// Start -> Set Project Info
+		{
+			Hash: 'tpl-c1',
+			SourceNodeHash: 'tpl-start',
+			SourcePortHash: 'tpl-start-out',
+			TargetNodeHash: 'tpl-setvals',
+			TargetPortHash: 'tpl-sv-in',
+			Data: {}
+		},
+		// Set Project Info -> Read Template
+		{
+			Hash: 'tpl-c2',
+			SourceNodeHash: 'tpl-setvals',
+			SourcePortHash: 'tpl-sv-out',
+			TargetNodeHash: 'tpl-read',
+			TargetPortHash: 'tpl-read-in',
+			Data: {}
+		},
+		// Read Template -> Set Project Name
+		{
+			Hash: 'tpl-c3',
+			SourceNodeHash: 'tpl-read',
+			SourcePortHash: 'tpl-read-done',
+			TargetNodeHash: 'tpl-replace-name',
+			TargetPortHash: 'tpl-rn-in',
+			Data: {}
+		},
+		// Set Project Name -> Set Version
+		{
+			Hash: 'tpl-c4',
+			SourceNodeHash: 'tpl-replace-name',
+			SourcePortHash: 'tpl-rn-done',
+			TargetNodeHash: 'tpl-replace-ver',
+			TargetPortHash: 'tpl-rv-in',
+			Data: {}
+		},
+		// Set Version -> Unresolved Placeholders?
+		{
+			Hash: 'tpl-c5',
+			SourceNodeHash: 'tpl-replace-ver',
+			SourcePortHash: 'tpl-rv-done',
+			TargetNodeHash: 'tpl-validate',
+			TargetPortHash: 'tpl-val-in',
+			Data: {}
+		},
+		// Unresolved Placeholders? (True) -> Warn
+		{
+			Hash: 'tpl-c6',
+			SourceNodeHash: 'tpl-validate',
+			SourcePortHash: 'tpl-val-true',
+			TargetNodeHash: 'tpl-warn',
+			TargetPortHash: 'tpl-warn-in',
+			Data: {}
+		},
+		// Warn -> End
+		{
+			Hash: 'tpl-c7',
+			SourceNodeHash: 'tpl-warn',
+			SourcePortHash: 'tpl-warn-done',
+			TargetNodeHash: 'tpl-end',
+			TargetPortHash: 'tpl-end-in',
+			Data: {}
+		},
+		// Unresolved Placeholders? (False) -> Add Header
+		{
+			Hash: 'tpl-c8',
+			SourceNodeHash: 'tpl-validate',
+			SourcePortHash: 'tpl-val-false',
+			TargetNodeHash: 'tpl-header',
+			TargetPortHash: 'tpl-hdr-in',
+			Data: {}
+		},
+		// Add Header -> Write Output
+		{
+			Hash: 'tpl-c9',
+			SourceNodeHash: 'tpl-header',
+			SourcePortHash: 'tpl-hdr-done',
+			TargetNodeHash: 'tpl-write',
+			TargetPortHash: 'tpl-write-in',
+			Data: {}
+		},
+		// Write Output -> End
+		{
+			Hash: 'tpl-c10',
+			SourceNodeHash: 'tpl-write',
+			SourcePortHash: 'tpl-write-done',
+			TargetNodeHash: 'tpl-end',
+			TargetPortHash: 'tpl-end-in',
+			Data: {}
+		},
+		// Read Template error -> End
+		{
+			Hash: 'tpl-c11',
+			SourceNodeHash: 'tpl-read',
+			SourcePortHash: 'tpl-read-err',
+			TargetNodeHash: 'tpl-end',
+			TargetPortHash: 'tpl-end-in',
+			Data: {}
+		},
+		// Set Project Name error -> End
+		{
+			Hash: 'tpl-c12',
+			SourceNodeHash: 'tpl-replace-name',
+			SourcePortHash: 'tpl-rn-err',
+			TargetNodeHash: 'tpl-end',
+			TargetPortHash: 'tpl-end-in',
+			Data: {}
+		},
+		// Set Version error -> End
+		{
+			Hash: 'tpl-c13',
+			SourceNodeHash: 'tpl-replace-ver',
+			SourcePortHash: 'tpl-rv-err',
+			TargetNodeHash: 'tpl-end',
+			TargetPortHash: 'tpl-end-in',
+			Data: {}
+		},
+		// Write Output error -> End
+		{
+			Hash: 'tpl-c14',
+			SourceNodeHash: 'tpl-write',
+			SourcePortHash: 'tpl-write-err',
+			TargetNodeHash: 'tpl-end',
+			TargetPortHash: 'tpl-end-in',
+			Data: {}
+		}
+	],
+	ViewState:
+	{
+		PanX: 0,
+		PanY: 0,
+		Zoom: 1,
+		SelectedNodeHash: null,
+		SelectedConnectionHash: null
+	}
+};