@pixlcore/xycli 1.0.7 → 1.0.9

package/lib/sync.js

@@ -28,6 +28,10 @@ module.exports = {
 		// sync a filesystem of XYPDF files to xyOps resources
 		// xy sync --up all --dry
 		// xy sync --up "events,plugins" --delete plugins
+		// System Hook deletion is a separate, local-only command.  Dispatch it
+		// before loading remote lists or interpreting ordinary sync directions.
+		if ('syshook' in this.args) return await this.runSyncSyshook();
+		
 		await this.getMultiple();
 		
 		// Both ordinary sync and setup completion commands report failures through
@@ -44,10 +48,11 @@ module.exports = {
 		
 		println( "\n " + cli.emoji('🔄') + ' ' + this.color('theme').bold("XYOPS SYNC ENGINE v1") );
 		
-		var supported_lists = this.config.ui.list_list.map( list => list.id ).filter( id => !id.match(/^(buckets|secrets|users|roles)$/) );
+		var supported_lists = this.config.ui.list_list.map( list => list.id ).filter( id => !id.match(/^(secrets|users|roles)$/) );
 		
 		// allow sync config in config files and/or cli args
 		var sconfig = this.sconfig = Tools.mergeHashes( this.config.sync || {}, this.args || {} );
+		var ignore_missing = !!sconfig.ignore_missing;
 		if (!sconfig.up && !sconfig.down) {
 			this.die("Please enable sync up and/or down modes.  Type 'xy help sync' for details.");
 		}
@@ -77,6 +82,13 @@ module.exports = {
 			this.die("Delete mode requires up-only sync. Enable --up and disable --down.");
 		}
 		
+		// Bucket content needs the replacement API and data timestamps introduced
+		// in xyOps 1.1.2. Check before any ordinary sync changes are applied.
+		if ((sconfig.up && sconfig.up.includes('buckets')) || (sconfig.down && sconfig.down.includes('buckets')) ||
+			(sconfig.delete && sconfig.delete.includes('buckets'))) {
+			this.requireBucketSyncVersion();
+		}
+
 		// scan all base directories, default to cwd
 		var files = [];
 		if (!this.args.other || !this.args.other.length) {
@@ -106,11 +118,15 @@ module.exports = {
 		// 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();
+		var bucket_extra_dirs = [];
 		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;
+			if (Array.isArray(xypdf.items) && xypdf.items.length == 1 && xypdf.items[0].type == 'bucket') {
+				bucket_extra_dirs.push(file.path.replace(/\.json$/i, ''));
+			}
 			
 			var dir = Path.dirname(file.path);
 			var stems = source_stems_by_dir.get(dir);
@@ -126,8 +142,9 @@ module.exports = {
 		
 		// load all xypdf files
 		var items = [];
+		var seen_sources = new Map();
 		
-		files.filter( file => !!file.path.match(/\.json$/i) ).forEach( file => {
+		files.filter( file => !!file.path.match(/\.json$/i) && !this.isSyncBucketExtraFile(file.path, bucket_extra_dirs) ).forEach( file => {
 			// file: { path, size, mtime }
 			var dir = Path.dirname(file.path);
 			var filename = Path.basename(file.path);
@@ -175,7 +192,7 @@ module.exports = {
 				this.logSyncWarning("Malformed item type in file: " + file.path);
 				return;
 			}
-			if (item.type.match(/^(bucket|secret|user|role)$/)) {
+			if (item.type.match(/^(secret|user|role)$/)) {
 				this.logSyncWarning("Unsupported item type: " + item.type + " in file: " + file.path);
 				return;
 			}
@@ -200,16 +217,14 @@ module.exports = {
 				return;
 			}
 			
-			var xy_item = Tools.findObject(list, { id: item.data.id });
-			if (!xy_item) {
-				this.logSyncWarning("Cannot find " + item.type + " in xyOps: " + item.data.title + " (" + item.data.id + "), will be skipped from sync.");
-				return;
-			}
-			
-			if (Tools.findObjectDeep(items, { 'type': item.type, 'data.id': item.data.id })) {
+			// Check duplicate identities even when their remote definition is
+			// missing, so --ignore_missing only relaxes the missing-ID check.
+			var source_key = item.type + '\0' + item.data.id;
+			if (seen_sources.has(source_key)) {
 				this.logSyncWarning("Duplicate source item found: " + file.path + " (skipping)");
 				return;
 			}
+			seen_sources.set(source_key, file.path);
 			
 			// locate any external neighbor prop files
 			var neighbor_error = false;
@@ -276,6 +291,19 @@ module.exports = {
 			// do not include item if neighbor loading or validation failed
 			if (neighbor_error) return;
 			
+			var xy_item = Tools.findObject(list, { id: item.data.id });
+			if (!xy_item) {
+				// An opted-in Git sync can briefly retain a source after its xyOps
+				// definition is deleted.  Skip only that source and keep scanning.
+				if (ignore_missing) {
+					println(" Skipping local " + item.type + " missing from xyOps: " + (item.data.title || item.data.id) + " (" + item.data.id + ")");
+					return;
+				}
+				
+				this.logSyncWarning("Cannot find " + item.type + " in xyOps: " + item.data.title + " (" + item.data.id + "), will be skipped from sync.");
+				return;
+			}
+			
 			// include effective mtime in item for two-way sync
 			item.mtime = file.mtime;
 			
@@ -313,24 +341,8 @@ module.exports = {
 			var changes = this.diffSyncItems(xy_item, item.data);
 			if (!changes.some( change => change.added || change.removed )) continue; // identical
 			
-			// render diff
-			var diff = "```diff\n";
-			changes.forEach( change => {
-				var prefix = change.added ? '+' : change.removed ? '-' : ' ';
-				var lines = change.value.replace(/\n$/, '').split(/\n/);
-				
-				if (!change.added && !change.removed && (lines.length > 2) && !this.verbose) {
-					// reduce context lines to 1 above and 1 below, unless in verbose mode
-					var top = lines.shift();
-					var bottom = lines.pop();
-					lines = [ top, "...", bottom ];
-				}
-				
-				lines.forEach( line => {
-					diff += prefix + line.trimEnd() + "\n";
-				} );
-			} );
-			diff += "```\n";
+			// Use the same highlighted, context-trimmed diff for every sync item.
+			var diff = this.formatSyncDiff(changes);
 			
 			// figure out which direction to go
 			var direction = false;
@@ -358,7 +370,7 @@ module.exports = {
 			if (direction == 'up') {
 				// sync change up to xyops
 				try {
-					await this.callStandardAPI('update_' + item.type, item.data, { text: "Updating " + item.type + "...", throw: true });
+					await this.callStandardAPI('update_' + item.type, item.data, { text: "Updating " + item.type + "...", throw: true, sync: true });
 					
 					// add flag to run optional command at completion
 					this.upSynced = true;
@@ -383,6 +395,12 @@ module.exports = {
 		
 		// update state db
 		await this.syncState(state);
+
+		// Bucket metadata is handled above like every other XYPDF item. Its data
+		// and binary files have their own storage records and reconciliation pass.
+		if (sconfig.up && sconfig.up.includes('buckets') || sconfig.down && sconfig.down.includes('buckets')) {
+			await this.syncBucketContents(items.filter( item => item.type == 'bucket' ), sconfig);
+		}
 		
 		// Deletion is the destructive final phase, so only begin it after every
 		// update and the sync-state write completed cleanly.  Earlier successful
@@ -418,7 +436,7 @@ module.exports = {
 				println( "\n " + cli.emoji('🗑️') + ' ' + red.bold("Deleting " + type_def.id) + ": " + red.bold(xy_item.title) + gray(" (" + xy_item.id + ")") );
 				
 				try {
-					await this.callStandardAPI('delete_' + type_def.id, { id: xy_item.id }, { text: "Deleting " + type_def.id + "...", throw: true });
+					await this.callStandardAPI('delete_' + type_def.id, { id: xy_item.id }, { text: "Deleting " + type_def.id + "...", throw: true, sync: true });
 					
 					// add flag to run optional command at completion
 					this.upSynced = true;
@@ -434,11 +452,14 @@ module.exports = {
 	
 	getSyncLockFile() {
 		// Allow a fixed path for service installations.  Otherwise, serialize all
-		// local syncs targeting the exact same configured xyOps base URL.
+		// local syncs targeting the exact same configured xyOps base URL.  Local
+		// System Hook deletions need no server config, so share a fixed lock key
+		// when no base URL is available.
 		var sconfig = Tools.mergeHashes( this.config.sync || {}, this.args || {} );
 		if (sconfig.lock_file) return Path.resolve('' + sconfig.lock_file);
 		
-		var digest = Tools.digestHex( this.config.base_url, 'sha256', 16);
+		var base_url = this.config.base_url || (('syshook' in this.args) ? 'syshook-local' : '');
+		var digest = Tools.digestHex( base_url, 'sha256', 16);
 		return Path.join( os.tmpdir(), 'xyops-cli-sync-' + digest + '.pid' );
 	},
 	
@@ -743,6 +764,27 @@ module.exports = {
 		);
 	},
 	
+	formatSyncDiff(changes) {
+		// Render a diff code block for the CLI Markdown highlighter. Keep long
+		// unchanged sections compact unless the user requested verbose output.
+		var diff = "```diff\n";
+		changes.forEach( change => {
+			var prefix = change.added ? '+' : change.removed ? '-' : ' ';
+			var lines = change.value.replace(/\n$/, '').split(/\n/);
+			
+			if (!change.added && !change.removed && (lines.length > 2) && !this.verbose) {
+				var top = lines.shift();
+				var bottom = lines.pop();
+				lines = [ top, "...", bottom ];
+			}
+			
+			lines.forEach( line => {
+				diff += prefix + line.trimEnd() + "\n";
+			} );
+		} );
+		return diff + "```\n";
+	},
+	
 	logSyncWarning(msg) {
 		this.warnings.push(msg);
 		
@@ -769,14 +811,14 @@ module.exports = {
 		// xy sync --setup events --new
 		// xy sync --setup all --marketplace --stock --force
 		if ((this.args.setup === 'all') || (this.args.setup[0] === 'all')) {
-			this.args.setup = this.config.ui.list_list.map( list => list.id ).filter( id => !id.match(/^(buckets|secrets|users|roles)$/) );
+			this.args.setup = this.config.ui.list_list.map( list => list.id ).filter( id => !id.match(/^(secrets|users|roles)$/) );
 		}
 		
 		if (typeof(this.args.setup) == 'string') this.args.setup = this.args.setup.split(/\,/);
 		if (!Array.isArray(this.args.setup)) this.dieUsage('sync setup');
 		
-		if (Tools.includesAny(this.args.setup, ['buckets', 'secrets', 'users', 'roles'])) {
-			this.die("Sorry, the sync engine cannot process buckets, secrets, users, or roles.");
+		if (Tools.includesAny(this.args.setup, ['secrets', 'users', 'roles'])) {
+			this.die("Sorry, the sync engine cannot process secrets, users, or roles.");
 		}
 		
 		if (!Tools.includesAll(this.config.ui.list_list.map( list => list.id ), this.args.setup)) {
@@ -784,6 +826,7 @@ module.exports = {
 		}
 		
 		if (!this.args.setup.length) this.die("No item types specified to set up.");
+		if (this.args.setup.includes('buckets')) this.requireBucketSyncVersion();
 		
 		if (this.args.file_props) {
 			if (typeof(this.args.file_props) == 'string') this.args.file_props = this.args.file_props.split(/\,/);
@@ -801,8 +844,9 @@ module.exports = {
 		}
 		if (new_only && this.args.force) this.die("Sync setup --new cannot be combined with --force.");
 		
+		var ignore_missing = !!this.args.ignore_missing;
 		var default_ext = this.normalizeSyncDefaultExt(this.args.default_ext);
-		var existing_keys = new_only ? this.scanSyncSourceIndex(['.']) : {};
+		var existing_keys = new_only ? this.scanSyncSourceIndex(['.'], { ignore_missing }) : {};
 		
 		this.printBoxList({
 			title: 'Sync Setup',
@@ -828,6 +872,13 @@ module.exports = {
 			force: !!this.args.force,
 			dry: !!this.dry
 		});
+
+		if (this.args.setup.includes('buckets')) {
+			await this.setupBucketContents(result.bucket_plans, {
+				force: !!this.args.force,
+				dry: !!this.dry
+			});
+		}
 		
 		if (new_only && !result.written) println( "\n " + gray("No new definitions found.") );
 		
@@ -859,7 +910,7 @@ module.exports = {
 		return ext;
 	},
 	
-	scanSyncSourceIndex(base_dirs) {
+	scanSyncSourceIndex(base_dirs, opts = {}) {
 		// Build an identity index from an existing sync tree.  Filenames and folders
 		// are deliberately ignored, because sync sources may be freely reorganized.
 		var files = [];
@@ -870,7 +921,19 @@ module.exports = {
 		});
 		
 		var index = {};
+		var seen_sources = new Map();
+		var bucket_extra_dirs = [];
 		files.filter( file => !!file.path.match(/\.json$/i) ).forEach( file => {
+			try {
+				var xypdf = Tools.parseJSON( fs.readFileSync(file.path, 'utf8') );
+				if (xypdf && xypdf.type == 'xypdf' && Array.isArray(xypdf.items) &&
+					xypdf.items.length == 1 && xypdf.items[0].type == 'bucket') {
+					bucket_extra_dirs.push(file.path.replace(/\.json$/i, ''));
+				}
+			}
+			catch (err) {;} // report malformed source files during the real scan
+		});
+		files.filter( file => !!file.path.match(/\.json$/i) && !this.isSyncBucketExtraFile(file.path, bucket_extra_dirs) ).forEach( file => {
 			var xypdf = null;
 			try { xypdf = Tools.parseJSON( fs.readFileSync(file.path, 'utf8') ); }
 			catch (err) { this.die("Failed to parse JSON file: " + file.path + ": " + err); }
@@ -889,7 +952,7 @@ module.exports = {
 			if (!item || !Tools.isaHash(item) || !item.type || (typeof(item.type) != 'string')) {
 				this.die("Malformed item type in file: " + file.path);
 			}
-			if (item.type.match(/^(bucket|secret|user|role)$/)) {
+			if (item.type.match(/^(secret|user|role)$/)) {
 				this.die("Unsupported item type: " + item.type + " in file: " + file.path);
 			}
 			if (!item.data || !Tools.isaHash(item.data) || !item.data.id || (typeof(item.data.id) != 'string')) {
@@ -900,20 +963,41 @@ module.exports = {
 			if (!type_def) this.die("Cannot locate internal type definition: " + item.type);
 			var list = this[type_def.list];
 			if (!list) this.die("Cannot locate internal list: " + type_def.list);
+			
+			// Keep duplicate detection independent of remote existence, including
+			// for sources intentionally skipped with --ignore_missing.
+			var key = item.type + '-' + item.data.id;
+			if (seen_sources.has(key)) {
+				this.die("Duplicate source item found: " + file.path + " (already found in " + seen_sources.get(key) + ")");
+			}
+			seen_sources.set(key, file.path);
+			
 			if (!Tools.findObject(list, { id: item.data.id })) {
+				// New-only setup needs the same grace period as ordinary sync.
+				// A missing local source does not represent a new remote item.
+				if (opts.ignore_missing) {
+					println(" Skipping local " + item.type + " missing from xyOps: " + (item.data.title || item.data.id) + " (" + item.data.id + ")");
+					return;
+				}
+				
 				this.die("Cannot find " + item.type + " in xyOps: " + (item.data.title || item.data.id) + " (" + item.data.id + ")");
 			}
 			
-			var key = item.type + '-' + item.data.id;
-			if (index[key]) {
-				this.die("Duplicate source item found: " + file.path + " (already found in " + index[key].file + ")");
-			}
 			index[key] = { file: file.path, item: item };
 		});
 		
 		return index;
 	},
 	
+	isSyncBucketExtraFile(file, dirs) {
+		// Bucket data and uploaded files are opaque to the XYPDF parser, even if
+		// a user uploaded a .json file with non-JSON contents.
+		return dirs.some( dir => {
+			var relative = Path.relative(dir, file);
+			return relative && (relative != '..') && !relative.startsWith('..' + Path.sep) && !Path.isAbsolute(relative);
+		});
+	},
+
 	writeSyncSetupFiles(list_names, opts = {}) {
 		// Write selected remote definitions using setup's suggested layout.  Keeping
 		// this operation separate allows a future downsync to append newly discovered
@@ -935,7 +1019,7 @@ module.exports = {
 			if (type_def) targets.push({ name: list_name, type: type_def.id, items: this[list_name] || [] });
 		});
 		
-		var result = { written: 0, skipped: 0 };
+		var result = { written: 0, skipped: 0, bucket_plans: [] };
 		var existing_keys = opts.existing_keys || {};
 		var base_dir = opts.base_dir || '.';
 		var default_ext = this.normalizeSyncDefaultExt(opts.default_ext);
@@ -1029,6 +1113,7 @@ module.exports = {
 				var title = plan.title;
 				var filename = title + '.json';
 				var file = Path.join(dir, filename);
+				if (target.type == 'bucket') result.bucket_plans.push({ id: item.id, file: file });
 				
 				if (!opts.dry) {
 					if (!opts.force && fs.existsSync(file)) this.die("File exists, add '--force' to overwrite all: " + file);

package/lib/transfer.js

@@ -86,7 +86,7 @@ module.exports = {
 		if (this.format.match(/json/)) return this.jsonOutput({ code: 0, file: filename, count: items.length, warnings: warnings });
 		
 		this.toast('✅', 'green', "Exported " + items.length + " item(s) to: " + filename);
-		warnings.forEach( warning => println(yellow(warning)) );
+		warnings.forEach( warning => warnln(yellow(warning)) );
 	},
 	
 	parseExportDependencies(value) {
@@ -316,7 +316,7 @@ module.exports = {
 		
 		if (this.format.match(/json/)) return this.jsonOutput(report);
 		
-		warnings.forEach( warning => println(yellow(warning)) );
+		warnings.forEach( warning => warnln(yellow(warning)) );
 		
 		this.printBoxTable({
 			title: 'Import Results',
@@ -324,7 +324,7 @@ module.exports = {
 			rows: results.map( item => [item.type, item.id || '(New)', item.title, item.status] )
 		});
 		
-		if (error) println("\n " + red('Import stopped: ' + error) + '\n Earlier successful changes remain in place.');
+		if (error) warnln("\n " + red('Import stopped: ' + error) + '\n Earlier successful changes remain in place.');
 		else this.printSuggestedCommands({
 			"List events": "xy events",
 			"List categories": "xy categories",

package/lib/utils.js

@@ -1011,7 +1011,7 @@ module.exports = {
 		// load client config from xyops and cache for a while
 		var { err, data } = await this.cacheAPI('config', { format: 'json' }, { cache_ttl: 3600 });
 		if (err) {
-			println( "\n" + bold.red("Failed to contact xyOps at: ") + this.config.base_url );
+			warnln( "\n" + bold.red("Failed to contact xyOps at: ") + this.config.base_url );
 			this.die(err);
 		}
 		
@@ -1057,7 +1057,8 @@ module.exports = {
 	async callStandardAPI(name, req, opts = {}) {
 		// wrapper around APIs that make a change
 		// indeterminate progress w/text, handle dry run, verbose req/res, etc.
-		this.validateStandardAPIRequest(name, req);
+		if (!opts.sync) this.validateStandardAPIRequest(name, req);
+		delete opts.sync;
 		
 		// Sensitive callers may supply a redacted display copy while the original
 		// request continues through validation and transport unchanged.
@@ -1264,7 +1265,11 @@ module.exports = {
 		// cli.box performs word wrapping at this content width and never ellipsizes.
 		var available_width = Math.max( 1, (cli.width() || 80) - 7 );
 		var max_width = Math.min( available_width, cli.stringWidth(final_text) );
-		println( "\n" + cli.box(final_text, { width: max_width, hspace: 2, vspace: 1, indent: 1, styles: [this.color(color)] }) );
+		var message = "\n" + cli.box(final_text, { width: max_width, hspace: 2, vspace: 1, indent: 1, styles: [this.color(color)] });
+		
+		// Keep warning and error toasts visible when routine output is quiet.
+		if (['⚠️', '🛑', '❌', '☢️'].includes(emoji)) warnln(message);
+		else println(message);
 	},
 	
 	printMutationSummary(opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pixlcore/xycli",
-	"version": "1.0.7",
+	"version": "1.0.9",
 	"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/upgrade.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-buckets-unit.test.js test/sync-syshook-unit.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/README.md

@@ -8,7 +8,7 @@ Use Node.js 22 or newer and install the CLI dependencies with `npm install`.
 
 Start xyOps at `http://localhost:5522` and configure an administrator API key using your normal CLI config file or the `XYOPS_API_KEY` environment variable. The tests read the same configuration as `xy`, including `XYOPS_BASE_URL` overrides. They refuse to run against a different server address.
 
-Use an xyOps version that supports restoring API key IDs, hashes, and masks through `create_api_key`. The Server and Job tests need a connected server, the Job tests need the enabled stock Shell Plugin, and the Monitor tests also need a server group. The log tests expect the standard log columns and debug entries in the current xyOps log.
+Use an xyOps version that supports restoring API key IDs, hashes, and masks through `create_api_key`. The `sync-buckets` suite requires xyOps 1.1.2 or later. The Server and Job tests need a connected server, the Job tests need the enabled stock Shell Plugin, and the Monitor tests also need a server group. The log tests expect the standard log columns and debug entries in the current xyOps log.
 
 ## Running Tests
 
@@ -42,10 +42,10 @@ node --test --test-reporter=spec test/monitors.test.js
 
 The controller exits with a nonzero status if any suite fails. A failed lifecycle check stops the remaining dependent steps in that suite, runs cleanup, and allows the next suite to proceed.
 
-The configuration and sync unit suites run offline with disposable directories and do not contact xyOps. Run them directly without configuring a development server:
+The configuration and sync unit suites, including `sync-buckets-unit`, run offline with disposable directories and do not contact xyOps. Run them directly without configuring a development server:
 
 ```sh
-node --test test/config.test.js test/sync-unit.test.js
+node --test test/config.test.js test/sync-buckets-unit.test.js test/sync-unit.test.js
 ```
 
 ## Coverage
@@ -67,6 +67,8 @@ node --test test/config.test.js test/sync-unit.test.js
 | `servers` | Active and recently offline lists, local filters, installer generation, historical search, live and historical Server details, charts, processes, connections, pagination, validation, help |
 | `system` | Admin dashboard, conductors, connected users, export, maintenance, optimization, rate resets, diagnostics, broadcasts, help |
 | `sync` | Setup export, isolated filesystem discovery, external property files, dry-run, upsync, downsync, composite global-state governance, no-op detection, and guarded delete mode |
+| `sync-buckets` | Disposable Bucket setup, JSON replacement, file upload and download, and timestamp alignment on xyOps 1.1.2 or later |
+| `sync-buckets-unit` | Offline Bucket version gating, content setup, upload and download, timestamp alignment, and pre-delete safety |
 | `sync-unit` | Offline setup extension fallbacks, new-only exports and setup completion commands, PID locking and stale recovery, up-only deletion guards, pre-delete failure blocking, stock/Marketplace deletion protection, inherited settings and CLI overrides, warning/error exit status, duplicates, quiet/dry runs, completion failures, and notification delivery after warnings or errors |
 | `tags` | CRUD, metadata search, sparse future-proof updates, JSON input, validation, pagination, help |
 | `tickets` | Search, CRUD, number resolution, comments, attachment uploads/downloads, Events, related Job lookup, sparse updates, validation, help |

package/test/help.test.js

@@ -1,6 +1,7 @@
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
 const Path = require('node:path');
+const { spawnSync } = require('node:child_process');
 const { xy } = require('./helpers/common.js');
 
 // Deliberately shadow any developer-machine configuration. Help and command
@@ -51,3 +52,58 @@ test('unknown top-level command does not suggest an unrelated command', () => {
 	assert.match(output, /Unknown command: completely_unrelated/);
 	assert.doesNotMatch(output, /Did you mean/);
 });
+
+test('quiet mode prints sync diagnostics and bound warnings on stderr', () => {
+	// Run the real CLI startup so this checks the warn override and the global
+	// binding installed by cli.global(), without contacting a server.
+	const script = `
+		process.argv = [process.execPath, require.resolve('./index.js'), 'help', '--quiet'];
+		process.on('beforeExit', () => {
+			const cli = require('pixl-cli');
+			cli.warnln('Fixture cli warning');
+			warnln('Fixture warning');
+			warn('Fixture direct warning\\n');
+			const utils = require('./lib/utils.js');
+			const context = { colors: { orange: [255, 105, 0], red: [251, 44, 54], green: [0, 201, 80] }, color: utils.color };
+			utils.toast.call(context, '⚠️', 'orange', 'Fixture toast warning');
+			utils.toast.call(context, '🛑', 'red', 'Fixture toast error');
+			utils.toast.call(context, '✅', 'green', 'Fixture success');
+			const sync = require('./lib/sync.js');
+			sync.logSyncWarning.call({ warnings: [] }, 'Fixture sync warning');
+			sync.logSyncError.call({ errors: [] }, 'Fixture sync error');
+			println('Routine output');
+		});
+		require('./index.js');
+	`;
+	const result = spawnSync(process.execPath, ['-e', script], {
+		cwd: Path.join(__dirname, '..'),
+		encoding: 'utf8',
+		env: { ...process.env, ...offlineEnv },
+		windowsHide: true
+	});
+	
+	assert.ifError(result.error);
+	assert.equal(result.status, 1);
+	assert.equal(result.stdout, '');
+	assert.match(result.stderr, /Fixture cli warning/);
+	assert.match(result.stderr, /Fixture warning/);
+	assert.match(result.stderr, /Fixture direct warning/);
+	assert.match(result.stderr, /Fixture toast warning/);
+	assert.match(result.stderr, /Fixture toast error/);
+	assert.match(result.stderr, /Fixture sync warning/);
+	assert.match(result.stderr, /Fixture sync error/);
+	assert.doesNotMatch(result.stderr, /Fixture success/);
+});
+
+test('quiet invalid usage reports an error on stderr', () => {
+	const result = spawnSync(process.execPath, [Path.join(__dirname, '..', 'index.js'), 'upgrade', 'unexpected', '--quiet'], {
+		encoding: 'utf8',
+		env: { ...process.env, ...offlineEnv },
+		windowsHide: true
+	});
+	
+	assert.ifError(result.error);
+	assert.equal(result.status, 1);
+	assert.equal(result.stdout, '');
+	assert.match(result.stderr, /Invalid usage.*xy help upgrade/);
+});