@pixlcore/xycli 1.0.8 → 1.1.0

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

@@ -0,0 +1,259 @@
+# Two-Way Git Sync with Event-Driven Deletes
+
+This tutorial keeps Events, workflows, and Plugins in both xyOps and Git. Existing definitions can be edited on either side, and deletions can start on either side. New definitions are created in the xyOps UI and exported to Git. Every sync runs because Git accepted a push or xyOps recorded an activity. There are no cron jobs or recurring sync schedules.
+
+Use xyCLI version **v1.1.0+** (with down-sync delete support) and xyOps version **v1.1.3+** (with System Activity triggers). Both features must be available before you enable this workflow.
+
+> [!IMPORTANT]
+> **Two-way deletion requires authoritative triggers in both directions.** Run `--up --delete` only in response to an accepted Git change, and run `--down --delete` only in response to xyOps activity. Each invocation has exactly one authoritative side. A single command with both `--up` and `--down` cannot use `--delete`.
+
+| Authoritative action | Trigger | Command | Result |
+| --- | --- | --- | --- |
+| Git accepts a contributor push | Git `post-receive` hook or GitHub `push` webhook | `xy sync ... --up events,plugins --down false --delete events,plugins` | Git updates existing definitions and removes missing ones from xyOps. |
+| xyOps updates or deletes an Event or Plugin | **System Activity** Event | `xy sync ... --up false --down events,plugins --delete events,plugins` | xyOps updates existing files and removes missing XYPDF files and their owned neighbors. |
+| xyOps creates an Event or Plugin | Separate **System Activity** Event | `xy sync setup events plugins --new ...` | New definitions are exported, committed, and pushed to Git. |
+
+> [!CAUTION]
+> There is a potential race condition between creating an item in xyOps and exporting it to Git. If a Git-triggered up-delete runs before the new XYPDF file reaches the checkout, it can delete that newly created item from xyOps. The shared job queue prevents runs from overlapping, but it cannot guarantee which trigger arrives first. See [Ordering and recovery](#ordering-and-recovery).
+
+The examples in this tutorial include **Events** (which includes Workflows) and **Plugins**. To manage other resource types, add them to the commands and choose their corresponding activity types. 
+
+## Before you begin
+
+Use one persistent Git checkout on a machine running xySat. Target all three xyOps Events below to that machine, where the checkout, xyCLI configuration, and Git credentials are available. The xyOps conductor does not need a copy of the repository. Use one operating-system account for all three jobs.
+
+You will need:
+
+- A xyOps API Key that can see the **complete** Event and Plugin inventories, update and delete those types, and update global sync state. A restricted or partial inventory is unsafe for up-only deletion.
+- A dedicated repository and a persistent checkout, such as `/srv/xyops-automation`, with noninteractive Git pull and push access.
+- A Git author identity for commits generated by xyOps.
+- Shared xyOps job capacity and queue limits on all three Events.
+- A way to monitor failed xyOps jobs and Git webhook deliveries, then retry them after checking both sides.
+
+This is a full-inventory workflow. Do not point it at a partial export, empty mount, fresh clone missing files, or API Key with an incomplete view. Stock and Marketplace definitions are naturally excluded.
+
+## 1. Prepare the checkout
+
+Clone the repository on the sync worker, then configure the account that will run the jobs:
+
+```sh
+git clone git@github.com:YOUR_ORG/xyops-automation.git /srv/xyops-automation
+cd /srv/xyops-automation
+git config user.name "xyOps Sync"
+git config user.email "xyops-sync@example.com"
+xy config --base_url https://xyops.example.com --api_key YOUR_API_KEY
+xy dashboard
+```
+
+Keep the API Key and Git credentials outside the repository. Use `main` as the dedicated branch in the examples below, or replace it consistently with your branch name.
+
+Export a complete starter inventory from the repository root. `--file_props` keeps common Plugin and Event scripts in neighboring files:
+
+```sh
+xy sync setup events plugins --file_props script,params.script --dry
+xy sync setup events plugins --file_props script,params.script
+git status --short
+```
+
+Review the generated files, including scripts and potentially sensitive configuration. Confirm that every non-stock Event, workflow, and Plugin visible to the sync API Key is present. Then commit and push the initial tree:
+
+```sh
+git add --all
+git commit -m "Export xyOps automation"
+git push -u origin main
+```
+
+Create the automation Events described below only after this inventory exists. Export them before enabling the Git trigger, so an early up-only delete pass cannot mistake an automation Event for a Git deletion.
+
+## 2. Add a commit helper
+
+Save this script as `/usr/local/sbin/commit-xyops-sync` on the sync worker. Both xyOps-originated jobs will use it as their explicit `--down_cmd`, to run after local changes have been made:
+
+```sh
+#!/bin/sh
+set -eu
+
+cd /srv/xyops-automation
+
+# This checkout is dedicated to xyOps automation. Stage removals as well as
+# new and updated files, then avoid an empty commit if nothing changed in Git.
+git add --all
+if git diff --cached --quiet; then
+	exit 0
+fi
+
+# The Git trigger should ignore commits carrying this prefix. They came from
+# xyOps and must not cause a second authoritative up-delete run.
+git commit -m "[xyops-sync] Export xyOps changes"
+git push origin HEAD:main
+```
+
+Make it executable with `chmod 755 /usr/local/sbin/commit-xyops-sync`. This helper assumes the repository contains only the automation tree. If it contains unrelated work, narrow the staged paths and review the resulting commit before using it unattended.
+
+## 3. Add one sync script for the three jobs
+
+Save this as `/usr/local/sbin/xyops-git-sync` on the sync worker:
+
+```sh
+#!/bin/sh
+set -eu
+
+# Include the directories containing Node.js, xyCLI, and Git on this worker.
+PATH="/usr/local/bin:/usr/bin:/bin"
+export PATH
+
+REPO_DIR="/srv/xyops-automation"
+XY_BIN="/usr/local/bin/xy"
+COMMIT_CMD="/usr/local/sbin/commit-xyops-sync"
+SYNC_TYPES="events,plugins"
+MODE="${1:-}"
+
+cd "$REPO_DIR"
+
+# Work only from the dedicated branch and a clean, existing checkout. A
+# missing tree or leftover change must never be treated as a deletion.
+if [ "$(git symbolic-ref --quiet --short HEAD)" != main ]; then
+	echo "Sync stopped: checkout is not on main." >&2
+	exit 1
+fi
+if [ -n "$(git status --porcelain)" ]; then
+	echo "Sync stopped: checkout has uncommitted changes." >&2
+	exit 1
+fi
+if [ ! -d events ] || [ ! -d plugins ]; then
+	echo "Sync stopped: Event or Plugin inventory directory is missing." >&2
+	exit 1
+fi
+
+# Pull accepted Git changes before scanning. A failed fast-forward requires
+# review rather than a reset that could discard a xyOps-generated commit.
+git pull --quiet --ff-only origin main
+
+case "$MODE" in
+	up)
+		"$XY_BIN" sync "$REPO_DIR" \
+			--up "$SYNC_TYPES" --down false --delete "$SYNC_TYPES" \
+			--up_cmd false --down_cmd false
+		;;
+	
+	down)
+		"$XY_BIN" sync "$REPO_DIR" \
+			--up false --down "$SYNC_TYPES" --delete "$SYNC_TYPES" \
+			--down_cmd "$COMMIT_CMD" --cmd_timeout 120
+		;;
+	
+	create)
+		# Setup scans the current directory and adds only remote definitions
+		# whose type and ID are not already represented in the checkout.
+		"$XY_BIN" sync --setup "$SYNC_TYPES" --new \
+			--file_props script,params.script \
+			--down_cmd "$COMMIT_CMD" --cmd_timeout 120
+		;;
+	
+	*)
+		echo "Usage: $0 up|down|create" >&2
+		exit 2
+		;;
+esac
+```
+
+Make it executable with `chmod 755 /usr/local/sbin/xyops-git-sync`. Change the paths and `PATH` for your worker. The directory checks are a basic guard against a missing checkout. They do not prove that the inventory is complete, so inspect it before enabling deletion and after any Git or API failure.
+
+Set a suitable job timeout for Git network operations. All three Events will share a xyOps capacity pool so only one can use this checkout at a time.
+
+## 4. Configure the xyOps Activity Events
+
+Create three Shell Plugin Events in xyOps, initially disabled. Target only the sync worker and give each Event the indicated trigger and script. The [System Activity trigger](https://docs.xyops.io/triggers#activity) lets you select multiple activity types in the UI; it launches a job when any of them occur. Note that the xyOps scheduler must be enabled for Activity triggers to run.
+
+| Event | Trigger | Select these activities | Shell script body |
+| --- | --- | --- | --- |
+| **Sync deletions and updates from xyOps** | System Activity | `event_update`, `plugin_update`, `event_delete`, `plugin_delete` | `/usr/local/sbin/xyops-git-sync down` |
+| **Export creations from xyOps** | System Activity | `event_create`, `plugin_create` | `/usr/local/sbin/xyops-git-sync create` |
+| **Apply accepted Git pushes** | Manual | No activity selection | `/usr/local/sbin/xyops-git-sync up` |
+
+The update activities make xyOps UI edits flow back to Git too. The separate creation Event runs `sync setup --new`, because ordinary downsync updates existing local sources but does not create files for new xyOps definitions. The setup command's `--down_cmd` runs only when it writes files; the down-delete command's `--down_cmd` runs only after local changes. Neither creates an empty Git commit on a no-op run.
+
+The Git Event has an enabled **Manual** trigger so a Git hook or verified webhook receiver can launch it with `xy run` or the [`run_event` API](https://docs.xyops.io/api#run_event). It has no schedule. The Git push is still the authoritative reason for that run.
+
+On **each** of these three Events, set a **[Max Jobs Limit](https://docs.xyops.io/#Docs/limits/max-jobs-limit)** of `1` with the same **[Shared Capacity Key](https://docs.xyops.io/#Docs/limits/shared-capacity-key)**, such as `xyops_git_sync`. Also set a **[Max Queue Limit](https://docs.xyops.io/#Docs/limits/max-queue-limit)** with the same positive amount on each Event, sized for the bursts you expect. This creates one shared, FIFO job queue for all sync operations. Without queue capacity, a trigger arriving while another sync job runs may be aborted instead of waiting. See xyOps's [shared capacity and queue limits](https://docs.xyops.io/limits#shared-capacity-key). Use the same priority on all three Events unless you deliberately want to change queue order, and monitor jobs that fail or exhaust the queue.
+
+Before enabling any of the three Events, export their new definitions from the checkout root:
+
+```sh
+cd /srv/xyops-automation
+/usr/local/sbin/xyops-git-sync create
+```
+
+The `create` mode uses `sync setup --new` and its `--down_cmd` to commit and push those files. Review that commit and confirm the tree is complete. Then enable the three Events and test with disposable definitions before allowing normal Git pushes to trigger up-delete.
+
+## 5. Trigger upsync from accepted Git pushes
+
+Choose the Git trigger that matches your repository hosting. Both options launch the **same** Git Event after a push has been accepted. Do not enable both for one repository.
+
+### Self-hosted Git: a `post-receive` hook
+
+On a self-hosted **bare remote repository**, save the following as `hooks/post-receive` and make it executable. This hook runs on the Git server after refs have been updated, not in each contributor's clone or the sync worker's checkout. The Git server needs xyCLI credentials that permit launching the Git Event, but it does not need the sync checkout.
+
+```sh
+#!/bin/sh
+set -eu
+
+deploy=false
+while read -r old_oid new_oid ref; do
+	[ "$ref" = refs/heads/main ] || continue
+	git cat-file -e "$new_oid^{commit}" 2>/dev/null || continue
+	
+	# A commit generated by the down/create helper is already from xyOps.
+	# Do not turn its push into another authoritative up-delete run.
+	case "$(git log -1 --format=%s "$new_oid")" in
+		'[xyops-sync]'*) continue ;;
+	esac
+	deploy=true
+done
+
+[ "$deploy" = true ] || exit 0
+/usr/local/bin/xy run SYNC_UP_EVENT_ID
+```
+
+Replace `SYNC_UP_EVENT_ID` with the xyOps Git Event's exact ID. Git's [`post-receive` hook](https://git-scm.com/docs/githooks#post-receive) runs after a push succeeds; a later hook or job failure cannot undo that push. Monitor the launched job and retry it after fixing any problem.
+
+### GitHub: a `push` webhook
+
+If GitHub hosts the repository, use its **push** webhook to notify your existing webhook receiver. In GitHub, open **Settings > Webhooks > Add webhook**, set its payload URL to that receiver, choose `application/json`, set a secret, and select only the **Pushes** event. The receiver should:
+
+1. Verify `X-Hub-Signature-256` against the raw request body, and accept only the intended repository and `refs/heads/main`.
+2. Ignore GitHub's initial `ping`, deleted branches, and commits whose head message starts with `[xyops-sync]`.
+3. Deduplicate by `X-GitHub-Delivery`, then launch `SYNC_UP_EVENT_ID` through xyOps's `run_event` API using an API Key with `run_jobs` access.
+4. Acknowledge only after recording the delivery for processing, and monitor the resulting xyOps job. Retry a failed job or redeliver a missed webhook after reviewing the Git and xyOps state.
+
+The API request made by the verified receiver is a JSON `POST` to `/api/app/run_event/v1` with an `X-API-Key` header and body `{"id":"SYNC_UP_EVENT_ID"}`. The Event runs on the sync worker, so the receiver does not need the checkout. Do not put an xyOps API Key in the GitHub payload URL. A direct xyOps Magic Link can start an Event, but it does not verify GitHub's webhook signature; use a receiver that does that verification for this workflow. See GitHub's [webhook setup](https://docs.github.com/en/webhooks/using-webhooks/creating-webhooks), [signature validation](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries), and [delivery guidance](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks).
+
+## 6. Test each direction before enabling automatic deletion
+
+Run these tests with disposable Events and Plugins, not production definitions:
+
+1. Create an Event or Plugin in xyOps. Confirm that the **create** Activity Event exports its XYPDF, commits it, and pushes it to Git.
+2. Edit that definition in the xyOps UI. Confirm that the **down** Activity Event downloads the change and commits it.
+3. Delete it in xyOps. Confirm that the **down** Event removes the XYPDF and owned neighbor files and pushes the deletion.
+4. Edit an existing definition in Git and push. Confirm that the accepted-push trigger runs **up** and updates xyOps.
+5. Delete a different existing definition in Git and push. Confirm that **up** deletes only that definition in xyOps.
+
+Before the first live delete, preview each direction against the complete checkout and inspect every proposed deletion:
+
+```sh
+cd /srv/xyops-automation
+xy sync . --up events,plugins --down false --delete events,plugins --dry
+xy sync . --up false --down events,plugins --delete events,plugins --dry
+```
+
+Remember that a dry run previews the inventory **at that moment**. It cannot establish what a later Git push or xyOps activity means. Keep recoverable Git history and xyOps backups.
+
+## Ordering and recovery
+
+Authoritative triggers tell each pass which side should win. They do not make a full-inventory sweep transactional or remove all races. For example, an Event newly created in xyOps but not yet exported looks missing to an up-delete run; a new Git XYPDF that has not been created in xyOps looks missing to a down-delete run. This tutorial permits **creation only in xyOps**, so contributors should edit or delete existing XYPDF sources, not add new IDs in Git.
+
+Keep all three jobs on the same worker and checkout, serialize the entire Git plus xyCLI sequence with their shared capacity key, and process pending xyOps creations before allowing a Git up-delete pass to treat the inventory as complete. The queue prevents overlap, but it cannot guarantee that independently delivered Git and xyOps triggers arrive in causal order. If changes on both sides occur together, pause automatic deletion, inspect the Git diff and both inventories, resolve the intended order, and rerun the appropriate job. Do not assume a successful webhook acknowledgment means the xyOps job succeeded.
+
+If a job or push fails, leave the checkout and xyOps as they are until you have inspected them. A failed Git push can leave a local commit that needs to be pushed or reconciled before another `git pull --ff-only`. A failed Activity launch or webhook delivery needs a deliberate retry; there is no cron pass to pick it up later. GitHub [does not automatically redeliver failed webhook deliveries](https://docs.github.com/en/webhooks/using-webhooks/handling-failed-webhook-deliveries).
+
+For all sync options and deletion safeguards, see the [Filesystem Sync Guide](sync.md#delete-mode). For a scheduled, modification-time-based workflow without automatic two-way deletion, see the [Two-Way Git Sync Tutorial](two-way-git-tutorial.md).

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

@@ -108,7 +108,9 @@ 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. Keep deletion disabled in the scheduled command, and follow the [coordinated deletion steps](#delete-a-definition-from-both-sides) when retiring an item.
+The `--delete false` switch is intentional. A single command with both directions does not propagate deletions. Keep deletion disabled in this scheduled command, and follow the [coordinated deletion steps](#delete-a-definition-from-both-sides) when retiring an item. Separate one-way [up and down delete modes](sync.md#delete-mode) are available for workflows that can coordinate their triggers and inventories.
+
+If you want deletion in both directions without a recurring schedule, use the separate [event-driven two-way delete tutorial](two-way-delete-tutorial.md).
 
 Review the displayed diffs carefully. If the wrong side would win, check the clocks and file modification times before continuing.
 
@@ -151,6 +153,7 @@ GIT_DOWN_CMD="git add --all && git commit -m 'Sync from xyOps' && git push"
 	--up events \
 	--down events \
 	--delete false \
+	--ignore_missing \
 	--down_cmd "$GIT_DOWN_CMD" \
 	--cmd_timeout 120
 
@@ -159,6 +162,7 @@ GIT_DOWN_CMD="git add --all && git commit -m 'Sync from xyOps' && git push"
 # The setup completion command runs only when new files were actually written.
 "$XY_BIN" sync setup events \
 	--new \
+	--ignore_missing \
 	--file_props script,params.script \
 	--default_ext ps1 \
 	--down_cmd "$GIT_DOWN_CMD" \
@@ -185,6 +189,8 @@ The two uses of `--down_cmd` are deliberately identical:
 - `sync setup --new` runs it only after at least one new local definition is written.
 - A no-op or dry run does not create a commit or push.
 
+The two `--ignore_missing` switches let the script continue while a definition deleted in xyOps still has a local XYPDF source. Other definitions can sync and new xyOps definitions can be exported during that interval. The stale source and its neighboring files remain in Git until you remove and push them. Other scan problems still stop the run.
+
 The command stages the entire dedicated repository with `git add --all`. Do not use this script in a checkout containing unrelated work. If your repository contains other material, narrow the Git paths in `GIT_DOWN_CMD`.
 
 ## 5. Schedule the script with cron
@@ -207,7 +213,7 @@ Run the script every minute, with `flock` outside the script:
 * * * * * /usr/bin/flock --nonblock --conflict-exit-code 0 /tmp/xyops-git-sync.lock /usr/local/sbin/xyops-git-sync >/dev/null
 ```
 
-Cron normally emails job output when local mail delivery is configured. This entry discards routine standard output so successful runs remain silent, but leaves standard error alone so failures can still trigger mail. The xyCLI commands deliberately omit `--quiet`, because that option can suppress collected sync warnings and error reports along with routine output.
+Cron normally emails job output when local mail delivery is configured. This entry discards routine standard output so successful runs remain silent, but leaves standard error alone so failures can still trigger mail. The xyCLI commands show progress when run manually; you can add `--quiet` to suppress that progress while keeping warnings and errors on standard error.
 
 To keep successful output in a log instead, replace `>/dev/null` with an append redirect to a file that the sync account can write. Do not place that log inside the Git repository because the completion command stages the whole tree.
 
@@ -247,13 +253,13 @@ When someone creates a new Event in xyOps, the ordinary sync pass does not know
 
 ### 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:
+You can automate deletions made in xyOps with [System Hook deletion](sync.md#system-hook-deletion). For manual coordination, the `--ignore_missing` switches let the scheduled script keep running while you complete these steps:
 
 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.
+2. Remove its XYPDF JSON file and all neighboring property files from Git, then commit and push the deletion.
+3. Check that the dedicated sync checkout receives the commit and completes a later sync 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.
+If the script runs after the xyOps deletion but before the Git deletion reaches its checkout, both sync commands skip that local source without treating it as a warning. They leave its files in place and continue processing other definitions. Remove and push the stale files to complete the deletion. Without `--ignore_missing` on both commands, the missing source stops the script.
 
 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.
 
@@ -267,7 +273,7 @@ Do not remove the Git files first. While the definition still exists in xyOps, `
 | 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 | 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 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. Use `--ignore_missing` on both sync commands to keep the script running during the gap. |
 | 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

@@ -18,6 +18,15 @@ if (!process.env.XYOPS_USER_AGENT) {
 	process.env.XYOPS_USER_AGENT = `xyOps CLI v${pkg.version} (Node.js); ${os.hostname()} (${os.platform()}/${os.arch()})`;
 }
 
+// Warnings and errors must reach stderr even in quiet mode. Install this
+// before cli.global() so its global warn() helper is bound to cli as usual.
+cli.warn = function(msg) {
+	if (this.progress.running) this.progress.erase();
+	process.stderr.write(msg);
+	if (this.progress.running) this.progress.draw();
+	this.log(msg);
+};
+
 cli.global();
 
 cli.mapArgs({
@@ -26,7 +35,8 @@ cli.mapArgs({
 	'd': 'debug',
 	'f': 'format',
 	'r': 'raw',
-	'h': 'help'
+	'h': 'help',
+	'ignore-missing': 'ignore_missing'
 });
 
 process.on('SIGINT', function() { cli.progress.end(); process.exit(130); } );
@@ -240,6 +250,14 @@ const app = {
 		delete args.quiet;
 		delete args.verbose;
 		
+		// A System Hook deletion uses only its STDIN payload and local XYPDF
+		// files.  Run it before the normal xyOps API credential and config fetch.
+		if ((cmd == 'sync') && ('syshook' in args)) {
+			await this.cmd_sync();
+			print("\n");
+			return;
+		}
+		
 		// create temp dir if needed
 		this.tempDir = this.config.temp_dir || Path.join( os.tmpdir(), 'xyops', 'cli' );
 		if (!fs.existsSync(this.tempDir)) Tools.mkdirpSync( this.tempDir );
@@ -413,6 +431,8 @@ const app = {
 	
 	dieUsage(heading) {
 		// print help and exit
+		if (cli.args.quiet) this.die("Invalid usage. Run 'xy help " + heading + "' for details.");
+		
 		this.printHelp(heading);
 		println("");
 		process.exit(1);
@@ -459,6 +479,7 @@ 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') );
+Tools.mergeHashInto( app, require('./lib/sync-syshook.js') );
 
 global.app = app;
 

package/lib/apikey.js

@@ -241,7 +241,7 @@ module.exports = {
 		println( "\n " + cyan.bold("API Key Secret: ") + bold(data.plain_key) );
 		println( " " + yellow.bold("Save this secret now.  It will never be displayed again.") );
 		if (state_error) {
-			println( "\n " + red.bold("Disable Error: ") + (state_error.message || state_error) );
+			warnln( "\n " + red.bold("Disable Error: ") + (state_error.message || state_error) );
 			process.exitCode = 1;
 			return;
 		}

package/lib/marketplace.js

@@ -235,7 +235,7 @@ module.exports = {
 				]
 			});
 			
-			if (warning) println("\n " + yellow(warning));
+			if (warning) warnln("\n " + yellow(warning));
 			println("\n This is the Plugin definition that will be " + (operation == 'create' ? 'created' : 'used to update the installed Plugin') + " when you confirm:");
 			this.jsonOutput(display.plugin);
 			if (display.script) this.printPluginScript(plugin);

package/lib/sync-buckets.js

@@ -87,6 +87,25 @@ module.exports = {
 		return { paths, data, data_stat: stat, files };
 	},
 	
+	getSyncBucketLocalDeletePlan(item) {
+		// A deleted Bucket owns its sibling data.json and uploaded files.  Only
+		// remove that directory when it has the exact structure produced by
+		// setup; an unexpected entry could belong to someone else.
+		var local = this.readSyncBucketLocal(item);
+		var dir_stat = fs.lstatSync(local.paths.dir);
+		if (!dir_stat.isDirectory() || dir_stat.isSymbolicLink()) {
+			throw new Error("Invalid bucket content directory: " + local.paths.dir);
+		}
+		var entries = fs.readdirSync(local.paths.dir).sort();
+		if (entries.length !== 2 || entries[0] !== 'data.json' || entries[1] !== 'files') {
+			throw new Error("Unexpected file in bucket content directory: " + local.paths.dir);
+		}
+		return {
+			files: [...local.files.values()].map( entry => entry.path ).concat(local.paths.data),
+			dirs: [local.paths.files, local.paths.dir]
+		};
+	},
+	
 	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.
@@ -187,6 +206,7 @@ module.exports = {
 		var down = sconfig.down && sconfig.down.includes('buckets');
 		var delete_files = sconfig.delete && sconfig.delete.includes('buckets');
 		var deletes = [];
+		var local_deletes = [];
 		
 		for (const entry of prepared) {
 			var id = entry.item.data.id;
@@ -233,6 +253,7 @@ module.exports = {
 					var target = manifest.get(name);
 					if (!target) {
 						if (up) uploads.push({ name, source });
+						else if (delete_files) local_deletes.push({ id, title, name, path: source.path });
 						continue;
 					}
 					var local_time = source.stat.mtimeMs / 1000;
@@ -294,7 +315,7 @@ module.exports = {
 		
 		// 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)) {
+		if ((deletes.length || local_deletes.length) && (this.errors.length || this.warnings.length)) {
 			this.logSyncWarning("Bucket file delete pass skipped because sync encountered warnings or errors.");
 			return;
 		}
@@ -311,5 +332,18 @@ module.exports = {
 				return;
 			}
 		}
+		for (const entry of local_deletes) {
+			this.printSyncBucketHeading('🗑️', this.dry ? 'Would delete local bucket file' : 'Deleting local bucket file', entry.title, entry.id, true);
+			println( "    " + cli.emoji('📎') + " " + cli.chalk.bold.yellow(entry.name) );
+			if (this.dry) continue;
+			try {
+				fs.unlinkSync(entry.path);
+				this.downSynced = true;
+			}
+			catch (err) {
+				this.logSyncError("Local bucket file deletion failed: " + err);
+				return;
+			}
+		}
 	}
 };