@pixlcore/xycli 1.0.7 → 1.0.8

package/docs/help.md

@@ -200,6 +200,8 @@ xy sync ./ --down events,plugins
 xy sync ./ --up categories,plugins --down events --dry
 xy sync ./ --up events --down events --dry
 xy sync ./ --up all --dry
+xy sync ./ --up buckets --dry
+xy sync ./ --down buckets
 xy sync --up events,plugins --verbose
 ```
 
@@ -212,7 +214,7 @@ Pass one or more base directories, or omit them to scan the current directory. F
 - `--dry` previews changes without applying them.
 - `--verbose` shows full diffs and API requests and responses.
 
-You must enable at least one direction. `TYPES` is a comma-separated list of `alerts`, `api_keys`, `categories`, `channels`, `events`, `groups`, `monitors`, `plugins`, `tags`, or `web_hooks`. Use `all` to select every supported type. Workflows are included under `events`. Buckets, Secrets, Users, and Roles are not supported.
+You must enable at least one direction. `TYPES` is a comma-separated list of `alerts`, `api_keys`, `buckets`, `categories`, `channels`, `events`, `groups`, `monitors`, `plugins`, `tags`, or `web_hooks`. Use `all` to select every supported type. Workflows are included under `events`. Bucket sync requires xyOps v1.1.2 or later. Secrets, Users, and Roles are not supported.
 
 Enable both directions for the same type to use experimental two-way sync. The newest modification time wins, including external property files. Git checkouts can reset filesystem timestamps, so prefer one-way sync when reliable conflict handling matters. Dry runs never update xyOps, write files, run completion commands, or send notifications.
 
@@ -222,6 +224,8 @@ Repeated sources with the same type and ID generate warnings, even if their cont
 
 External string properties are loaded automatically from adjacent files named `BASENAME-PROPERTY.EXT`, such as `My-Plugin-script.js` beside `My-Plugin.json`, or `My-Event-params.script.sh` beside `My-Event.json`. The extension is your choice. Keep only one external file per property, and rename its basename along with the JSON file.
 
+Bucket metadata uses a normal XYPDF source. For a Bucket titled `My Bucket Name`, its separate JSON data and uploaded files live beside `buckets/My-Bucket-Name.json` in `buckets/My-Bucket-Name/data.json` and `buckets/My-Bucket-Name/files/`. Both `data.json` and `files/` are required for a selected local bucket. Bucket data upsync replaces the entire remote data object. Bucket files are matched by xyOps filename normalization and transferred according to size and modification time. Two-way bucket sync uses the data record and file timestamps from xyOps; a transfer updates local file times to match. Bucket files missing locally are deleted remotely only with up-only `--delete buckets`.
+
 **Delete mode**
 
 Add `--delete TYPES` to delete xyOps objects that have no matching source in the scanned directories. Deletion requires up-only sync and a complete local inventory. The CLI rejects deletion if upsync is disabled or any downsync direction is enabled, including saved defaults and dry runs. Use `--down false` to disable inherited downsync. See [Delete mode](sync.md#delete-mode) before using it.
@@ -282,6 +286,7 @@ Export existing xyOps definitions into a starter sync tree in the current direct
 
 ```sh
 xy sync setup events plugins categories --dry
+xy sync setup buckets
 xy sync setup events plugins categories --file_props script,params.script
 xy sync setup events --file_props params.script --default_ext ps1
 xy sync setup events plugins --new
@@ -296,6 +301,8 @@ Choose one or more resource types separated by spaces, or use `all`. Supported t
 
 Setup creates one folder per resource type and one XYPDF JSON file per object, using its title as a filename slug. Selecting `events` exports both Events and workflows, with workflows placed in a separate `workflows` folder. Events and workflows are grouped into subfolders using their Category title as a slug. Both are synced with `--up events` or `--down events`. Setup stops before writing if an Event or workflow selected for export refers to a missing Category.
 
+For each Bucket, setup also writes `BUCKET-SLUG/data.json` and downloads its files into `BUCKET-SLUG/files/` beside the XYPDF file. `--new` skips Bucket definitions already present locally, including their content. `--force` permits overwriting existing Bucket content files.
+
 - `--file_props PATHS` extracts string properties into adjacent files.
 - `--default_ext EXT` sets the fallback neighbor extension instead of `txt`.
 - `--new` writes only remote definitions not already represented locally.

package/docs/sync.md

@@ -54,6 +54,7 @@ Use these names with `--up`, `--down`, `--delete`, and setup:
 | --- | --- |
 | `alerts` | Alert definitions, rather than their invocations. |
 | `api_keys` | API Key definitions. |
+| `buckets` | Bucket definitions, JSON data, and uploaded files. Requires xyOps 1.1.2 or later. |
 | `categories` | Event Categories. |
 | `channels` | Notification Channels. |
 | `events` | Events and workflows. |
@@ -65,7 +66,7 @@ Use these names with `--up`, `--down`, `--delete`, and setup:
 
 `all` selects every supported type. Supply multiple types as a comma-separated string without spaces, such as `events,plugins,categories`.
 
-Buckets, Secret Vaults, Users, and Roles are not supported by sync. Individual workers, jobs, Tickets, Alert history, and snapshots are also outside its definition-sync scope. Workflows use the `events` selection even though setup places them in a separate folder (for convenience).
+Secret Vaults, Users, and Roles are not supported by sync. Individual workers, jobs, Tickets, Alert history, and snapshots are also outside its definition-sync scope. Workflows use the `events` selection even though setup places them in a separate folder (for convenience).
 
 ### Permissions
 
