@pixlcore/xycli 1.0.8 → 1.1.0

package/lib/sync-syshook.js

@@ -0,0 +1,207 @@
+// Local XYPDF deletion for xyOps System Hooks.
+// This command never updates definitions or queries the remote server.
+
+const fs = require('fs');
+const Path = require('path');
+const cli = require('pixl-cli');
+const Tools = cli.Tools;
+
+const MAX_HOOK_BYTES = 64 * 1024 * 1024;
+
+// Map each supported xyOps deletion activity to both its STDIN payload key
+// and its XYPDF item type.  API Keys use "apikey" in the activity name but
+// "api_key" in the payload; workflows are stored as Event definitions.
+// Buckets are excluded because their data and uploaded files need separate
+// deletion handling beyond the single XYPDF source and its property files.
+const HOOK_TYPES = {
+	alert_delete: 'alert',
+	apikey_delete: 'api_key',
+	category_delete: 'category',
+	channel_delete: 'channel',
+	event_delete: 'event',
+	group_delete: 'group',
+	monitor_delete: 'monitor',
+	plugin_delete: 'plugin',
+	tag_delete: 'tag',
+	web_hook_delete: 'web_hook'
+};
+
+async function readHookPayload() {
+	// System Hooks send one JSON activity object followed by a newline.  Read
+	// until EOF so a partial pipe write cannot be mistaken for a valid event.
+	if (process.stdin.isTTY) throw new Error("System Hook sync requires an activity payload on STDIN.");
+	
+	var chunks = [];
+	var size = 0;
+	for await (const chunk of process.stdin) {
+		var buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+		size += buffer.length;
+		if (size > MAX_HOOK_BYTES) throw new Error("System Hook activity payload is too large.");
+		chunks.push(buffer);
+	}
+	
+	if (!size) throw new Error("System Hook activity payload is empty.");
+	
+	try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+	catch (err) { throw new Error("Invalid System Hook activity JSON: " + err.message); }
+}
+
+function listLocalFiles(dir) {
+	// Match ordinary sync's visible-file scan, but never follow symbolic links.
+	// A local delete must not cross into an unrelated tree through a link.
+	var files = [];
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith('.')) continue;
+		var file = Path.join(dir, entry.name);
+		if (entry.isDirectory()) files.push(...listLocalFiles(file));
+		else if (entry.isFile()) files.push(file);
+	}
+	return files;
+}
+
+function isInsideDir(file, dir) {
+	var relative = Path.relative(dir, file);
+	return !!relative && (relative != '..') && !relative.startsWith('..' + Path.sep) && !Path.isAbsolute(relative);
+}
+
+function scanSources(files) {
+	// Index every valid XYPDF stem, not only the target item.  A source named
+	// "Foo" must not claim property files belonging to "Foo-V2".
+	var sources = [];
+	var bucket_dirs = [];
+	var parse_errors = [];
+	for (const file of files.filter( file => file.match(/\.json$/i) )) {
+		var raw = null;
+		try { raw = fs.readFileSync(file, 'utf8'); }
+		catch (err) { throw new Error("Failed to read JSON file: " + file + ": " + err.message); }
+		
+		var xypdf = null;
+		try { xypdf = JSON.parse(raw); }
+		catch (err) {
+			parse_errors.push({ file, err });
+			continue;
+		}
+		if (!xypdf || (xypdf.type !== 'xypdf')) continue;
+		
+		var stem = Path.basename(file).replace(/\.json$/i, '');
+		var item = Array.isArray(xypdf.items) && (xypdf.items.length === 1) ? xypdf.items[0] : null;
+		if (item && (item.type === 'bucket')) bucket_dirs.push(file.replace(/\.json$/i, ''));
+		sources.push({ file, stem, xypdf, item });
+	}
+	
+	// Bucket uploaded files are opaque content even when named *.json.  They
+	// must not participate in this definition source inventory.
+	for (const entry of parse_errors) {
+		if (bucket_dirs.some( dir => isInsideDir(entry.file, dir) )) continue;
+		throw new Error("Failed to parse JSON file: " + entry.file + ": " + entry.err.message);
+	}
+	
+	return sources.filter( source => !bucket_dirs.some( dir => isInsideDir(source.file, dir) ) );
+}
+
+function findOwnedNeighbors(app, files, sources, source) {
+	var dir = Path.dirname(source.file);
+	var stem = source.stem;
+	var source_stems = sources.filter( item => Path.dirname(item.file) === dir )
+		.map( item => item.stem ).sort( (a, b) => b.length - a.length );
+	var neighbors = [];
+	
+	for (const file of files) {
+		if (Path.dirname(file) !== dir || file === source.file) continue;
+		var name = Path.basename(file);
+		var name_stem = name.replace(/\.\w+$/, '');
+		if (!name_stem.startsWith(stem + '-')) continue;
+		
+		// The longest XYPDF prefix owns a neighboring property file.  Another
+		// XYPDF is always its own source, even if its name looks like a neighbor.
+		var owner = source_stems.find( other => name_stem.startsWith(other + '-') );
+		if (owner && (owner !== stem)) continue;
+		if (sources.some( other => other.file === file )) continue;
+		
+		var prop_path = name_stem.substring(stem.length + 1);
+		if (!prop_path.match(/^[\w\.\-]+$/) ||
+			(typeof(app.getSyncPropByPath(source.item.data, prop_path)) !== 'string')) {
+			throw new Error("Neighbor file does not match a string property: " + file);
+		}
+		neighbors.push(file);
+	}
+	return neighbors;
+}
+
+module.exports = {
+	
+	async runSyncSyshook() {
+		// The argument is an exact activity action, not a general sync direction.
+		// Ignore saved up/down/delete settings by never entering ordinary sync.
+		var action = this.args.syshook;
+		var type = HOOK_TYPES[action];
+		if (!type) this.die("Invalid --syshook action (use one of: " + Object.keys(HOOK_TYPES).join(', ') + ").");
+		if (['up', 'down', 'delete', 'setup', 'new'].some( key => key in this.args )) {
+			this.die("--syshook cannot be combined with ordinary sync modes.");
+		}
+		if (!this.args.other || (this.args.other.length !== 1)) {
+			this.die("--syshook requires exactly one sync directory.");
+		}
+		if (this.args.down_cmd && (typeof(this.args.down_cmd) !== 'string')) {
+			this.die("--down_cmd must be a shell command.");
+		}
+		
+		var dir = Path.resolve(this.args.other[0]);
+		var stat = null;
+		try { stat = fs.statSync(dir); }
+		catch (err) { this.die("Sync directory is not accessible: " + dir + ": " + err.message); }
+		if (!stat.isDirectory()) this.die("Sync path is not a directory: " + dir);
+		this.args.other = [dir]; // completion commands run from this directory
+		this.sconfig = Tools.mergeHashes(this.config.sync || {}, this.args);
+		this.warnings = [];
+		this.errors = [];
+		
+		var payload = null;
+		try { payload = await readHookPayload(); }
+		catch (err) { this.die(err.message); }
+		if (!payload || (typeof(payload) !== 'object') || Array.isArray(payload) ||
+			(payload.xy !== 1) || (payload.action !== action)) {
+			this.die("System Hook activity does not match --syshook " + action + ".");
+		}
+		var object = payload[type];
+		if (!object || (typeof(object) !== 'object') || Array.isArray(object) ||
+			(typeof(object.id) !== 'string') || !object.id.match(/^[a-z0-9_]+$/)) {
+			this.die("System Hook activity is missing a valid " + type + " ID.");
+		}
+		
+		// Identify the single local source by its stored type and ID, never by
+		// title or filename.  Read the entire local inventory before changing it.
+		var files = [];
+		var sources = [];
+		try {
+			files = listLocalFiles(dir);
+			sources = scanSources(files);
+		}
+		catch (err) { this.die("Failed to scan sync directory: " + err.message); }
+		var matches = sources.filter( source => source.item && (source.item.type === type) &&
+			source.item.data && (source.item.data.id === object.id) );
+		if (matches.length > 1) this.die("Duplicate XYPDF sources for " + type + " ID " + object.id + ".");
+		if (!matches.length) {
+			println("No local XYPDF source found for " + type + " ID " + object.id + ".");
+			return;
+		}
+		var source = matches[0];
+		if (source.xypdf.version !== '1.0') this.die("Cannot delete incompatible XYPDF source: " + source.file);
+		
+		var neighbors = [];
+		try { neighbors = findOwnedNeighbors(this, files, sources, source); }
+		catch (err) { this.die(err.message); }
+		var targets = [...neighbors, source.file]; // keep JSON last for safe retries
+		
+		for (const file of targets) {
+			println((this.dry ? "Would delete: " : "Deleting: ") + file);
+			if (this.dry) continue;
+			try { fs.unlinkSync(file); }
+			catch (err) { this.die("Failed to delete local file: " + file + ": " + err.message); }
+		}
+		
+		// A dry run and a missing local source never trigger Git commands.  Run
+		// only the explicitly supplied down_cmd after a real local deletion.
+		if (!this.dry && this.args.down_cmd) this.syncFinishCmd(this.args.down_cmd);
+	}
+};

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
@@ -48,6 +52,7 @@ module.exports = {
 		
 		// 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.");
 		}
