@pixlcore/xycli 1.0.6 → 1.0.8

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # xyCLI Changelog
 
+## Version v1.0.6
+
+> September 22, 2026
+
+- [`985c132`](https://github.com/pixlcore/xycli/commit/985c132607e1dcdabbadc829d6f21e599a2eb52b): Version 1.0.6
+- [`f0aac32`](https://github.com/pixlcore/xycli/commit/f0aac320cbd301a5dc45862edaec9f842c2c6c79): Feature: Add "xy upgrade" command.
+- [`a9b653b`](https://github.com/pixlcore/xycli/commit/a9b653b9649afd15d93cb3d29ee4f23da47bde0a): Bug Fix: Sync files with similar stems and neighbors can get mixed up.  Fixes #4.
+
 ## Version v1.0.5
 
 > September 21, 2026

package/README.md

@@ -499,7 +499,7 @@ cd xyops-automation
 xy sync setup events plugins categories --file_props script,params.script
 ```
 
-Setup creates one file per definition and can extract scripts into adjacent source files. Events and workflows are automatically grouped into subfolders named after their Categories. You can reorganize the tree afterward; sync scans subdirectories and matches definitions by resource type and exact ID.
+Setup creates one file per definition and can extract scripts into adjacent source files. The same `--file_props script,params.script` selection also extracts matching scripts from workflow nodes automatically. Events and workflows are grouped into subfolders named after their Categories. You can reorganize the tree afterward; sync scans subdirectories and matches definitions by resource type and exact ID.
 
 Preview a push or pull, then apply the direction you want:
 

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.
@@ -308,6 +315,8 @@ Setup creates one folder per resource type and one XYPDF JSON file per object, u
 
 For `--file_props`, use comma-separated property names or dot paths, such as `script,params.script`. Only nonempty string values are extracted. The JSON value becomes `(External)`, and sync loads the external file automatically. Setup chooses extensions from executable commands, shebangs, and JSON content when possible. Use `--default_ext ps1` (or `--default_ext .ps1`) to replace the `.txt` fallback for properties whose type cannot be detected. The override does not replace an extension that setup successfully detects.
 
+The same property selection also checks every workflow node automatically. For example, `params.script` in a node's `data` becomes a neighbor such as `My-Workflow-workflow.nt3sr3y4.params.script.sh`. The node ID in the filename identifies which node owns the property. No additional setup option is needed.
+
 Use `--new` from the root of an existing sync tree to add definitions that exist in xyOps but have no local source. Setup scans recursively and matches existing sources by item type and exact ID, so renamed files and custom folder layouts are preserved. New definitions use the normal suggested type and Category folders. Malformed, duplicate, unsupported, or orphaned local sources stop the operation before any new files are written. `--new` cannot be combined with `--force`, and it does not create new definitions in xyOps.
 
 An explicitly supplied `--down_cmd` runs from the current setup directory after at least one definition is written. It does not run when `--new` finds nothing or during a dry run. Saved sync completion commands are not inherited by setup.

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
 
@@ -96,7 +97,7 @@ Setup always writes below the current working directory. Type names after `setup
 xy sync setup events plugins categories --file_props script,params.script --dry
 ```
 
-The `--file_props` switch will externalize specific JSON property paths into individually named files, for easy editing.  This is great for storing Plugin scripts and Event shell scripts in separate files alongside the main JSON definition files.
+The `--file_props` switch will externalize specific JSON property paths into individually named files, for easy editing.  This is great for storing Plugin scripts, Event shell scripts, and workflow node scripts in separate files alongside the main JSON definition files.
 
 The preview lists the folders and files that would be written. `--dry` creates no directories or files.
 
@@ -122,10 +123,13 @@ xyops-automation/
     workflows/
         Deployments/
             Release-Pipeline.json
+            Release-Pipeline-workflow.nt3sr3y4.params.script.sh
 ```
 
 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
@@ -242,9 +246,12 @@ This extracts the selected content, if found, and moves it to a neighboring file
 | --- | --- | --- |
 | `My-Plugin.json` | `script` | `My-Plugin-script.js` |
 | `My-Event.json` | `params.script` | `My-Event-params.script.sh` |
+| `Release-Pipeline.json` | `workflow.nt3sr3y4.params.script` | `Release-Pipeline-workflow.nt3sr3y4.params.script.sh` |
 
 The general naming pattern is **`BASENAME-PROPERTY.EXT`**, in the same directory as `BASENAME.json`. Dot paths such as `params.script` identify nested properties. Setup chooses an extension from the executable command or a script's shebang when possible, falling back to JSON-looking content or `.txt`. Normal sync accepts your chosen extension.
 
+The same `--file_props script,params.script` selection checks every node in a workflow automatically. If a node has a nonempty string at `data.params.script`, setup writes a neighbor for that node and leaves `(External)` in the workflow JSON. In its filename, `workflow.NODE_ID.params.script` identifies the node by its ID and then reads `data.params.script`. No additional option is needed for workflow nodes.
+
 Use `--default_ext EXT` to replace the `.txt` fallback when setup cannot detect a type. For example, `--default_ext ps1` and `--default_ext .ps1` both produce `.ps1` neighbors. Detected interpreter and JSON extensions still take precedence. The fallback applies to every undetected property selected by that setup command, so group properties with the same expected file type or run setup separately when needed.
 
 External properties are detected automatically when sync runs; you do not need to repeat `--file_props`. The neighbor's text replaces that property in the local definition before comparison and before an upload. A pull writes the latest value into the existing neighbor file.
@@ -435,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
 
@@ -495,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

@@ -67,7 +67,7 @@ xy sync setup events --file_props script,params.script --default_ext ps1 --dry
 
 The `events` selection includes both Events and workflows. Setup places workflows in their own `workflows/` directory, then groups Events and workflows into subfolders named after their Categories.
 
-`--file_props script,params.script` extracts common Plugin and Event script properties into neighboring files. If your Plugin uses another property, add its dot path to the list. For example, use `script,params.script,params.command` when an Event stores its PowerShell source in `params.command`.
+`--file_props script,params.script` extracts common script properties into neighboring files. It also checks each workflow node automatically, so a node's `data.params.script` gets its own file named with that node's ID. If a property uses another path, add its dot path to the list. For example, use `script,params.script,params.command` when an Event stores its PowerShell source in `params.command`.
 
 The optional `--default_ext ps1` uses `.ps1` when setup cannot detect a neighbor file's language from an executable command, shebang, or JSON content. Remove it or choose another extension if PowerShell is not the appropriate fallback for your repository.
 
@@ -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/jobs.js

@@ -414,8 +414,8 @@ module.exports = {
 			
 			this.printNiceHTML( job.html.content );
 			
-			if (job.table.caption) {
-				println( " " + gray(job.table.caption) );
+			if (job.html.caption) {
+				println( " " + gray(job.html.caption) );
 			}
 		} // job.html
 		

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