@@ -127,6 +128,8 @@ xyops-automation/
 
 Setup creates one folder per selected resource type and one JSON file per definition. Event and workflow exports are separated into `events/` and `workflows/`, then grouped into subfolders using their Category titles. Both participate in normal sync through the `events` selection.
 
+Bucket setup also creates a sibling directory for each Bucket's content. For example, a Bucket titled `My Bucket Name` has `buckets/My-Bucket-Name.json`, `buckets/My-Bucket-Name/data.json`, and `buckets/My-Bucket-Name/files/` for its definition, data, and uploaded files. Move or rename the sibling directory with the XYPDF file. A normal Bucket sync requires both the data file and files directory, even when they contain an empty object and no files. Bucket data upsync replaces the full remote data object, including removed keys. File transfers match xyOps normalized filenames and align local modification times with the server's timestamps after each transfer.
+
 Folder and filenames come from Category and definition titles: sequences of non-word characters become hyphens, and leading or trailing hyphens are removed. For example, the Event `Nightly Backup` in the `Operations` Category becomes `events/Operations/Nightly-Backup.json`. Different titles can produce the same path, so review the preview for collisions. Setup stops before writing anything if an Event or workflow selected for export refers to a Category that is not present in xyOps.
 
 ### 4. Review and version the tree
@@ -439,7 +442,23 @@ For each differing definition, the engine compares xyOps's `modified` timestamp
 
 Two-way sync is experimental. Keep clocks synchronized, review dry runs, and preserve a history of both configuration and scripts. Git checkout, clone, restore, or file copying can give old content a new filesystem timestamp.
 
