@pixlcore/xycli 1.0.6 → 1.0.7

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # xyCLI Changelog
 
+## Version v1.0.6
+
+> September 22, 2026
+
+- [`985c132`](https://github.com/pixlcore/xycli/commit/985c132607e1dcdabbadc829d6f21e599a2eb52b): Version 1.0.6
+- [`f0aac32`](https://github.com/pixlcore/xycli/commit/f0aac320cbd301a5dc45862edaec9f842c2c6c79): Feature: Add "xy upgrade" command.
+- [`a9b653b`](https://github.com/pixlcore/xycli/commit/a9b653b9649afd15d93cb3d29ee4f23da47bde0a): Bug Fix: Sync files with similar stems and neighbors can get mixed up.  Fixes #4.
+
 ## Version v1.0.5
 
 > September 21, 2026

package/README.md

@@ -499,7 +499,7 @@ cd xyops-automation
 xy sync setup events plugins categories --file_props script,params.script
 ```
 
-Setup creates one file per definition and can extract scripts into adjacent source files. Events and workflows are automatically grouped into subfolders named after their Categories. You can reorganize the tree afterward; sync scans subdirectories and matches definitions by resource type and exact ID.
+Setup creates one file per definition and can extract scripts into adjacent source files. The same `--file_props script,params.script` selection also extracts matching scripts from workflow nodes automatically. Events and workflows are grouped into subfolders named after their Categories. You can reorganize the tree afterward; sync scans subdirectories and matches definitions by resource type and exact ID.
 
 Preview a push or pull, then apply the direction you want:
 

package/docs/help.md

@@ -308,6 +308,8 @@ Setup creates one folder per resource type and one XYPDF JSON file per object, u
 
 For `--file_props`, use comma-separated property names or dot paths, such as `script,params.script`. Only nonempty string values are extracted. The JSON value becomes `(External)`, and sync loads the external file automatically. Setup chooses extensions from executable commands, shebangs, and JSON content when possible. Use `--default_ext ps1` (or `--default_ext .ps1`) to replace the `.txt` fallback for properties whose type cannot be detected. The override does not replace an extension that setup successfully detects.
 
+The same property selection also checks every workflow node automatically. For example, `params.script` in a node's `data` becomes a neighbor such as `My-Workflow-workflow.nt3sr3y4.params.script.sh`. The node ID in the filename identifies which node owns the property. No additional setup option is needed.
+
 Use `--new` from the root of an existing sync tree to add definitions that exist in xyOps but have no local source. Setup scans recursively and matches existing sources by item type and exact ID, so renamed files and custom folder layouts are preserved. New definitions use the normal suggested type and Category folders. Malformed, duplicate, unsupported, or orphaned local sources stop the operation before any new files are written. `--new` cannot be combined with `--force`, and it does not create new definitions in xyOps.
 
 An explicitly supplied `--down_cmd` runs from the current setup directory after at least one definition is written. It does not run when `--new` finds nothing or during a dry run. Saved sync completion commands are not inherited by setup.

package/docs/sync.md

@@ -96,7 +96,7 @@ Setup always writes below the current working directory. Type names after `setup
 xy sync setup events plugins categories --file_props script,params.script --dry
 ```
 
-The `--file_props` switch will externalize specific JSON property paths into individually named files, for easy editing.  This is great for storing Plugin scripts and Event shell scripts in separate files alongside the main JSON definition files.
+The `--file_props` switch will externalize specific JSON property paths into individually named files, for easy editing.  This is great for storing Plugin scripts, Event shell scripts, and workflow node scripts in separate files alongside the main JSON definition files.
 
 The preview lists the folders and files that would be written. `--dry` creates no directories or files.
 
@@ -122,6 +122,7 @@ xyops-automation/
     workflows/
         Deployments/
             Release-Pipeline.json
+            Release-Pipeline-workflow.nt3sr3y4.params.script.sh
 ```
 
 Setup creates one folder per selected resource type and one JSON file per definition. Event and workflow exports are separated into `events/` and `workflows/`, then grouped into subfolders using their Category titles. Both participate in normal sync through the `events` selection.
@@ -242,9 +243,12 @@ This extracts the selected content, if found, and moves it to a neighboring file
 | --- | --- | --- |
 | `My-Plugin.json` | `script` | `My-Plugin-script.js` |
 | `My-Event.json` | `params.script` | `My-Event-params.script.sh` |
+| `Release-Pipeline.json` | `workflow.nt3sr3y4.params.script` | `Release-Pipeline-workflow.nt3sr3y4.params.script.sh` |
 
 The general naming pattern is **`BASENAME-PROPERTY.EXT`**, in the same directory as `BASENAME.json`. Dot paths such as `params.script` identify nested properties. Setup chooses an extension from the executable command or a script's shebang when possible, falling back to JSON-looking content or `.txt`. Normal sync accepts your chosen extension.
 
+The same `--file_props script,params.script` selection checks every node in a workflow automatically. If a node has a nonempty string at `data.params.script`, setup writes a neighbor for that node and leaves `(External)` in the workflow JSON. In its filename, `workflow.NODE_ID.params.script` identifies the node by its ID and then reads `data.params.script`. No additional option is needed for workflow nodes.
+
 Use `--default_ext EXT` to replace the `.txt` fallback when setup cannot detect a type. For example, `--default_ext ps1` and `--default_ext .ps1` both produce `.ps1` neighbors. Detected interpreter and JSON extensions still take precedence. The fallback applies to every undetected property selected by that setup command, so group properties with the same expected file type or run setup separately when needed.
 
 External properties are detected automatically when sync runs; you do not need to repeat `--file_props`. The neighbor's text replaces that property in the local definition before comparison and before an upload. A pull writes the latest value into the existing neighbor file.

package/docs/two-way-git-tutorial.md

@@ -67,7 +67,7 @@ xy sync setup events --file_props script,params.script --default_ext ps1 --dry
 
 The `events` selection includes both Events and workflows. Setup places workflows in their own `workflows/` directory, then groups Events and workflows into subfolders named after their Categories.
 
-`--file_props script,params.script` extracts common Plugin and Event script properties into neighboring files. If your Plugin uses another property, add its dot path to the list. For example, use `script,params.script,params.command` when an Event stores its PowerShell source in `params.command`.
+`--file_props script,params.script` extracts common script properties into neighboring files. It also checks each workflow node automatically, so a node's `data.params.script` gets its own file named with that node's ID. If a property uses another path, add its dot path to the list. For example, use `script,params.script,params.command` when an Event stores its PowerShell source in `params.command`.
 
 The optional `--default_ext ps1` uses `.ps1` when setup cannot detect a neighbor file's language from an executable command, shebang, or JSON content. Remove it or choose another extension if PowerShell is not the appropriate fallback for your repository.
 

package/lib/jobs.js

@@ -414,8 +414,8 @@ module.exports = {
 			
 			this.printNiceHTML( job.html.content );
 			
-			if (job.table.caption) {
-				println( " " + gray(job.table.caption) );
+			if (job.html.caption) {
+				println( " " + gray(job.html.caption) );
 			}
 		} // job.html
 		

package/lib/sync.js

@@ -253,13 +253,13 @@ module.exports = {
 				}
 				
 				// External files may only replace string properties that already exist in
-				// the definition.  Tools.setPath() creates missing keys, so validate first.
-				if (typeof(Tools.getPath(item.data, prop_path)) != 'string') {
+				// the definition.  setSyncPropByPath() creates missing keys, so validate first.
+				if (typeof(this.getSyncPropByPath(item.data, prop_path)) != 'string') {
 					this.logSyncWarning("Neighbor file does not match an existing string property: " + neighbor.path + " (" + prop_path + ")");
 					neighbor_error = true;
 					return;
 				}
-				if (!Tools.setPath(item.data, prop_path, content)) {
+				if (!this.setSyncPropByPath(item.data, prop_path, content)) {
 					this.logSyncWarning("Invalid neighbor property path: " + neighbor.path + " (" + prop_path + ")");
 					neighbor_error = true;
 					return;
@@ -703,9 +703,9 @@ module.exports = {
 		if (item.neighbors) {
 			for (var path in item.neighbors) {
 				var file = item.neighbors[path];
-				var value = Tools.getPath( data, path ) ?? "";
+				var value = this.getSyncPropByPath( data, path ) ?? "";
 				
-				if (!Tools.setPath( data, path, "(External)" )) {
+				if (!this.setSyncPropByPath( data, path, "(External)" )) {
 					throw "External neighbor file path not found: " + file + ": " + path;
 				}
 				
@@ -1006,10 +1006,22 @@ module.exports = {
 				var item = Tools.copyHash(plan.source_item, true);
 				var extras = [];
 				(opts.file_props || []).forEach( path => {
-					var extra = Tools.getPath(item, path);
+					var extra = this.getSyncPropByPath(item, path);
 					if ((typeof(extra) == 'string') && extra.match(/\S/)) {
 						extras.push({ path, content: extra });
-						Tools.setPath( item, path, "(External)" );
+						this.setSyncPropByPath( item, path, "(External)" );
+					}
+					
+					// handle workflow nodes separately
+					if (item.workflow && item.workflow.nodes && Array.isArray(item.workflow.nodes)) {
+						item.workflow.nodes.forEach( node => {
+							if (!node.data || !Tools.isaHash(node.data)) return; // sanity
+							var extra = this.getSyncPropByPath(node.data, path);
+							if ((typeof(extra) == 'string') && extra.match(/\S/)) {
+								extras.push({ path: `workflow.${node.id}.${path}`, content: extra });
+								this.setSyncPropByPath( node.data, path, "(External)" );
+							}
+						} );
 					}
 				});
 				
@@ -1188,6 +1200,42 @@ module.exports = {
 		}
 		
 		return ext;
+	},
+	
+	getSyncPropByPath(data, path) {
+		// special-case Tools.getPath for handling shorthand for named workflow nodes
+		// e.g. `workflow.nabcd1234.params.foo` == `workflow.nodes[id='nabcd1234'].data.params.foo`
+		if (path.match(/^workflow\.(\w+)\.(.+)$/) && data.workflow && data.workflow.nodes && Array.isArray(data.workflow.nodes)) {
+			var node_id = RegExp.$1;
+			var sub_path = RegExp.$2;
+			if (node_id === 'nodes') return Tools.getPath(data, path);
+			
+			var node = Tools.findObject( data.workflow.nodes, { id: node_id } );
+			if (!node || !node.data) return undefined;
+			
+			data = node.data;
+			path = sub_path;
+		}
+		
+		return Tools.getPath(data, path);
+	},
+	
+	setSyncPropByPath(data, path, value) {
+		// special-case Tools.setPath for handling shorthand for named workflow nodes
+		// e.g. `workflow.nabcd1234.params.foo` == `workflow.nodes[id='nabcd1234'].data.params.foo`
+		if (path.match(/^workflow\.(\w+)\.(.+)$/) && data.workflow && data.workflow.nodes && Array.isArray(data.workflow.nodes)) {
+			var node_id = RegExp.$1;
+			var sub_path = RegExp.$2;
+			if (node_id === 'nodes') return Tools.setPath(data, path, value);
+			
+			var node = Tools.findObject( data.workflow.nodes, { id: node_id } );
+			if (!node || !node.data) return undefined;
+			
+			data = node.data;
+			path = sub_path;
+		}
+		
+		return Tools.setPath(data, path, value);
 	}
 		
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pixlcore/xycli",
-	"version": "1.0.6",
+	"version": "1.0.7",
 	"description": "A complete command-line interface for the xyOps workflow automation system.",
 	"author": "Joseph Huckaby <jhuckaby@pixlcore.com>",
 	"homepage": "https://github.com/pixlcore/xycli",

package/test/sync-unit.test.js

@@ -432,6 +432,61 @@ test('sync setup groups Events and workflows into Category folders', t => {
 	assert.equal(result.stdout.indexOf('events/Operations-Team/', operationsHeader + 1), -1);
 });
 
+test('sync setup externalizes each matching workflow node parameter', t => {
+	const shellScript = '#!/bin/sh\necho first\n';
+	const nodeScript = '#!/usr/bin/env node\nconsole.log("second");\n';
+	const workflow = {
+		id: 'flow', title: 'Flow', type: 'workflow', category: 'operations',
+		workflow: { nodes: [
+			{ id: 'ntrigger1', type: 'trigger' },
+			{ id: 'nfirst01', type: 'event', data: { params: { script: shellScript } } },
+			{ id: 'nsecond1', type: 'job', data: { params: { script: nodeScript } } },
+			{ id: 'nempty001', type: 'job', data: { params: { script: '' } } }
+		] }
+	};
+	const result = runSync(t, {
+		setup: ['events'],
+		categories: [{ id: 'operations', title: 'Operations' }],
+		events: [workflow],
+		args: { file_props: 'params.script' }
+	});
+	const dir = Path.join(result.dir, 'workflows', 'Operations');
+	const source = JSON.parse(fs.readFileSync(Path.join(dir, 'Flow.json'), 'utf8')).items[0].data;
+	
+	assert.equal(result.status, 0);
+	assert.deepEqual(result.report.errors, []);
+	assert.equal(fs.readFileSync(Path.join(dir, 'Flow-workflow.nfirst01.params.script.sh'), 'utf8'), shellScript);
+	assert.equal(fs.readFileSync(Path.join(dir, 'Flow-workflow.nsecond1.params.script.js'), 'utf8'), nodeScript);
+	assert.equal(source.workflow.nodes[1].data.params.script, '(External)');
+	assert.equal(source.workflow.nodes[2].data.params.script, '(External)');
+	assert.equal(source.workflow.nodes[3].data.params.script, '');
+	assert.equal(fs.readdirSync(dir).length, 3, 'Empty and trigger nodes have no neighbor files');
+});
+
+test('sync setup accepts a shorthand path for one workflow node', t => {
+	const workflow = {
+		id: 'flow', title: 'Flow', type: 'workflow', category: 'operations',
+		workflow: { nodes: [
+			{ id: 'nfirst01', type: 'job', data: { params: { script: 'First\n' } } },
+			{ id: 'nsecond1', type: 'job', data: { params: { script: 'Second\n' } } }
+		] }
+	};
+	const result = runSync(t, {
+		setup: ['events'],
+		categories: [{ id: 'operations', title: 'Operations' }],
+		events: [workflow],
+		args: { file_props: 'workflow.nfirst01.params.script' }
+	});
+	const dir = Path.join(result.dir, 'workflows', 'Operations');
+	const source = JSON.parse(fs.readFileSync(Path.join(dir, 'Flow.json'), 'utf8')).items[0].data;
+	
+	assert.equal(result.status, 0);
+	assert.equal(fs.readFileSync(Path.join(dir, 'Flow-workflow.nfirst01.params.script.txt'), 'utf8'), 'First\n');
+	assert.equal(source.workflow.nodes[0].data.params.script, '(External)');
+	assert.equal(source.workflow.nodes[1].data.params.script, 'Second\n');
+	assert.equal(fs.readdirSync(dir).length, 2);
+});
+
 test('sync setup validates all Event Categories before writing any files', t => {
 	const result = runSync(t, {
 		setup: ['plugins', 'events'],
@@ -655,6 +710,112 @@ test('property neighbor matching requires an exact source basename boundary', t
 	assert.equal(result.report.requests.some(request => request.method === 'update_event'), false);
 });
 
+test('workflow node neighbors replace placeholders before upload', t => {
+	const shellScript = '#!/bin/sh\necho local\n';
+	const nodeScript = '#!/usr/bin/env node\nconsole.log("local");\n';
+	const remote = {
+		id: 'flow', title: 'Flow', type: 'workflow', category: 'operations',
+		workflow: { nodes: [
+			{ id: 'nfirst01', type: 'event', data: { params: { script: 'Remote shell\n' } } },
+			{ id: 'nsecond1', type: 'job', data: { params: { script: 'Remote node\n' } } }
+		] }
+	};
+	const local = JSON.parse(JSON.stringify(remote));
+	local.workflow.nodes.forEach(node => { node.data.params.script = '(External)'; });
+	const result = runSync(t, {
+		events: [remote],
+		existingSources: [
+			{ path: 'Flow.json', type: 'event', data: local },
+			{ path: 'Flow-workflow.nfirst01.params.script.sh', contents: shellScript },
+			{ path: 'Flow-workflow.nsecond1.params.script.js', contents: nodeScript }
+		],
+		args: { up: 'events' }
+	});
+	const updates = result.report.requests.filter(request => request.method === 'update_event');
+	
+	assert.equal(result.status, 0);
+	assert.deepEqual(result.report.warnings, []);
+	assert.deepEqual(result.report.errors, []);
+	assert.equal(updates.length, 1);
+	assert.equal(updates[0].data.workflow.nodes[0].data.params.script, shellScript);
+	assert.equal(updates[0].data.workflow.nodes[1].data.params.script, nodeScript);
+	const source = JSON.parse(fs.readFileSync(Path.join(result.dir, 'Flow.json'), 'utf8')).items[0].data;
+	assert.equal(source.workflow.nodes[0].data.params.script, '(External)');
+	assert.equal(source.workflow.nodes[1].data.params.script, '(External)');
+});
+
+test('workflow node neighbors receive pulled values while JSON keeps placeholders', t => {
+	const shellScript = '#!/bin/sh\necho remote\n';
+	const nodeScript = '#!/usr/bin/env node\nconsole.log("remote");\n';
+	const remote = {
+		id: 'flow', title: 'Flow', type: 'workflow', category: 'operations',
+		workflow: { nodes: [
+			{ id: 'nfirst01', type: 'event', data: { params: { script: shellScript } } },
+			{ id: 'nsecond1', type: 'job', data: { params: { script: nodeScript } } }
+		] }
+	};
+	const local = JSON.parse(JSON.stringify(remote));
+	local.workflow.nodes.forEach(node => { node.data.params.script = '(External)'; });
+	const result = runSync(t, {
+		events: [remote],
+		existingSources: [
+			{ path: 'Flow.json', type: 'event', data: local },
+			{ path: 'Flow-workflow.nfirst01.params.script.sh', contents: 'Old shell\n' },
+			{ path: 'Flow-workflow.nsecond1.params.script.js', contents: 'Old node\n' }
+		],
+		args: { down: 'events' }
+	});
+	const source = JSON.parse(fs.readFileSync(Path.join(result.dir, 'Flow.json'), 'utf8')).items[0].data;
+	
+	assert.equal(result.status, 0);
+	assert.deepEqual(result.report.warnings, []);
+	assert.deepEqual(result.report.errors, []);
+	assert.equal(fs.readFileSync(Path.join(result.dir, 'Flow-workflow.nfirst01.params.script.sh'), 'utf8'), shellScript);
+	assert.equal(fs.readFileSync(Path.join(result.dir, 'Flow-workflow.nsecond1.params.script.js'), 'utf8'), nodeScript);
+	assert.equal(source.workflow.nodes[0].data.params.script, '(External)');
+	assert.equal(source.workflow.nodes[1].data.params.script, '(External)');
+});
+
+test('workflow node shorthand preserves ordinary indexed dot paths', () => {
+	const sync = require('../lib/sync.js');
+	const data = { workflow: { nodes: [
+		{ id: 'nfirst01', data: { params: { script: 'Original\n' } } }
+	] } };
+	
+	// The literal "nodes" segment must not be mistaken for a workflow node ID.
+	assert.equal(sync.getSyncPropByPath(data, 'workflow.nfirst01.params.script'), 'Original\n');
+	assert.equal(sync.getSyncPropByPath(data, 'workflow.nodes.0.data.params.script'), 'Original\n');
+	assert.equal(sync.setSyncPropByPath(data, 'workflow.nodes.0.data.params.script', 'Indexed\n'), true);
+	assert.equal(sync.getSyncPropByPath(data, 'workflow.nfirst01.params.script'), 'Indexed\n');
+	assert.equal(sync.setSyncPropByPath(data, 'workflow.nfirst01.params.script', 'Shorthand\n'), true);
+	assert.equal(sync.getSyncPropByPath(data, 'workflow.nodes.0.data.params.script'), 'Shorthand\n');
+	assert.equal(sync.getSyncPropByPath(data, 'workflow.nmissing1.params.script'), undefined);
+	assert.equal(sync.setSyncPropByPath(data, 'workflow.nmissing1.params.script', 'Missing\n'), undefined);
+	assert.equal(data.workflow.nodes.length, 1);
+});
+
+test('a workflow neighbor for a missing node stops sync before upload', t => {
+	const workflow = {
+		id: 'flow', title: 'Flow', type: 'workflow', category: 'operations',
+		workflow: { nodes: [
+			{ id: 'nfirst01', type: 'job', data: { params: { script: 'Inline\n' } } }
+		] }
+	};
+	const result = runSync(t, {
+		events: [workflow],
+		existingSources: [
+			{ path: 'Flow.json', type: 'event', data: workflow },
+			{ path: 'Flow-workflow.nmissing1.params.script.sh', contents: 'Orphan\n' }
+		],
+		args: { up: 'events' }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.report.warnings[0], /does not match an existing string property/);
+	assert.deepEqual(result.report.errors, []);
+	assert.equal(result.report.requests.some(request => request.method === 'update_event'), false);
+});
+
 test('a property neighbor must resolve to an existing string property', t => {
 	const category = { id: 'fixture', title: 'Fixture', notes: '' };
 	const result = runSync(t, {