@pixlcore/xycli 1.0.6 → 1.0.8

package/lib/sync.js

@@ -44,7 +44,7 @@ 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 || {} );
@@ -77,6 +77,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 +113,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);
@@ -127,7 +138,7 @@ module.exports = {
 		// load all xypdf files
 		var items = [];
 		
-		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 +186,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;
 			}
@@ -253,13 +264,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;
@@ -313,24 +324,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 +353,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 +378,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 +419,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;
@@ -703,9 +704,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;
 				}
 				
@@ -743,6 +744,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 +791,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 +806,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(/\,/);
@@ -828,6 +851,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.") );
 		
@@ -870,7 +900,18 @@ module.exports = {
 		});
 		
 		var index = {};
+		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 +930,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')) {
@@ -914,6 +955,15 @@ module.exports = {
 		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 +985,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);
@@ -1006,10 +1056,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)" );
+							}
+						} );
 					}
 				});
 				
@@ -1017,6 +1079,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);
@@ -1188,6 +1251,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/utils.js

@@ -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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pixlcore/xycli",
-	"version": "1.0.6",
+	"version": "1.0.8",
 	"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-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/sync-buckets-unit.test.js

@@ -0,0 +1,188 @@
+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 bucketSync = require('../lib/sync-buckets.js');
+const sync = require('../lib/sync.js');
+const utils = require('../lib/utils.js');
+
+// The bucket pass uses the ordinary sync logging functions, whose output is
+// provided by pixl-cli in production. Keep the test output quiet and local.
+global.println = () => {};
+
+function fixture(t, options = {}) {
+	const dir = fs.mkdtempSync(Path.join(os.tmpdir(), 'xycli-bucket-sync-unit-'));
+	t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+	const item = { type: 'bucket', data: { id: 'bucket_unit', title: 'Changed Title' }, file: Path.join(dir, 'custom', 'Original-Name.json') };
+	const paths = bucketSync.getSyncBucketPaths(item);
+	fs.mkdirSync(paths.files, { recursive: true });
+	fs.writeFileSync(item.file, '{}');
+	fs.writeFileSync(paths.data, JSON.stringify(options.localData || { keep: true, removed: true }));
+	fs.utimesSync(paths.data, 100, options.localDataTime || 100);
+	
+	const remote = {
+		bucket: { id: item.data.id, title: item.data.title },
+		data: options.remoteData || { keep: false, server: true },
+		meta: { mod: options.remoteDataTime || 90 },
+		files: options.remoteFiles || []
+	};
+	const bytes = options.remoteBytes || {};
+	const calls = [];
+	const app = {
+		...bucketSync,
+		...sync,
+		compareVersions: utils.compareVersions,
+		xyopsVersion: options.version || '1.1.2',
+		dry: !!options.dry,
+		errors: [],
+		warnings: [],
+		api: {
+			async getBucket() { return { data: structuredClone(remote) }; },
+			async file(request, settings) {
+				const path = 'files/' + request.path;
+				if (!Object.hasOwn(bytes, path)) return { err: new Error('Missing remote bytes') };
+				fs.writeFileSync(settings.download, bytes[path]);
+				return { data: {} };
+			}
+		},
+		async callStandardAPI(method, request, settings = {}) {
+			calls.push({ method, request, settings });
+			if (method == 'writeBucketData') {
+				remote.data = structuredClone(request.data);
+				remote.meta.mod = 120;
+				return {};
+			}
+			if (method == 'uploadBucketFiles') {
+				settings.files.forEach(path => {
+					const name = app.cleanSyncBucketFilename(Path.basename(path));
+					let file = remote.files.find(entry => entry.filename == name);
+					if (!file) {
+						file = { filename: name, path: 'files/bucket/bucket_unit/new/' + name };
+						remote.files.push(file);
+					}
+					file.size = fs.statSync(path).size;
+					file.date = 130;
+				});
+				return { files: structuredClone(remote.files) };
+			}
+			if (method == 'deleteBucketFile') {
+				remote.files = remote.files.filter(file => file.path != request.path);
+				return {};
+			}
+			throw new Error('Unexpected API: ' + method);
+		},
+		logSyncError(message) { this.errors.push(message); },
+		logSyncWarning(message) { this.warnings.push(message); },
+		markdown(text) { return text; },
+		die(message) { throw new Error(message); }
+	};
+	return { dir, item, paths, remote, calls, app };
+}
+
+test('bucket sync rejects xyOps versions older than 1.1.2', t => {
+	const current = fixture(t);
+	assert.doesNotThrow(() => current.app.requireBucketSyncVersion());
+	current.app.xyopsVersion = '1.1.1';
+	assert.throws(() => current.app.requireBucketSyncVersion(), /v1\.1\.2 or later/);
+});
+
+test('bucket setup writes data and binary files with server mtimes beside the XYPDF source', async t => {
+	const file = { filename: 'Sample.JSON', path: 'files/bucket/bucket_unit/key/Sample.JSON', size: 8, date: 80 };
+	const env = fixture(t, { remoteFiles: [file], remoteBytes: { [file.path]: 'not json' } });
+	fs.rmSync(env.paths.dir, { recursive: true, force: true });
+	await env.app.setupBucketContents([{ id: env.item.data.id, file: env.item.file }], { dry: false, force: false });
+	assert.deepEqual(JSON.parse(fs.readFileSync(env.paths.data, 'utf8')), env.remote.data);
+	assert.equal(fs.readFileSync(Path.join(env.paths.files, 'Sample.JSON'), 'utf8'), 'not json');
+	assert.equal(fs.statSync(env.paths.data).mtimeMs / 1000, 90);
+	assert.equal(fs.statSync(Path.join(env.paths.files, 'Sample.JSON')).mtimeMs / 1000, 80);
+});
+
+test('upsync replaces data, normalizes manifest names, batches uploads, and deletes missing files last', async t => {
+	const removed = { filename: 'old.txt', path: 'files/bucket/bucket_unit/old/old.txt', size: 3, date: 60 };
+	const env = fixture(t, { remoteFiles: [removed] });
+	// Semicolon needs server filename normalization but remains a regular file on Windows.
+	const upload = Path.join(env.paths.files, 'New; File.txt');
+	fs.writeFileSync(upload, 'new');
+	fs.utimesSync(upload, 110, 110);
+	await env.app.syncBucketContents([env.item], { up: ['buckets'], delete: ['buckets'] });
+	assert.deepEqual(env.calls.map(call => call.method), ['writeBucketData', 'uploadBucketFiles', 'deleteBucketFile']);
+	assert.equal(env.calls[0].request.replace, true);
+	assert.deepEqual(env.remote.data, { keep: true, removed: true });
+	assert.equal(env.remote.files[0].filename, 'New_ File.txt');
+	assert.equal(fs.statSync(upload).mtimeMs / 1000, 130);
+	assert.equal(fs.statSync(env.paths.data).mtimeMs / 1000, 120);
+});
+
+test('downsync replaces changed files and preserves the server timestamp', async t => {
+	const file = { filename: 'same.txt', path: 'files/bucket/bucket_unit/key/same.txt', size: 6, date: 140 };
+	const env = fixture(t, { remoteFiles: [file], remoteBytes: { [file.path]: 'remote' }, remoteDataTime: 150 });
+	const localFile = Path.join(env.paths.files, file.filename);
+	fs.writeFileSync(localFile, 'old');
+	fs.utimesSync(localFile, 100, 100);
+	await env.app.syncBucketContents([env.item], { down: ['buckets'] });
+	assert.equal(fs.readFileSync(localFile, 'utf8'), 'remote');
+	assert.equal(fs.statSync(localFile).mtimeMs / 1000, 140);
+	assert.deepEqual(JSON.parse(fs.readFileSync(env.paths.data, 'utf8')), env.remote.data);
+	assert.equal(fs.statSync(env.paths.data).mtimeMs / 1000, 150);
+});
+
+test('two-way sync chooses the newer data and file copies independently', async t => {
+	const old = { filename: 'remote.txt', path: 'files/bucket/bucket_unit/key/remote.txt', size: 6, date: 140 };
+	const env = fixture(t, {
+		localDataTime: 160,
+		remoteDataTime: 150,
+		remoteFiles: [old],
+		remoteBytes: { [old.path]: 'remote'
+		}
+	});
+	const localFile = Path.join(env.paths.files, old.filename);
+	fs.writeFileSync(localFile, 'stale');
+	fs.utimesSync(localFile, 100, 100);
+	await env.app.syncBucketContents([env.item], { up: ['buckets'], down: ['buckets'] });
+	assert.deepEqual(env.calls.map(call => call.method), ['writeBucketData']);
+	assert.equal(fs.readFileSync(localFile, 'utf8'), 'remote');
+	assert.equal(fs.statSync(localFile).mtimeMs / 1000, 140);
+	assert.deepEqual(env.remote.data, env.app.readSyncBucketLocal(env.item).data);
+});
+
+test('two-way sync reports equal-time content conflicts instead of guessing', async t => {
+	const env = fixture(t, { remoteDataTime: 100 });
+	await env.app.syncBucketContents([env.item], { up: ['buckets'], down: ['buckets'] });
+	assert.equal(env.app.errors.length, 1);
+	assert.match(env.app.errors[0], /equal timestamps/);
+	assert.deepEqual(env.calls, []);
+});
+
+test('invalid local data blocks every bucket mutation including file deletion', async t => {
+	const removed = { filename: 'old.txt', path: 'files/bucket/bucket_unit/old/old.txt', size: 3, date: 60 };
+	const env = fixture(t, { remoteFiles: [removed] });
+	fs.writeFileSync(env.paths.data, '{invalid');
+	await env.app.syncBucketContents([env.item], { up: ['buckets'], delete: ['buckets'] });
+	assert.equal(env.app.errors.length, 1);
+	assert.deepEqual(env.calls, []);
+});
+
+test('bucket dry runs leave data, files, and server records unchanged', async t => {
+	const removed = { filename: 'old.txt', path: 'files/bucket/bucket_unit/old/old.txt', size: 3, date: 60 };
+	const env = fixture(t, { remoteFiles: [removed], dry: true });
+	const added = Path.join(env.paths.files, 'new.txt');
+	fs.writeFileSync(added, 'new');
+	const originalTime = fs.statSync(env.paths.data).mtimeMs;
+	await env.app.syncBucketContents([env.item], { up: ['buckets'], delete: ['buckets'] });
+	assert.deepEqual(env.calls, []);
+	assert.equal(env.remote.files.length, 1);
+	assert.deepEqual(env.remote.data, { keep: false, server: true });
+	assert.equal(fs.statSync(env.paths.data).mtimeMs, originalTime);
+});
+
+test('a failed download keeps the previous local file intact', async t => {
+	const file = { filename: 'same.txt', path: 'files/bucket/bucket_unit/key/same.txt', size: 6, date: 140 };
+	const env = fixture(t, { remoteFiles: [file] });
+	const localFile = Path.join(env.paths.files, file.filename);
+	fs.writeFileSync(localFile, 'before');
+	fs.utimesSync(localFile, 100, 100);
+	await env.app.syncBucketContents([env.item], { down: ['buckets'] });
+	assert.equal(env.app.errors.length, 1);
+	assert.equal(fs.readFileSync(localFile, 'utf8'), 'before');
+});