@@ -71,10 +76,10 @@ module.exports = {
 		if (sconfig.delete && !Tools.includesAll(supported_lists, sconfig.delete)) this.die("Invalid sync.delete list: " + sconfig.delete.join(', '));
 		if (sconfig.delete && !sconfig.delete.length) sconfig.delete = false;
 		
-		// Deletion requires up-only sync, including directions inherited from config.
-		// Validate before scanning or applying any changes, even for a dry run.
-		if (sconfig.delete && (!sconfig.up || sconfig.down)) {
-			this.die("Delete mode requires up-only sync. Enable --up and disable --down.");
+		// Deletion follows the sole enabled direction.  Validate settings inherited
+		// from config as well as command-line args before scanning or writing.
+		if (sconfig.delete && (!!sconfig.up === !!sconfig.down)) {
+			this.die("Delete mode requires exactly one sync direction: --up or --down.");
 		}
 		
 		// Bucket content needs the replacement API and data timestamps introduced
@@ -137,6 +142,8 @@ module.exports = {
 		
 		// load all xypdf files
 		var items = [];
+		var local_delete_items = [];
+		var seen_sources = new Map();
 		
 		files.filter( file => !!file.path.match(/\.json$/i) && !this.isSyncBucketExtraFile(file.path, bucket_extra_dirs) ).forEach( file => {
 			// file: { path, size, mtime }
@@ -211,16 +218,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;
@@ -282,19 +287,38 @@ module.exports = {
 				// include neighbor metadata for downsync
 				if (!item.neighbors) item.neighbors = {};
 				item.neighbors[ prop_path ] = neighbor.path;
+				if (!item.delete_neighbors) item.delete_neighbors = [];
+				item.delete_neighbors.push(neighbor.path);
 			} ); // foreach neighbor
 			
 			// do not include item if neighbor loading or validation failed
 			if (neighbor_error) return;
 			
-			// include effective mtime in item for two-way sync
-			item.mtime = file.mtime;
-			
-			// include list name for convenience below
 			item.list = type_def.list;
-			
-			// include file for downsync
 			item.file = file.path;
+			var xy_item = Tools.findObject(list, { id: item.data.id });
+			if (!xy_item) {
+				// In a down-only delete run, xyOps owns this definition type.
+				// Queue its local files for the final destructive pass, after every
+				// source and neighbor has passed the normal scan validation.
+				if (sconfig.delete && sconfig.down && sconfig.delete.includes(item.list)) {
+					local_delete_items.push(item);
+					return;
+				}
+				
+				// 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;
 			
 			// add to sync list
 			items.push(item);
@@ -396,7 +420,12 @@ module.exports = {
 		// now handle deletes
 		if (!sconfig.delete) return await this.completeSync();
 		
-		// (deletes always happen upward, i.e. in xyops)
+		if (sconfig.down) {
+			this.deleteSyncLocalItems(local_delete_items);
+			return await this.completeSync();
+		}
+		
+		// Up-only deletion removes remote definitions absent from the local tree.
 		var list_data_types = [];
 		for (var id in this.config.ui.data_types) {
 			var type_def = this.config.ui.data_types[id];
@@ -433,13 +462,105 @@ module.exports = {
 		await this.completeSync();
 	},
 	
+	deleteSyncLocalItems(items) {
+		// Validate every selected local deletion before removing any files.  The
+		// normal source scan has already checked XYPDF identity and neighboring
+		// property paths; recheck the source and file types in case a checkout or
+		// another process changed the tree while this sync was running.
+		var plans = [];
+		for (const item of items) {
+			// Match the protection used by upward deletion for bundled or
+			// Marketplace definitions.  A local source may retain these markers
+			// even after its remote record has disappeared.
+			if (Object.hasOwn(item.data, 'stock') || Object.hasOwn(item.data, 'marketplace')) continue;
+			
+			var bucket_plan = null;
+			try {
+				if (item.type === 'bucket') bucket_plan = this.getSyncBucketLocalDeletePlan(item);
+			}
+			catch (err) {
+				this.logSyncError("Local delete preflight failed: " + err.message);
+				return;
+			}
+			var targets = [...new Set(item.delete_neighbors || []), ...(bucket_plan ? bucket_plan.files : []), item.file];
+			var dirs = bucket_plan ? bucket_plan.dirs : [];
+			try {
+				for (const file of targets) {
+					var stat = fs.lstatSync(file);
+					if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Local deletion target is not a regular file: " + file);
+				}
+				for (const dir of dirs) {
+					var stat = fs.lstatSync(dir);
+					if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error("Local deletion target is not a regular directory: " + dir);
+				}
+				var source = Tools.parseJSON(fs.readFileSync(item.file, 'utf8'));
+				var source_item = source && Array.isArray(source.items) && (source.items.length === 1) ? source.items[0] : null;
+				if (!source || (source.type !== 'xypdf') || (source.version !== '1.0') || !source_item ||
+					(source_item.type !== item.type) || !source_item.data || (source_item.data.id !== item.data.id)) {
+					throw new Error("Local XYPDF source changed during sync: " + item.file);
+				}
+			}
+			catch (err) {
+				this.logSyncError("Local delete preflight failed: " + err.message);
+				return;
+			}
+			plans.push({ item, targets, dirs });
+		}
+		
+		for (const plan of plans) {
+			println( "\n " + cli.emoji('🗑️') + ' ' + red.bold(this.dry ? "Would delete local " : "Deleting local ") +
+				red.bold(plan.item.type) + ": " + red.bold(plan.item.data.title || plan.item.data.id) +
+				gray(" (" + plan.item.data.id + ")") );
+			// Keep the XYPDF JSON source last so a partial filesystem failure
+			// leaves the identity available for a later retry.
+			for (const file of plan.targets.slice(0, -1)) {
+				println("    " + file);
+				if (this.dry) continue;
+				try {
+					fs.unlinkSync(file);
+					this.downSynced = true;
+				}
+				catch (err) {
+					this.logSyncError("Failed to delete local file: " + file + ": " + err.message);
+					return;
+				}
+			}
+			for (const dir of plan.dirs) {
+				println("    " + dir + Path.sep);
+				if (this.dry) continue;
+				try {
+					fs.rmdirSync(dir);
+					this.downSynced = true;
+				}
+				catch (err) {
+					this.logSyncError("Failed to delete local directory: " + dir + ": " + err.message);
+					return;
+				}
+			}
+			var source_file = plan.targets[plan.targets.length - 1];
+			println("    " + source_file);
+			if (this.dry) continue;
+			try {
+				fs.unlinkSync(source_file);
+				this.downSynced = true;
+			}
+			catch (err) {
+				this.logSyncError("Failed to delete local file: " + source_file + ": " + err.message);
+				return;
+			}
+		}
+	},
+	
 	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' );
 	},
 	
@@ -824,8 +945,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',
@@ -889,7 +1011,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 = [];
@@ -900,6 +1022,7 @@ module.exports = {
 		});
 		
 		var index = {};
+		var seen_sources = new Map();
 		var bucket_extra_dirs = [];
 		files.filter( file => !!file.path.match(/\.json$/i) ).forEach( file => {
 			try {
@@ -941,14 +1064,26 @@ 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 };
 		});
 		

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);
 		}
 		
@@ -1265,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.8",
+	"version": "1.1.0",
 	"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-buckets-unit.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

@@ -66,10 +66,10 @@ node --test test/config.test.js test/sync-buckets-unit.test.js test/sync-unit.te
 | `secrets` | Vault metadata, assignments, redacted previews, full field replacement, confirmed decryption, deletion, validation, help |
 | `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` | Setup export, isolated filesystem discovery, external property files, dry-run, upsync, downsync, composite global-state governance, no-op detection, up-only deletion, and down-only Event and Plugin file deletion |
+| `sync-buckets` | Disposable Bucket setup, JSON replacement, file upload and download, timestamp alignment, and down-only local file and whole-Bucket deletion 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 |
+| `sync-unit` | Offline setup extension fallbacks, new-only exports and setup completion commands, PID locking and stale recovery, one-way 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 |
 | `toast` | Warning-box word wrapping and terminal-width limits |

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/);
+});