@pixlcore/xycli 1.0.5 → 1.0.6

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # xyCLI Changelog
 
+## 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

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
@@ -312,6 +314,20 @@ An explicitly supplied `--down_cmd` runs from the current setup directory after
 
 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/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/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
+				
+				// 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 suffix = nstem.substring(stem.length);
-				if (!suffix.match(/\-([\w\.\-]+)$/)) return; // not correct format
-				var prop_path = RegExp.$1;
+				var prop_path = nstem.substring(stem.length + 1);
+				if (!prop_path.match(/^[\w\.\-]+$/)) return; // not correct format
 				
 				var content = '';
 				try {

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.6",
 	"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

@@ -583,6 +583,78 @@ 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('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/);
+	});
+});