@pixlcore/xycli 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # 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
+
+- [`2542921`](https://github.com/pixlcore/xycli/commit/25429212b664130bf767db85f52610c8d07c00aa): Version 1.0.5
+- [`8818ec6`](https://github.com/pixlcore/xycli/commit/8818ec6291c0d06ec6b48174443eaf330682cff2): Bug FIx: Help system was breaking on Windows due to CRLF line endings.
+
+## Version v1.0.4
+
+> September 21, 2026
+
+- [`553d4d9`](https://github.com/pixlcore/xycli/commit/553d4d95eec0dd4e966dba03d1cccadee49454fc): Version 1.0.4
+- [`4a68d5a`](https://github.com/pixlcore/xycli/commit/4a68d5ad6ab1d2c28b5a5a933e6c6ec711fd2d90): Bug Fix: Validate local command routing before requiring a configured server.
+
+## Version v1.0.3
+
+> September 21, 2026
+
+- [`00c2805`](https://github.com/pixlcore/xycli/commit/00c280596899cee1de66a4179684d1a7992ee1d9): Version 1.0.3
+- [`82777d0`](https://github.com/pixlcore/xycli/commit/82777d01cb751769e14987a7cd86e0d71f91ee79): Feature: Add Windows support.  Fixes #3.
+
 ## Version v1.0.2
 
 > September 20, 2026

package/README.md

@@ -43,6 +43,13 @@ npm install -g @pixlcore/xycli
 
 This installs the `xy` command. In the xyOps web interface, open **API Keys** and create a key for the CLI. Choose privileges and resource access appropriate for the work you want to do. The [tutorial](docs/tutorial.md) needs access to view Events and servers, create and edit Events, run jobs, and create and test Web Hooks. System administration commands require a full administrator key.
 
+To check for a newer xyCLI release, use `xy upgrade`. The command displays the installed and latest npm versions without making any changes. Add `--confirm` to install the version shown.
+
+```sh
+xy upgrade
+xy upgrade --confirm
+```
+
 Save your xyOps URL and API Key:
 
 ```sh
@@ -492,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

@@ -24,6 +24,7 @@ xy tags
 xy tickets
 xy hooks
 xy marketplace
+xy upgrade
 xy event EVENT_ID --export event.json
 xy import event.json
 xy sync ./ --up events,plugins --dry
@@ -95,6 +96,7 @@ xy help marketplace
 xy help marketplace search
 xy help marketplace get
 xy help marketplace install
+xy help upgrade
 xy help export
 xy help import
 xy help sync
@@ -306,12 +308,28 @@ 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.
 
 Without `--force`, ordinary setup stops when an output file already exists. Files written before an error are not rolled back. Ensure object titles produce distinct filename slugs, especially when using `--force`, and back up any local edits before rerunning setup. For a delete-mode inventory, verify that every object eligible for deletion that you intend to keep has a source file. Stock and Marketplace objects are protected from deletion and may be omitted.
 
+## upgrade
+
+Check the installed xyCLI version against the latest version published to npm. This command is local and does not require an xyOps URL or API Key.
+
+```sh
+xy upgrade
+xy upgrade --confirm
+xy upgrade --confirm --dry
+```
+
+The command always displays the installed and latest versions. When an upgrade is available, add `--confirm` to install the exact version shown using npm. npm output is connected directly to the current terminal. A dry run prints the installation command without executing it.
+
+The command never downgrades xyCLI. If the installed version is newer than npm's `latest` version, it reports that status and exits without running npm. Global npm installations may require a user-writable npm prefix; the command does not invoke `sudo` or otherwise elevate privileges.
+
 ## api
 
 Call any API method exposed by the xyOps SDK and print its JSON request and response. Named options become request properties, and dotted names provide a convenient way to build nested objects.

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/index.js

@@ -54,7 +54,7 @@ const JSON_ARG_EXCEPTIONS = ['body'];
 // Keep the public command inventory in one place, so typo suggestions and the
 // fallback help text always advertise the exact same top-level commands.
 const TOP_LEVEL_COMMANDS = [
-	'help', 'config', 'doc', 'dashboard', 'system', 'upcoming',
+	'help', 'config', 'upgrade', 'doc', 'dashboard', 'system', 'upcoming',
 	'alerts', 'alert', 'buckets', 'bucket', 'categories', 'category',
 	'channels', 'channel', 'events', 'event', 'run', 'groups', 'group',
 	'jobs', 'job', 'keys', 'key', 'log', 'monitors', 'monitor',
@@ -191,8 +191,9 @@ const app = {
 		
 		println( "\n " + cli.emoji('🚀') + " " + this.color('theme').bold("xyOps CLI ") + gray("v" + this.version) );
 		
-		// call config cmd early (before contacting xyops)
-		if (cmd == 'config') {
+		// Call local commands early, before requiring xyOps credentials or
+		// contacting the configured server. The upgrade command only contacts npm.
+		if ((cmd == 'config') || (cmd == 'upgrade')) {
 			await this['cmd_' + cmd]();
 			print("\n");
 			return;
@@ -428,6 +429,7 @@ const app = {
 
 Tools.mergeHashInto( app, require('./lib/utils.js') );
 Tools.mergeHashInto( app, require('./lib/config.js') );
+Tools.mergeHashInto( app, require('./lib/upgrade.js') );
 Tools.mergeHashInto( app, require('./lib/doc.js') );
 Tools.mergeHashInto( app, require('./lib/dashboard.js') );
 Tools.mergeHashInto( app, require('./lib/system.js') );

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

@@ -100,6 +100,30 @@ module.exports = {
 		
 		println( " " + Tools.commify(files.length) + " files found." );
 		
+		// Index XYPDF basenames by directory before attaching any neighbor files.
+		// A source such as "Test-Event.json" is a prefix of both
+		// "Test-Event-V2.json" and "Test-Event-V2-params.command.ps1".  Sorting
+		// longest-first lets each external property file belong to the most specific
+		// source basename instead of also being claimed by every shorter prefix.
+		var source_stems_by_dir = new Map();
+		files.filter( file => !!file.path.match(/\.json$/i) ).forEach( file => {
+			var xypdf = null;
+			try { xypdf = Tools.parseJSON( fs.readFileSync(file.path, 'utf8') ); }
+			catch (err) { return; } // the normal scan below reports malformed JSON
+			if (!xypdf || !Tools.isaHash(xypdf) || (xypdf.type !== 'xypdf')) return;
+			
+			var dir = Path.dirname(file.path);
+			var stems = source_stems_by_dir.get(dir);
+			if (!stems) {
+				stems = [];
+				source_stems_by_dir.set(dir, stems);
+			}
+			stems.push( Path.basename(file.path).replace(/\.\w+$/, '') );
+		} );
+		source_stems_by_dir.forEach( stems => {
+			stems.sort( (a, b) => b.length - a.length );
+		} );
+		
 		// load all xypdf files
 		var items = [];
 		
@@ -196,11 +220,16 @@ module.exports = {
 				var nfilename = Path.basename(neighbor.path);
 				var nstem = nfilename.replace(/\.\w+$/, '');
 				if (nstem.length <= stem.length) return; // neighbor stem too short
-				if (!nstem.startsWith(stem)) return; // no shared stem
+				if (!nstem.startsWith(stem + '-')) return; // no exact basename boundary
 				
-				var suffix = nstem.substring(stem.length);
-				if (!suffix.match(/\-([\w\.\-]+)$/)) return; // not correct format
-				var prop_path = RegExp.$1;
+				// Multiple XYPDF sources may share a title prefix.  The longest matching
+				// source stem owns this neighbor, so shorter sources must ignore it.
+				var source_stems = source_stems_by_dir.get(dir) || [];
+				var owner_stem = source_stems.find( source_stem => nstem.startsWith(source_stem + '-') );
+				if (owner_stem && (owner_stem !== stem)) return;
+				
+				var prop_path = nstem.substring(stem.length + 1);
+				if (!prop_path.match(/^[\w\.\-]+$/)) return; // not correct format
 				
 				var content = '';
 				try {
@@ -224,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;
@@ -674,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;
 				}
 				
@@ -977,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)" );
+							}
+						} );
 					}
 				});
 				
@@ -1159,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/lib/upgrade.js

@@ -0,0 +1,126 @@
+// xyCLI Self-Upgrade Layer
+
+const cp = require('node:child_process');
+
+const cli = require('pixl-cli');
+const chalk = cli.chalk;
+
+const PACKAGE_NAME = '@pixlcore/xycli';
+const REGISTRY_URL = 'https://registry.npmjs.org/@pixlcore%2Fxycli/latest';
+const REGISTRY_TIMEOUT_MS = 10000;
+
+module.exports = {
+	
+	async cmd_upgrade() {
+		// This is a deliberately small local command. It must remain usable before
+		// the user has configured an xyOps URL or API key.
+		if (this.args.other.length) this.dieUsage('upgrade');
+		if (('confirm' in this.args) && (typeof(this.args.confirm) != 'boolean')) {
+			this.die("Upgrade --confirm must be true or false.");
+		}
+		
+		// These common switches are consumed by the main command runner after local
+		// commands return. Ignore them here, but reject command-specific typos.
+		var allowed = ['other', 'confirm', 'debug', 'echo', 'quiet', 'verbose'];
+		var unsupported = Object.keys(this.args).find( key => !allowed.includes(key) );
+		if (unsupported) this.die("Unsupported upgrade option: --" + unsupported);
+		
+		var installed_version = this.version;
+		var latest_version = await this.getLatestXYCLIVersion();
+		var comparison = this.compareVersions(latest_version, installed_version);
+		var status = comparison > 0 ? this.color('blue').bold('Upgrade available') :
+			comparison < 0 ? this.color('yellow').bold('Installed version is newer than npm') :
+			this.color('green').bold('Up to date');
+		
+		this.printBoxList({
+			title: 'xyCLI Version',
+			rows: [
+				[ 'Installed Version', 'v' + installed_version ],
+				[ 'Latest Version', 'v' + latest_version ],
+				[ 'Status', status ]
+			]
+		});
+		
+		// A different version is not necessarily an upgrade. In particular, local
+		// development builds must never be silently downgraded to npm's latest tag.
+		if (comparison <= 0) return;
+		
+		if (this.args.confirm !== true) {
+			this.toast('ℹ️', 'blue', "A new xyCLI version is available! Add '--confirm' to perform the upgrade now.");
+			return;
+		}
+		
+		// Install the exact version shown above. This prevents the npm latest tag
+		// from moving between the version check and the confirmed installation.
+		var command = 'npm install --global ' + PACKAGE_NAME + '@' + latest_version;
+		println( "\n " + this.color('green').bold('Running command: ') + chalk.bold(command) );
+		
+		if (this.dry) {
+			this.toast('⚠️', 'orange', "DRY RUN: The upgrade command was not executed.");
+			return;
+		}
+		
+		var result;
+		try {
+			result = await this.spawnUpgradeCommand(command);
+		}
+		catch (err) {
+			this.die("Could not start the upgrade command: " + err.message);
+		}
+		
+		if (result.signal) this.die("Upgrade command was terminated by signal: " + result.signal);
+		if (result.code !== 0) this.die("Upgrade command failed with exit code: " + result.code);
+		
+		this.toast('✅', 'green', 'Successfully upgraded xyCLI to v' + latest_version + '.');
+	},
+	
+	async getLatestXYCLIVersion() {
+		// The npm latest document is authoritative for the version that an
+		// unqualified global npm install would select.
+		this.cli.progress.start({ amount: 1, pct: false, text: this.color('gray')('Checking npm for the latest xyCLI version...') });
+		
+		var response;
+		try {
+			response = await fetch(REGISTRY_URL, {
+				headers: {
+					'Accept': 'application/json',
+					'User-Agent': PACKAGE_NAME + '/v' + this.version
+				},
+				signal: AbortSignal.timeout(REGISTRY_TIMEOUT_MS)
+			});
+		}
+		catch (err) {
+			this.cli.progress.end();
+			this.die("Could not contact the npm registry: " + err.message);
+		}
+		
+		this.cli.progress.end();
+		if (!response.ok) this.die("npm registry request failed with HTTP status: " + response.status);
+		
+		var data;
+		try { data = await response.json(); }
+		catch (err) { this.die("Could not parse the npm registry response: " + err.message); }
+		
+		if (!data || (typeof(data.version) != 'string') || !data.version.length) {
+			this.die("The npm registry response did not include a package version.");
+		}
+		
+		return data.version;
+	},
+	
+	spawnUpgradeCommand(command) {
+		// npm is npm.cmd on Windows, so launch the fixed, validated command through
+		// the platform shell. Inherited stdio gives npm full use of the terminal.
+		return new Promise((resolve, reject) => {
+			var child = cp.spawn(command, {
+				shell: true,
+				stdio: 'inherit',
+				windowsHide: false
+			});
+			
+			child.once('error', reject);
+			child.once('close', (code, signal) => resolve({ code, signal }));
+		});
+	}
+	
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pixlcore/xycli",
-	"version": "1.0.5",
+	"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",
@@ -21,7 +21,7 @@
 	],
 	"scripts": {
 		"test": "node test.js",
-		"test:offline": "node --test test/config.test.js test/help.test.js test/markdown.test.js test/sync-unit.test.js test/toast.test.js test/utils-unit.test.js",
+		"test:offline": "node --test test/config.test.js test/help.test.js test/markdown.test.js test/sync-unit.test.js test/toast.test.js test/upgrade.test.js test/utils-unit.test.js",
 		"changelog": "node tools/changelog.js"
 	},
 	"dependencies": {

package/test/help.test.js

@@ -18,6 +18,12 @@ test('help is available without server credentials', () => {
 	assert.match(output, /HELP: OVERVIEW/);
 });
 
+test('upgrade help is available without server credentials', () => {
+	const output = xy(['help', 'upgrade'], { env: offlineEnv });
+	assert.match(output, /HELP: UPGRADE/);
+	assert.match(output, /xy upgrade --confirm/);
+});
+
 test('help parses a document with Windows line endings', () => {
 	const output = xy(['help'], { env: offlineEnv, preload: crlfHelpPreload });
 	assert.match(output, /HELP: OVERVIEW/);

package/test/helpers/upgrade-preload.js

@@ -0,0 +1,44 @@
+// Replace npm registry access and the final npm process for offline CLI tests.
+const fs = require('node:fs');
+const cp = require('node:child_process');
+const { EventEmitter } = require('node:events');
+
+global.fetch = async function(url, options) {
+	if (process.env.XYCLI_TEST_REQUEST_FILE) {
+		fs.writeFileSync(process.env.XYCLI_TEST_REQUEST_FILE, JSON.stringify({
+			url: url,
+			headers: options.headers
+		}));
+	}
+	
+	if (process.env.XYCLI_TEST_FETCH_ERROR) {
+		throw new Error(process.env.XYCLI_TEST_FETCH_ERROR);
+	}
+	
+	var status = Number(process.env.XYCLI_TEST_HTTP_STATUS || 200);
+	return {
+		ok: (status >= 200) && (status < 300),
+		status: status,
+		async json() {
+			return { version: process.env.XYCLI_TEST_LATEST_VERSION };
+		}
+	};
+};
+
+cp.spawn = function(command, options) {
+	if (process.env.XYCLI_TEST_SPAWN_FILE) {
+		fs.writeFileSync(process.env.XYCLI_TEST_SPAWN_FILE, JSON.stringify({
+			command: command,
+			shell: options.shell,
+			stdio: options.stdio,
+			windowsHide: options.windowsHide
+		}));
+	}
+	
+	var child = new EventEmitter();
+	process.nextTick(() => {
+		if (process.env.XYCLI_TEST_SPAWN_ERROR) child.emit('error', new Error(process.env.XYCLI_TEST_SPAWN_ERROR));
+		else child.emit('close', Number(process.env.XYCLI_TEST_SPAWN_EXIT || 0), null);
+	});
+	return child;
+};

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'],
@@ -583,6 +638,184 @@ test('a prefixed XYPDF source is never loaded as a property neighbor', t => {
 	assert.equal(result.report.requests.some(request => request.method === 'update_category'), false);
 });
 
+test('a property neighbor belongs to the longest matching XYPDF source stem', t => {
+	const shortCommand = 'Write-Host "Test Event"\n';
+	const longCommand = 'Write-Host "Test Event V2"\n';
+	const shortEvent = { id: 'short', title: 'Test Event', params: { command: shortCommand } };
+	const longEvent = { id: 'long', title: 'Test Event V2', params: { command: longCommand } };
+	const result = runSync(t, {
+		events: [shortEvent, longEvent],
+		existingSources: [
+			{
+				path: 'Test-Event.json',
+				type: 'event',
+				data: { ...shortEvent, params: { command: '(External)' } }
+			},
+			{
+				path: 'Test-Event-params.command.ps1',
+				contents: shortCommand
+			},
+			{
+				path: 'Test-Event-V2.json',
+				type: 'event',
+				data: { ...longEvent, params: { command: '(External)' } }
+			},
+			{
+				path: 'Test-Event-V2-params.command.ps1',
+				contents: longCommand
+			}
+		],
+		args: { up: 'events', dry: true }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.deepEqual(result.report.warnings, []);
+	assert.deepEqual(result.report.errors, []);
+	assert.equal(result.report.requests.some(request => request.method === 'update_event'), false);
+});
+
+test('property neighbor matching requires an exact source basename boundary', t => {
+	const singularCommand = 'Write-Host "Test Event"\n';
+	const pluralCommand = 'Write-Host "Test Events"\n';
+	const singularEvent = { id: 'singular', title: 'Test Event', params: { command: singularCommand } };
+	const pluralEvent = { id: 'plural', title: 'Test Events', params: { command: pluralCommand } };
+	const result = runSync(t, {
+		events: [singularEvent, pluralEvent],
+		existingSources: [
+			{
+				path: 'Test-Event.json',
+				type: 'event',
+				data: { ...singularEvent, params: { command: '(External)' } }
+			},
+			{
+				path: 'Test-Event-params.command.ps1',
+				contents: singularCommand
+			},
+			{
+				path: 'Test-Events.json',
+				type: 'event',
+				data: { ...pluralEvent, params: { command: '(External)' } }
+			},
+			{
+				path: 'Test-Events-params.command.ps1',
+				contents: pluralCommand
+			}
+		],
+		args: { up: 'events', dry: true }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.deepEqual(result.report.warnings, []);
+	assert.deepEqual(result.report.errors, []);
+	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, {

package/test/upgrade.test.js

@@ -0,0 +1,121 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const Path = require('node:path');
+const pkg = require('../package.json');
+const { xy } = require('./helpers/common.js');
+
+const preload = Path.join(__dirname, 'helpers', 'upgrade-preload.js');
+const offlineEnv = {
+	XYOPS_API_KEY: '',
+	XYOPS_BASE_URL: ''
+};
+
+function createUpgradeFixture(t, latest) {
+	// Each command gets private observation files. The preload records registry
+	// and spawn calls without contacting npm or installing anything globally.
+	const dir = fs.mkdtempSync(Path.join(os.tmpdir(), 'xycli-upgrade-'));
+	t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+	
+	return {
+		requestFile: Path.join(dir, 'request.json'),
+		spawnFile: Path.join(dir, 'spawn.json'),
+		run(args, options = {}) {
+			return xy(['upgrade', ...args], {
+				preload: preload,
+				fail: options.fail,
+				env: {
+					...offlineEnv,
+					XYCLI_TEST_LATEST_VERSION: latest,
+					XYCLI_TEST_REQUEST_FILE: this.requestFile,
+					XYCLI_TEST_SPAWN_FILE: this.spawnFile,
+					...options.env
+				}
+			});
+		}
+	};
+}
+
+test('upgrade checks npm and works without xyOps credentials', t => {
+	const fixture = createUpgradeFixture(t, pkg.version);
+	const output = fixture.run([]);
+	const request = JSON.parse(fs.readFileSync(fixture.requestFile, 'utf8'));
+	const escaped_version = pkg.version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+	
+	assert.equal(request.url, 'https://registry.npmjs.org/@pixlcore%2Fxycli/latest');
+	assert.equal(request.headers.Accept, 'application/json');
+	assert.match(request.headers['User-Agent'], /^@pixlcore\/xycli\/v/);
+	assert.match(output, new RegExp('Installed Version:\\s+v' + escaped_version));
+	assert.match(output, new RegExp('Latest Version:\\s+v' + escaped_version));
+	assert.match(output, /Up to date/);
+	assert.equal(fs.existsSync(fixture.spawnFile), false);
+});
+
+test('upgrade advertises a newer version without installing it', t => {
+	const fixture = createUpgradeFixture(t, '99.0.0');
+	const output = fixture.run([]);
+	
+	assert.match(output, /Upgrade available/);
+	assert.match(output, /A new xyCLI version is available!/);
+	assert.match(output, /--confirm/);
+	assert.equal(fs.existsSync(fixture.spawnFile), false);
+});
+
+test('confirmed upgrade installs the exact checked version with inherited stdio', t => {
+	const fixture = createUpgradeFixture(t, '99.0.0');
+	const output = fixture.run(['--confirm']);
+	const spawn = JSON.parse(fs.readFileSync(fixture.spawnFile, 'utf8'));
+	
+	assert.match(output, /Running command:\s+npm install --global @pixlcore\/xycli@99\.0\.0/);
+	assert.match(output, /Successfully upgraded xyCLI to v99\.0\.0/);
+	assert.equal(spawn.command, 'npm install --global @pixlcore/xycli@99.0.0');
+	assert.equal(spawn.shell, true);
+	assert.equal(spawn.stdio, 'inherit');
+	assert.equal(spawn.windowsHide, false);
+});
+
+test('upgrade dry run prints the pinned command without spawning npm', t => {
+	const fixture = createUpgradeFixture(t, '99.0.0');
+	const output = fixture.run(['--confirm', '--dry']);
+	
+	assert.match(output, /npm install --global @pixlcore\/xycli@99\.0\.0/);
+	assert.match(output, /DRY RUN: The upgrade command was not executed/);
+	assert.equal(fs.existsSync(fixture.spawnFile), false);
+});
+
+test('upgrade never downgrades a newer local version', t => {
+	const fixture = createUpgradeFixture(t, '0.0.1');
+	const output = fixture.run(['--confirm']);
+	
+	assert.match(output, /Installed version is newer than npm/);
+	assert.equal(fs.existsSync(fixture.spawnFile), false);
+});
+
+test('upgrade rejects malformed registry versions before spawning a shell', t => {
+	const fixture = createUpgradeFixture(t, '99.0.0; unwanted-command');
+	const output = fixture.run(['--confirm'], { fail: true });
+	
+	assert.match(output, /Invalid version/);
+	assert.equal(fs.existsSync(fixture.spawnFile), false);
+});
+
+test('upgrade reports registry and npm process failures', async t => {
+	await t.test('registry failure', t => {
+		const fixture = createUpgradeFixture(t, '99.0.0');
+		const output = fixture.run([], {
+			fail: true,
+			env: { XYCLI_TEST_FETCH_ERROR: 'fixture network failure' }
+		});
+		assert.match(output, /Could not contact the npm registry: fixture network failure/);
+	});
+	
+	await t.test('npm failure', t => {
+		const fixture = createUpgradeFixture(t, '99.0.0');
+		const output = fixture.run(['--confirm'], {
+			fail: true,
+			env: { XYCLI_TEST_SPAWN_EXIT: '7' }
+		});
+		assert.match(output, /Upgrade command failed with exit code: 7/);
+	});
+});