-For automatic two-way operation, use a persistent tree and run every minute. Both directions are considered on each run; you do not need separate alternating up and down jobs. Newly created definitions still need a setup export or individual local source, and remotely deleted definitions leave their old source files behind until you remove them.
+Bucket data and files use their own modification times, separate from the Bucket definition. When contents differ, two-way sync compares `data.json` with the data record's modification time and each local file with the matching manifest date. Equal timestamps with differing Bucket content are reported as conflicts. After a transfer, xyCLI sets the local modification time to the server's returned time.
+
+Bucket file comparison uses size and modification time because the manifest has no content hash. A same-size change with an unchanged timestamp cannot be detected.
+
+For automatic two-way operation, use a persistent tree and run every minute. Both directions are considered on each run; you do not need separate alternating up and down jobs. Newly created definitions still need a setup export or individual local source.
+
+### Remove a definition during two-way sync
+
+Two-way sync does not propagate deletions. Definition deletions are usually infrequent, so coordinating them manually is generally practical. Keep `--delete false` in the scheduled command, and remove a definition from both sides deliberately:
+
+1. Delete the definition in the xyOps web interface first.
+2. Remove its local XYPDF JSON file and any neighboring external property files. If the tree is stored in Git, commit and push their removal so the dedicated sync checkout receives the deletion.
+3. Run sync again, or resume the schedule, after the local files are gone. Pause the schedule during these steps if you want to avoid a failed pass between the two removals.
+
+If a sync runs after the xyOps deletion but before local cleanup, the leftover source produces a missing-object warning. The run exits with a failure status before updating or downloading any definitions, and a script that stops on failure will not reach a following `sync setup --new` step. The deleted definition is not recreated. Remove the stale files and retry.
+
+Do not remove the Git files first while the definition still exists in xyOps. A scheduled `sync setup --new` pass can export the still-existing definition back into the repository. See the [Two-Way Git Sync Tutorial](two-way-git-tutorial.md#delete-a-definition-from-both-sides) for the Git workflow.
 
 ## Remote-management warnings
 
@@ -499,6 +518,8 @@ Deleting an Event does not automatically remove its dependencies. Remote API rul
 
 Deletion only begins after every update has completed and the sync-tracking state has been written without warnings or errors. If either phase fails, the entire delete pass is skipped for that run. Earlier successful updates remain in place, so correct the error and retry; definitions already updated will compare equal. Once deletion begins, successful earlier deletions are not rolled back if a later deletion fails.
 
+With `--delete buckets`, a remote Bucket file missing from a selected local Bucket's `files/` directory is deleted individually. Removing the Bucket XYPDF source deletes the whole Bucket, including all its data and files. A missing or invalid `data.json`, incomplete file inventory, or failed transfer prevents Bucket file deletion and the whole-object delete pass.
+
 An unavailable base directory stops the scan, but an existing empty directory can look like an empty inventory. Do not treat that guard as protection against an empty mount, accidental file removal, or missing exports of your own definitions.
 
 Keep deletion disabled in general-purpose cron, Git hooks, and CI until you have a deliberate policy for maintaining and checking the complete inventory. Disable saved deletion for other runs with `--delete false`.

package/docs/two-way-git-tutorial.md

@@ -108,7 +108,7 @@ This considers both directions for every local Event and workflow source:
 - A newer xyOps definition is downloaded to its existing local file.
 - Identical definitions are left alone.
 
-The `--delete false` switch is intentional. Two-way sync does not propagate deletions safely. Delete an item deliberately on both sides, and keep deletion disabled in the scheduled command.
+The `--delete false` switch is intentional. Two-way sync does not propagate deletions. Keep deletion disabled in the scheduled command, and follow the [coordinated deletion steps](#delete-a-definition-from-both-sides) when retiring an item.
 
 Review the displayed diffs carefully. If the wrong side would win, check the clocks and file modification times before continuing.
 
@@ -245,6 +245,18 @@ When someone creates a new Event in xyOps, the ordinary sync pass does not know
 
 `--new` is additive. It does not overwrite existing sources, and it matches existing definitions by type and exact ID rather than filename. This preserves renamed files and custom folder layouts.
 
+### Delete a definition from both sides
+
+Event and workflow deletions are usually infrequent, so it is practical to coordinate the xyOps and Git changes manually. Pause the scheduled script if you want to avoid a failed pass while you make both changes:
+
+1. Delete the definition in the xyOps web interface first.
+2. Remove its XYPDF JSON file and all neighboring property files from Git, then commit and push the deletion. Make sure the dedicated sync checkout receives that commit before its next sync pass.
+3. Resume the scheduled script and check its next run.
+
+If the script runs after the xyOps deletion but before the Git deletion reaches its checkout, ordinary sync reports a missing-object warning and exits with a failure status. It does not recreate the definition or process other changes. The script's `set -e` also prevents the following `sync setup --new` pass. Once the stale files are removed, the next run can proceed normally.
+
+Do not remove the Git files first. While the definition still exists in xyOps, `sync setup --new` can export it again and commit the files back to Git. This is a manual deletion procedure, not automatic two-way deletion. See the [Sync Guide](sync.md#remove-a-definition-during-two-way-sync) for the general behavior.
+
 ## Troubleshooting
 
 | Symptom | What to check |
@@ -255,7 +267,7 @@ When someone creates a new Event in xyOps, the ordinary sync pass does not know
 | The wrong side wins a two-way conflict | Check NTP, the xyOps conductor clock, and the modification times of the JSON and neighboring files. A checkout, restore, or file copy can refresh local timestamps. |
 | A new Event is not exported | Confirm `sync setup events --new` runs from the repository root and that the API Key can see the Event. Add the correct property path if its script is stored somewhere other than `params.script`. |
 | A new Git file is not created in xyOps | Ordinary sync updates definitions that already exist on both sides. Create or import the definition into xyOps first, then let sync manage subsequent changes. |
-| A deleted item reappears or causes an error | Two-way deletion is not supported. Remove the local source and the xyOps definition deliberately as one coordinated operation. |
+| A deleted item reappears or causes an error | Follow the [coordinated deletion steps](#delete-a-definition-from-both-sides): delete in xyOps first, then remove and commit its local files. A leftover source stops sync until it is removed. |
 | A cron run is skipped | Another cron invocation may hold the `flock` lock. The lock file itself may remain when no lock is held, so check for a running sync process rather than treating the file as stale. |
 | A completion command times out | Increase `--cmd_timeout`, investigate Git network latency, and confirm that Git cannot wait for interactive input. |
 

package/index.js

@@ -39,6 +39,14 @@ Uncatch.on('uncaughtException', function(err) {
 	cli.progress.end();
 });
 
+cli.emoji = function(emoji) {
+	// override cli.emoji with our own TTY-aware version (FUTURE: Remove this patch after pixl-cli v1.1.7+)
+	// Draw the emoji, restore its starting cursor position, then explicitly move
+	// forward two cells.  This overrides each terminal's automatic cursor advance.
+	if (!cli.tty()) return emoji;
+	return '\u001b7' + emoji + '\u001b8\u001b[2C';
+};
+
 const { api } = require('@pixlcore/xyops-sdk');
 var highlight = require('cli-highlight').highlight;
 const Tools = cli.Tools;
@@ -357,10 +365,7 @@ const app = {
 		print( "\n " + cyan.bold("Request:") );
 		this.jsonOutput(this.args);
 		
-		if (this.dry) {
-			this.toast('⚠️', 'orange', bold("DRY RUN: ") + "Exiting without sending request.");
-			return;
-		}
+		if (this.dry) return;
 		
 		cli.progress.start({ amount: 1, pct: false, text: gray('→ ' + name) });
 		var { err, data } = await this.api[name](this.args);
@@ -453,6 +458,7 @@ Tools.mergeHashInto( app, require('./lib/webhook.js') );
 Tools.mergeHashInto( app, require('./lib/transfer.js') );
 Tools.mergeHashInto( app, require('./lib/marketplace.js') );
 Tools.mergeHashInto( app, require('./lib/sync.js') );
+Tools.mergeHashInto( app, require('./lib/sync-buckets.js') );
 
 global.app = app;
 

package/lib/buckets.js

@@ -218,7 +218,6 @@ module.exports = {
 		if (this.dry) {
 			if (files.length) {
 				this.jsonOutput({ files: files });
-				this.toast('⚠️', 'orange', bold("DRY RUN: ") + "Exiting without sending request.");
 			}
 			return;
 		}
@@ -475,10 +474,7 @@ module.exports = {
 				output: dest_file
 			});
 		}
-		if (this.dry) {
-			this.toast('⚠️', 'orange', bold("DRY RUN: ") + "Exiting without sending request.");
-			return;
-		}
+		if (this.dry) return;
 		
 		println( "\n " + this.color('theme').bold('BUCKET FILE: ' + file.filename) );
 		println( " " + gray("Downloading to file: ") + dest_file );

package/lib/sync-buckets.js

@@ -0,0 +1,315 @@
+// Filesystem sync for storage bucket data and binary files.
+// Bucket definitions themselves remain in the ordinary XYPDF sync engine.
+
+const fs = require('fs');
+const Path = require('path');
+const Crypto = require('crypto');
+const Diff = require('diff');
+const cli = require('pixl-cli');
+const Tools = cli.Tools;
+
+module.exports = {
+	
+	requireBucketSyncVersion() {
+		// The replace flag and separate data modification time arrived in 1.1.2.
+		// Keep the older minimum version for every other sync resource.
+		if (!this.xyopsVersion || this.compareVersions(this.xyopsVersion, '1.1.2') < 0) {
+			this.die("Bucket sync requires xyOps v1.1.2 or later (server: " + (this.xyopsVersion || 'unknown') + ").");
+		}
+	},
+	
+	getSyncBucketPaths(item) {
+		// The local XYPDF source owns its sibling content directory. The bucket ID
+		// identifies the remote object, so title edits never move existing files.
+		var dir = item.file.replace(/\.json$/i, '');
+		return { dir, data: Path.join(dir, 'data.json'), files: Path.join(dir, 'files') };
+	},
+	
+	cleanSyncBucketFilename(filename) {
+		// Match xyOps cleanFilename(), which is used for manifest identity. The
+		// server's cleanURLFilename() is only for the storage URL component.
+		return filename.replace(/[^\w\-\+\.\,\s\(\)\[\]\{\}\'\"\!\&\^\%\$\#\@\*\?\~]+/g, '_');
+	},
+	
+	validateSyncBucketFilename(filename) {
+		// A server manifest must never be allowed to escape the bucket files dir.
+		if (!filename || (typeof(filename) != 'string') || (filename == '.') || (filename == '..') ||
+			filename.includes('/') || filename.includes('\\') || filename.includes('\0') || (Path.basename(filename) != filename)) {
+			throw new Error("Unsafe bucket filename: " + filename);
+		}
+	},
+	
+	async getSyncBucket(id) {
+		// Read both independently stored content records and their timestamps.
+		var { err, data } = await this.api.getBucket({ id });
+		if (err) throw err;
+		if (!data || !Tools.isaHash(data.data) || !Array.isArray(data.files) ||
+			!data.meta || (typeof(data.meta.mod) != 'number') || !Number.isFinite(data.meta.mod)) {
+			throw new Error("Incomplete bucket data or file manifest: " + id);
+		}
+		
+		var names = new Set();
+		data.files.forEach( file => {
+			this.validateSyncBucketFilename(file.filename);
+			if ((typeof(file.date) != 'number') || !Number.isFinite(file.date) ||
+				(typeof(file.size) != 'number') || !Number.isSafeInteger(file.size) || (file.size < 0) ||
+				(typeof(file.path) != 'string') || !file.path.startsWith('files/bucket/' + id + '/') ||
+				Path.posix.normalize(file.path) != file.path) {
+				throw new Error("Invalid file manifest entry in bucket: " + id);
+			}
+			if (names.has(file.filename)) throw new Error("Duplicate bucket filename in manifest: " + file.filename);
+			names.add(file.filename);
+		});
+		return data;
+	},
+	
+	readSyncBucketLocal(item) {
+		// A missing data file or files directory is an incomplete inventory. This
+		// is an error even when the remote bucket currently happens to be empty.
+		var paths = this.getSyncBucketPaths(item);
+		var stat = fs.lstatSync(paths.data);
+		if (!stat.isFile() || stat.isSymbolicLink()) throw new Error("Invalid bucket data file: " + paths.data);
+		var data = JSON.parse(fs.readFileSync(paths.data, 'utf8'));
+		if (!Tools.isaHash(data)) throw new Error("Bucket data must be a JSON object: " + paths.data);
+		
+		var dir_stat = fs.lstatSync(paths.files);
+		if (!dir_stat.isDirectory() || dir_stat.isSymbolicLink()) throw new Error("Invalid bucket files directory: " + paths.files);
+		
+		var files = new Map();
+		fs.readdirSync(paths.files, { withFileTypes: true }).forEach( entry => {
+			var path = Path.join(paths.files, entry.name);
+			if (!entry.isFile()) throw new Error("Bucket files directory must contain only regular files: " + path);
+			var name = this.cleanSyncBucketFilename(entry.name);
+			this.validateSyncBucketFilename(name);
+			if (files.has(name)) throw new Error("Bucket filenames collide after normalization: " + path);
+			files.set(name, { path, stat: fs.statSync(path) });
+		});
+		return { paths, data, data_stat: stat, files };
+	},
+	
+	stampSyncBucketFile(path, epoch) {
+		// Keep the access time intact. Server times are Unix seconds; Node accepts
+		// the same unit for utimes(), including fractional seconds if provided.
+		var stat = fs.statSync(path);
+		fs.utimesSync(path, stat.atime, Number(epoch));
+	},
+	
+	printSyncBucketHeading(icon, label, title, id, deleting) {
+		// Match the standard sync heading: direction, action, display title and
+		// a quiet internal ID. Give destructive operations the existing red style.
+		var action = deleting ? cli.chalk.red.bold : cli.chalk.green.bold;
+		var name = deleting ? cli.chalk.red.bold : cli.chalk.cyan.bold;
+		println( "\n " + cli.emoji(icon) + " " + action(label) + ": " + name(title) + cli.chalk.gray(" (" + id + ")") );
+	},
+	
+	async downloadSyncBucketFile(id, file, destination) {
+		// Download to a private sibling first. A failed or partial response must
+		// never replace the previous local copy of a bucket file.
+		var temp = destination + '.xy-sync-' + Crypto.randomBytes(8).toString('hex') + '.tmp';
+		try {
+			var { err } = await this.api.file({
+				path: file.path.replace(/^files\//, ''),
+				download: file.filename
+			}, { download: temp });
+			if (err) throw err;
+			var stat = fs.statSync(temp);
+			if (stat.size !== Number(file.size)) throw new Error("Downloaded bucket file size differs from manifest: " + file.filename);
+			this.stampSyncBucketFile(temp, file.date);
+			fs.renameSync(temp, destination);
+		}
+		finally {
+			if (fs.existsSync(temp)) fs.unlinkSync(temp);
+		}
+	},
+	
+	async setupBucketContents(plans, opts) {
+		// Fetch every selected bucket before writing any bucket extras. Honor the
+		// ordinary setup --force, --new and --dry rules for all content files.
+		var prepared = [];
+		var paths_seen = new Set();
+		for (const item of plans) {
+			var paths = this.getSyncBucketPaths(item);
+			if (paths_seen.has(paths.dir)) this.die("Bucket setup paths collide: " + paths.dir);
+			paths_seen.add(paths.dir);
+			for (const dir of [ paths.dir, paths.files ]) {
+				if (fs.existsSync(dir) && (!fs.lstatSync(dir).isDirectory() || fs.lstatSync(dir).isSymbolicLink())) {
+					this.die("Invalid bucket setup directory: " + dir);
+				}
+			}
+			var snapshot = await this.getSyncBucket(item.id);
+			var files = snapshot.files.map( file => ({ file, path: Path.join(paths.files, file.filename) }) );
+			if (!opts.force && !opts.dry) {
+				if (fs.existsSync(paths.data)) this.die("File exists, add '--force' to overwrite all: " + paths.data);
+				files.forEach( entry => {
+					if (fs.existsSync(entry.path)) this.die("File exists, add '--force' to overwrite all: " + entry.path);
+				});
+			}
+			prepared.push({ item, paths, snapshot, files });
+		}
+		
+		for (const entry of prepared) {
+			// Mirror the setup tree above: a colored folder heading, then short
+			// names for the data file and nested uploaded-file directory.
+			println( "\n " + cli.emoji('🪣') + " " + cli.chalk.bold.cyan(Path.basename(entry.paths.dir) + '/') );
+			println( "    " + cli.emoji('📄') + " " + cli.chalk.bold.green('data.json') );
+			println( "    " + cli.emoji('📂') + " " + cli.chalk.bold.cyan('files/') );
+			entry.files.forEach( file => {
+				println( "        " + cli.emoji('📎') + " " + cli.chalk.bold.yellow(file.file.filename) );
+			});
+			if (opts.dry) continue;
+			Tools.mkdirp.sync(entry.paths.files);
+			Tools.writeFileAtomicSync(entry.paths.data, JSON.stringify(entry.snapshot.data, null, '\t') + '\n');
+			this.stampSyncBucketFile(entry.paths.data, entry.snapshot.meta.mod);
+			for (const file of entry.files) {
+				await this.downloadSyncBucketFile(entry.item.id, file.file, file.path);
+			}
+		}
+	},
+	
+	async syncBucketContents(items, sconfig) {
+		if (!items.length || this.errors.length || this.warnings.length) return;
+		var prepared = [];
+		
+		// Preflight every selected local inventory and every remote manifest before
+		// applying changes. A missing data.json or unreadable files dir must never
+		// turn into a remote deletion candidate.
+		try {
+			for (const item of items) {
+				prepared.push({ item, local: this.readSyncBucketLocal(item), remote: await this.getSyncBucket(item.data.id) });
+			}
+		}
+		catch (err) {
+			this.logSyncError("Bucket sync preflight failed: " + err);
+			return;
+		}
+		
+		var up = sconfig.up && sconfig.up.includes('buckets');
+		var down = sconfig.down && sconfig.down.includes('buckets');
+		var delete_files = sconfig.delete && sconfig.delete.includes('buckets');
+		var deletes = [];
+		
+		for (const entry of prepared) {
+			var id = entry.item.data.id;
+			var local = entry.local;
+			var remote = entry.remote;
+			var title = (remote.bucket && remote.bucket.title) || entry.item.data.title || id;
+			var same_data = Tools.stableStringify(local.data) === Tools.stableStringify(remote.data);
+			
+			try {
+				if (!same_data) {
+					var local_time = local.data_stat.mtimeMs / 1000;
+					var remote_time = Number(remote.meta.mod);
+					if (up && down && local_time == remote_time) throw new Error("Bucket data conflict with equal timestamps: " + id);
+					var data_direction = up && down ? (local_time > remote_time ? 'up' : 'down') : (up ? 'up' : 'down');
+					var data_changes = Diff.diffLines(
+						Tools.stablePrettyStringify(remote.data),
+						Tools.stablePrettyStringify(local.data)
+					);
+					this.printSyncBucketHeading(data_direction == 'up' ? '⬆️' : '⬇️', 'Updating bucket data', title, id);
+					println( "\n" + this.markdown(this.formatSyncDiff(data_changes)) );
+					if (!this.dry && data_direction == 'up') {
+						await this.callStandardAPI('writeBucketData', { id, data: local.data, replace: true }, { text: 'Writing bucket data...', throw: true });
+						var updated = await this.getSyncBucket(id);
+						if (Tools.stableStringify(updated.data) !== Tools.stableStringify(local.data)) {
+							throw new Error("Bucket data changed during upload: " + id);
+						}
+						if (Tools.stableStringify(JSON.parse(fs.readFileSync(local.paths.data, 'utf8'))) !== Tools.stableStringify(local.data)) {
+							throw new Error("Local bucket data changed during upload: " + local.paths.data);
+						}
+						this.stampSyncBucketFile(local.paths.data, updated.meta.mod);
+						this.upSynced = true;
+					}
+					else if (!this.dry) {
+						Tools.writeFileAtomicSync(local.paths.data, JSON.stringify(remote.data, null, '\t') + '\n');
+						this.stampSyncBucketFile(local.paths.data, remote.meta.mod);
+						this.downSynced = true;
+					}
+				}
+				
+				var manifest = new Map(remote.files.map( file => [file.filename, file] ));
+				var uploads = [];
+				var downloads = [];
+				for (const [name, source] of local.files) {
+					var target = manifest.get(name);
+					if (!target) {
+						if (up) uploads.push({ name, source });
+						continue;
+					}
+					var local_time = source.stat.mtimeMs / 1000;
+					var remote_time = Number(target.date);
+					var size_differs = source.stat.size !== Number(target.size);
+					if (up && down) {
+						if (local_time > remote_time) uploads.push({ name, source });
+						else if (remote_time > local_time) downloads.push({ name, target, path: source.path });
+						else if (size_differs) throw new Error("Bucket file size conflict with equal timestamps: " + source.path);
+					}
+					else if (up && (size_differs || local_time > remote_time)) uploads.push({ name, source });
+					else if (down && (size_differs || remote_time > local_time)) downloads.push({ name, target, path: source.path });
+				}
+				for (const file of remote.files) {
+					if (!local.files.has(file.filename)) {
+						if (down) downloads.push({ name: file.filename, target: file, path: Path.join(local.paths.files, file.filename) });
+						else if (delete_files) deletes.push({ id, title, file });
+					}
+				}
+				
+				if (uploads.length) {
+					var upload_label = "Uploading " + uploads.length + " bucket " + (uploads.length == 1 ? 'file' : 'files');
+					this.printSyncBucketHeading('⬆️', upload_label, title, id);
+					uploads.forEach( entry => {
+						println( "    " + cli.emoji('📎') + " " + cli.chalk.bold.yellow(Path.basename(entry.source.path)) );
+					});
+					if (!this.dry) {
+						var result = await this.callStandardAPI('uploadBucketFiles', { id }, {
+							text: 'Uploading bucket files...', files: uploads.map( entry => entry.source.path ), throw: true
+						});
+						var updated = new Map((result.files || []).map( file => [file.filename, file] ));
+						for (const entry of uploads) {
+							var file = updated.get(entry.name);
+							if (!file || (typeof(file.date) != 'number') || !Number.isFinite(file.date)) {
+								throw new Error("Uploaded bucket file missing or invalid in response: " + entry.name);
+							}
+							var current = fs.statSync(entry.source.path);
+							if ((current.size !== entry.source.stat.size) || (current.mtimeMs !== entry.source.stat.mtimeMs)) {
+								throw new Error("Local bucket file changed during upload: " + entry.source.path);
+							}
+							this.stampSyncBucketFile(entry.source.path, file.date);
+						}
+						this.upSynced = true;
+					}
+				}
+				for (const entry of downloads) {
+					this.printSyncBucketHeading('⬇️', 'Downloading bucket file', title, id);
+					println( "    " + cli.emoji('📎') + " " + cli.chalk.bold.yellow(entry.name) );
+					if (!this.dry) {
+						await this.downloadSyncBucketFile(id, entry.target, entry.path);
+						this.downSynced = true;
+					}
+				}
+			}
+			catch (err) {
+				this.logSyncError("Bucket sync failed for " + id + ": " + err);
+			}
+		}
+		
+		// Deletions are the final content phase. Any earlier warning or error
+		// suppresses all bucket file deletes, just like whole-object deletion.
+		if (deletes.length && (this.errors.length || this.warnings.length)) {
+			this.logSyncWarning("Bucket file delete pass skipped because sync encountered warnings or errors.");
+			return;
+		}
+		for (const entry of deletes) {
+			this.printSyncBucketHeading('🗑️', 'Deleting bucket file', entry.title, entry.id, true);
+			println( "    " + cli.emoji('📎') + " " + cli.chalk.bold.yellow(entry.file.filename) );
+			if (this.dry) continue;
+			try {
+				await this.callStandardAPI('deleteBucketFile', { id: entry.id, path: entry.file.path }, { text: 'Deleting bucket file...', throw: true });
+				this.upSynced = true;
+			}
+			catch (err) {
+				this.logSyncError("Bucket file deletion failed: " + err);
+				return;
+			}
+		}
+	}
+};

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;
 			}
@@ -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;
@@ -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);
@@ -1029,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);

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.7",
+	"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');
+});

package/test/sync-buckets.test.js

@@ -0,0 +1,133 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const Path = require('node:path');
+const { api } = require('@pixlcore/xyops-sdk');
+const { loadTestConfig, createCheck, createTempDir, xy, call } = require('./helpers/common.js');
+
+test('bucket filesystem sync', async t => {
+	loadTestConfig();
+	const check = createCheck(t);
+	const temp = createTempDir(t, 'xycli-bucket-sync-live-');
+	const setupRoot = Path.join(temp, 'setup');
+	const activeRoot = Path.join(temp, 'active');
+	const stamp = Date.now();
+	const id = 'cli_bucket_sync_test_' + stamp;
+	const title = 'CLI Bucket Sync Test ' + stamp;
+	const slug = title.replace(/\W+/g, '-').replace(/^-|-$/g, '');
+	const seed = Path.join(temp, 'seed.json');
+	let originalState = null;
+	let created = false;
+	
+	fs.mkdirSync(setupRoot, { recursive: true });
+	fs.mkdirSync(activeRoot, { recursive: true });
+	fs.writeFileSync(seed, 'seed');
+	
+	try {
+		await check('create an isolated Bucket fixture', async () => {
+			const before = await call('getMultiple', { lists: 'buckets', state: 1 });
+			originalState = structuredClone((before.state && before.state.sync) || {});
+			
+			// --new will skip existing Buckets without downloading their content.
+			for (const bucket of before.buckets) {
+				fs.writeFileSync(Path.join(setupRoot, 'skip-' + bucket.id + '.json'), JSON.stringify({
+					type: 'xypdf', version: '1.0', items: [{ type: 'bucket', data: bucket }]
+				}));
+			}
+			await call('createBucket', { id, title, enabled: false, data: { keep: true, remove: true } });
+			created = true;
+			const uploaded = await api.uploadBucketFiles({ id }, { files: [seed] });
+			assert.ok(!uploaded.err && uploaded.data && uploaded.data.code === 0, 'Seed upload succeeded');
+		});
+		
+		await check('setup exports Bucket data and files', async () => {
+			const output = xy(['sync', 'setup', 'buckets', '--new'], { cwd: setupRoot });
+			assert.match(output, /🪣.*\/\s*\n/);
+			assert.match(output, /📄.*data\.json/);
+			assert.match(output, /📂.*files\//);
+			assert.match(output, /📎.*seed\.json/);
+			assert.doesNotMatch(output, /Bucket content:/);
+			const source = Path.join(setupRoot, 'buckets', slug);
+			assert.deepEqual(JSON.parse(fs.readFileSync(Path.join(source, 'data.json'), 'utf8')), { keep: true, remove: true });
+			assert.equal(fs.readFileSync(Path.join(source, 'files', 'seed.json'), 'utf8'), 'seed');
+			fs.mkdirSync(Path.join(activeRoot, 'buckets'), { recursive: true });
+			fs.cpSync(source + '.json', Path.join(activeRoot, 'buckets', slug + '.json'));
+			fs.cpSync(source, Path.join(activeRoot, 'buckets', slug), { recursive: true });
+		});
+		
+		await check('upsync replaces data and uploads a new file', async () => {
+			const content = Path.join(activeRoot, 'buckets', slug);
+			// Semicolon exercises filename normalization on Unix and Windows alike.
+			const added = Path.join(content, 'files', 'New; File.txt');
+			const source = Path.join(activeRoot, 'buckets', slug + '.json');
+			const xypdf = JSON.parse(fs.readFileSync(source, 'utf8'));
+			xypdf.items[0].data.notes = 'Local Bucket notes';
+			fs.writeFileSync(source, JSON.stringify(xypdf));
+			fs.writeFileSync(Path.join(content, 'data.json'), JSON.stringify({ keep: 'local' }));
+			fs.writeFileSync(added, 'new content');
+			const output = xy(['sync', activeRoot, '--up', 'buckets', '--down', 'false', '--delete', 'false']);
+			assert.match(output, new RegExp('Updating bucket: ' + title + ' \\(' + id + '\\)'));
+			assert.match(output, new RegExp('\\n\\n ⬆️ Updating bucket data: ' + title + ' \\(' + id + '\\)'));
+			assert.match(output, /-.*"keep": true/);
+			assert.match(output, /\+.*"keep": "local"/);
+			assert.match(output, new RegExp('\\n\\n ⬆️ Uploading \\d+ bucket files?: ' + title + ' \\(' + id + '\\)'));
+			assert.match(output, /📎.*New; File\.txt/);
+			assert.ok(output.indexOf('Updating bucket data:') > output.indexOf('Updating bucket:'), 'Bucket data has its own section after the definition');
+			const bucket = await call('getBucket', { id });
+			assert.equal(bucket.bucket.notes, 'Local Bucket notes');
+			assert.deepEqual(bucket.data, { keep: 'local' });
+			const file = bucket.files.find(entry => entry.filename === 'New_ File.txt');
+			assert.ok(file, 'Normalized upload is in the manifest');
+			assert.equal(Math.floor(fs.statSync(added).mtimeMs / 1000), file.date);
+		});
+		
+		await check('downsync pulls remote data and file changes', async () => {
+			await call('updateBucket', { id, notes: 'Remote Bucket notes' });
+			await call('writeBucketData', { id, replace: true, data: { keep: 'remote' } });
+			fs.writeFileSync(seed, 'remote replacement');
+			const uploaded = await api.uploadBucketFiles({ id }, { files: [seed] });
+			assert.ok(!uploaded.err && uploaded.data && uploaded.data.code === 0, 'Replacement upload succeeded');
+			xy(['sync', activeRoot, '--up', 'false', '--down', 'buckets', '--delete', 'false']);
+			const content = Path.join(activeRoot, 'buckets', slug);
+			const xypdf = JSON.parse(fs.readFileSync(content + '.json', 'utf8'));
+			assert.equal(xypdf.items[0].data.notes, 'Remote Bucket notes');
+			assert.deepEqual(JSON.parse(fs.readFileSync(Path.join(content, 'data.json'), 'utf8')), { keep: 'remote' });
+			assert.equal(fs.readFileSync(Path.join(content, 'files', 'seed.json'), 'utf8'), 'remote replacement');
+		});
+		
+		await check('two-way sync pushes newer local content and aligns timestamps', async () => {
+			const content = Path.join(activeRoot, 'buckets', slug);
+			const dataFile = Path.join(content, 'data.json');
+			const file = Path.join(content, 'files', 'seed.json');
+			const newer = Math.ceil(Date.now() / 1000) + 5;
+			fs.writeFileSync(dataFile, JSON.stringify({ keep: 'two-way' }));
+			fs.writeFileSync(file, 'two-way file');
+			fs.utimesSync(dataFile, newer, newer);
+			fs.utimesSync(file, newer, newer);
+			const output = xy(['sync', activeRoot, '--up', 'buckets', '--down', 'buckets', '--delete', 'false']);
+			assert.match(output, new RegExp('\\n\\n ⬆️ Updating bucket data: ' + title + ' \\(' + id + '\\)'));
+			assert.match(output, /-.*"keep": "remote"/);
+			assert.match(output, /\+.*"keep": "two-way"/);
+			const bucket = await call('getBucket', { id });
+			assert.deepEqual(bucket.data, { keep: 'two-way' });
+			const remoteFile = bucket.files.find(entry => entry.filename === 'seed.json');
+			assert.equal(remoteFile.size, Buffer.byteLength('two-way file'));
+			assert.equal(Math.floor(fs.statSync(file).mtimeMs / 1000), remoteFile.date);
+			assert.equal(Math.floor(fs.statSync(dataFile).mtimeMs / 1000), bucket.meta.mod);
+		});
+	}
+	finally {
+		// Ordinary sync writes a shared management map. Restore it exactly, then
+		// delete only this uniquely named Bucket and its content.
+		const cleanupErrors = [];
+		if (originalState !== null) {
+			try { await call('update_global_state', { sync: originalState }); }
+			catch (error) { cleanupErrors.push(error); }
+		}
+		if (created) {
+			try { await call('deleteBucket', { id }); }
+			catch (error) { cleanupErrors.push(error); }
+		}
+		if (cleanupErrors.length) throw new AggregateError(cleanupErrors, 'Bucket sync fixture cleanup failed');
+	}
+});

package/test/sync-unit.test.js

@@ -18,6 +18,7 @@ const script = `
 	if (options.setupCwd) process.chdir(options.setupCwd);
 	const calls = [];
 	const requests = [];
+	const apiOptions = [];
 	const app = {
 		...sync,
 		args: options.args,
@@ -41,9 +42,10 @@ const script = `
 		compareVersions() { return 0; },
 		async getMultiple() {},
 		die(message) { throw new Error(message); },
-		async callStandardAPI(method, data) {
+		async callStandardAPI(method, data, opts) {
 			calls.push(method);
 			requests.push({ method, data });
+			apiOptions.push({ method, opts });
 			if (options.failAPI === method) throw new Error('Fixture API failure');
 		}
 	};
@@ -51,7 +53,7 @@ const script = `
 		console.error(err.message);
 		process.exitCode = 1;
 	}).finally(() => {
-		console.log(JSON.stringify({ calls, requests, errors: app.errors || [], warnings: app.warnings || [] }));
+		console.log(JSON.stringify({ calls, requests, apiOptions, errors: app.errors || [], warnings: app.warnings || [] }));
 	});
 `;
 
@@ -225,6 +227,20 @@ test('sync errors exit nonzero even in quiet mode or a dry run', t => {
 	}
 });
 
+test('sync sends existing Plugin properties through the sync API path', t => {
+	const remote = { id: 'legacy', title: 'Legacy', type: 'event', command: 'node', cwd: '/opt/legacy', custom_field: { keep: true }, notes: 'Remote' };
+	const local = { ...remote, notes: 'Local' };
+	const result = runSync(t, {
+		plugins: [remote],
+		existingSources: [{ path: 'Legacy.json', type: 'plugin', data: local }],
+		args: { up: 'plugins' }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.deepEqual(result.report.requests.find(request => request.method === 'update_plugin').data, local);
+	assert.equal(result.report.apiOptions.find(call => call.method === 'update_plugin').opts.sync, true);
+});
+
 test('sync API errors preserve failure status while still sending both notifications', t => {
 	const category = { id: 'fixture', title: 'Fixture', notes: 'Remote' };
 	for (const failAPI of ['update_category', 'update_global_state', 'delete_category']) {

package/test/utils-unit.test.js

@@ -1,7 +1,10 @@
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
+const cli = require('pixl-cli');
 const utils = require('../lib/utils.js');
 
+cli.global();
+
 test('executable language detection accepts Unix and Windows command forms', () => {
 	// Plugin definitions are portable, so exercise both path styles regardless of
 	// the operating system running this test.
@@ -17,3 +20,50 @@ test('executable language detection accepts Unix and Windows command forms', ()
 	assert.equal(utils.getLangFromBinary('unknown-binary.exe'), null);
 	assert.equal(utils.getLangFromBinary(null), null);
 });
+
+test('sync API updates preserve stored properties while manual updates retain typo checks', async () => {
+	const calls = [];
+	const context = {
+		...utils,
+		dry: false,
+		verbose: false,
+		api: {
+			async update_plugin(request, opts) {
+				calls.push({ method: 'update_plugin', request, opts });
+				return { err: null, data: { code: 0 } };
+			},
+			async update_event(request, opts) {
+				calls.push({ method: 'update_event', request, opts });
+				return { err: null, data: { code: 0 } };
+			}
+		},
+		die(message) { throw new Error(message); }
+	};
+	
+	for (const [method, request] of [
+		['update_plugin', { id: 'legacy_plugin', cwd: '/tmp/legacy' }],
+		['update_event', { id: 'legacy_event', custom_field: { enabled: true } }]
+	]) {
+		// A hand-typed update still rejects an unknown top-level property.
+		const prior_calls = calls.length;
+		await assert.rejects(context.callStandardAPI(method, request), /Unsupported property/);
+		assert.equal(calls.length, prior_calls);
+		
+		// Sync forwards the complete stored object to xyOps for its own validation.
+		await context.callStandardAPI(method, request, { sync: true });
+		assert.equal(calls.length, prior_calls + 1);
+		assert.deepEqual(calls.at(-1), { method, request, opts: {} });
+	}
+	
+	// The original report failed during dry sync, before any xyOps request.
+	// Preview the same Plugin payload and verify that it makes no SDK call.
+	const plugin_request = { id: 'legacy_plugin', cwd: '/tmp/legacy' };
+	const previews = [];
+	const prior_calls = calls.length;
+	context.dry = true;
+	context.color = () => cli.chalk.white;
+	context.jsonOutput = request => { previews.push(request); };
+	await context.callStandardAPI('update_plugin', plugin_request, { sync: true });
+	assert.deepEqual(previews, [plugin_request]);
+	assert.equal(calls.length, prior_calls);
+});