@pixlcore/xycli 1.0.8 → 1.0.9

package/README.md

@@ -134,7 +134,7 @@ These switches control output or execution across many commands. Add them to the
 | Switch | Short form | What it does |
 | --- | --- | --- |
 | `--verbose` | `-v` | Show extra detail. Resource views may expand scripts, parameters, or monitoring sections; many mutation commands also display API requests and responses. |
-| `--quiet` | `-q` | Suppress ordinary terminal output and progress displays. JSON data still prints, and fatal error messages remain visible on stderr. |
+| `--quiet` | `-q` | Suppress ordinary terminal output and progress displays. JSON data still prints, and human-readable warnings and errors remain visible on stderr. |
 | `--dry` | | Preview a supported operation without applying it. Resource mutations, imports, exports, sync, and API calls use this to show planned changes or requests. It does not prevent connection checks or reads, and does not apply to local `xy config` updates. |
 | `--format json` | `-f json` | Display supported results as indented JSON instead of the usual report or table. |
 | `--format jsonc` | `-f jsonc` | Display supported results as compact JSON on one line. Here, `jsonc` means compact JSON. |
@@ -157,7 +157,7 @@ XYOPS_COLOR=false xy events --format json --quiet > ./events.json
 xy categories -f jsonc -q > ./categories.json
 ```
 
-Fatal errors print to stderr and exit with a nonzero status even in quiet mode, so redirecting JSON output to a file leaves those errors visible in your terminal. Quiet mode can still suppress command-specific warnings and failure reports, such as sync messages or import results. Sync warnings and errors still produce a nonzero exit status. Check exit status and any structured results when scripting; omit `--quiet` when you need those detailed diagnostics.
+Human-readable warnings and errors print to stderr even in quiet mode, so redirecting JSON output to a file leaves those diagnostics visible in your terminal. Structured JSON results may also include warnings and errors. Sync warnings and errors still produce a nonzero exit status. Check exit status and any structured results when scripting.
 
 JSON output varies by command: some local collection views return all matches even when their table view is paginated, while database searches may return only the selected page. Some commands print multiple JSON values, such as the request and response from `xy api`. Check the command reference when using the output in a script.
 

package/docs/help.md

@@ -213,6 +213,7 @@ Pass one or more base directories, or omit them to scan the current directory. F
 - `--down TYPES` updates local files from xyOps.
 - `--dry` previews changes without applying them.
 - `--verbose` shows full diffs and API requests and responses.
+- `--ignore_missing` skips local sources whose type and ID are absent from xyOps, without a warning or failure. It leaves their files untouched.
 
 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.
 
@@ -239,6 +240,16 @@ xy sync ./ --up events,plugins --delete events
 
 **The scanned directories must contain a complete inventory of the other objects you intend to keep for every type selected for deletion.** Delete mode is not limited to previously synced objects. A missing file, incomplete export, or unavailable mount can cause unintended deletions of your own definitions. Verify that all source directories are available and inspect a dry run before removing `--dry`. Source warnings or scan errors stop the run before any updates begin. If an update or sync-tracking API operation fails, earlier successful updates remain in place, but the entire delete pass is skipped for that run.
 
+**System Hook deletions**
+
+Use `--syshook ACTION` when a matching xyOps System Hook launches the CLI. This supports deletion hooks for every standard sync definition type except Buckets. It reads the activity JSON from STDIN and removes only the XYPDF with the matching type and ID, plus its neighboring property files. It does not run ordinary sync, compare definitions, or call the xyOps API. Pass exactly one sync directory, and use an absolute path because System Hooks start in a temporary directory. See the [supported actions](sync.md#system-hook-deletion) for the exact hook names, including `apikey_delete` for API Keys.
+
+```sh
+xy sync /srv/xyops-automation --syshook event_delete --down_cmd /usr/local/sbin/commit-xyops-deletion
+```
+
+`--down_cmd` runs from the sync directory only after files are actually removed. A missing local source is a successful no-op; duplicate matching sources stop the command without deleting either one. `--dry` previews the files without deleting them or running `down_cmd`. No xyOps URL or API Key is needed. See [System Hook deletion](sync.md#system-hook-deletion) for configuration and operational details.
+
 **Completion commands and notifications**
 
 ```sh
@@ -254,7 +265,7 @@ xy sync ./ --up events,plugins \
 - `--error_email ADDRESS` sends warnings and errors by email through xyOps.
 - `--error_event EVENT_ID` runs an Event on warnings or errors.
 
-Completion commands run in a local shell in the first base directory. Deletions alone do not trigger them. Event notifications receive `input.data.errors` and `input.data.warnings`.
+Completion commands run in a local shell in the first base directory. Successful up-only deletion triggers `up_cmd`; local System Hook deletion triggers an explicitly supplied `down_cmd`. Event notifications receive `input.data.errors` and `input.data.warnings`.
 
 The configured API Key needs the appropriate resource permissions and `update_state` for sync tracking updates. Notification actions also need their usual permissions. Earlier successful changes are not rolled back if a later operation fails. Retry the sync after correcting an error; previously applied updates compare equal, and deletion remains disabled until the pre-delete phase completes without warnings or errors.
 
@@ -306,6 +317,7 @@ For each Bucket, setup also writes `BUCKET-SLUG/data.json` and downloads its fil
 - `--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.
+- `--ignore_missing` lets `--new` skip local sources whose type and ID are absent from xyOps.
 - `--down_cmd COMMAND` runs after setup writes one or more definitions.
 - `--cmd_timeout SECONDS` changes the command timeout from 30 seconds.
 - `--stock` includes stock objects, which are omitted by default.
@@ -317,7 +329,7 @@ For `--file_props`, use comma-separated property names or dot paths, such as `sc
 
 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.
+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. With `--ignore_missing`, only sources whose type and ID are absent from xyOps are skipped. `--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

@@ -172,7 +172,7 @@ xy sync setup events plugins categories --new --file_props script,params.script
 xy sync setup events plugins categories --new --file_props script,params.script
 ```
 
-New-only setup scans the current directory recursively and indexes existing XYPDF sources by item type and exact ID. Renamed files and custom folders are preserved. Remote definitions not found in that index are written to setup's normal type and Category folders; existing definitions are skipped without being rewritten. Malformed, duplicate, unsupported, or locally orphaned sources stop the operation before new files are written. `--new` cannot be combined with `--force`.
+New-only setup scans the current directory recursively and indexes existing XYPDF sources by item type and exact ID. Renamed files and custom folders are preserved. Remote definitions not found in that index are written to setup's normal type and Category folders; existing definitions are skipped without being rewritten. Malformed, duplicate, unsupported, or locally orphaned sources stop the operation before new files are written. Add `--ignore_missing` to skip only local sources whose type and ID are absent from xyOps. `--new` cannot be combined with `--force`.
 
 This is an additive local export. It does not create definitions in xyOps, and ordinary upsync or downsync still updates only definitions that already exist on both sides.
 
@@ -394,15 +394,17 @@ Relative paths resolve against the CLI's current working directory. Completion c
 | `--up TYPES` | `sync.up` | Disabled | Sync upwards to xyOps from local sources for these types. |
 | `--down TYPES` | `sync.down` | Disabled | Down downwards to existing local sources from xyOps for these types. |
 | `--delete TYPES` | `sync.delete` | Disabled | Delete remote objects with no local source. Use only in an up-only workflow; see [Delete mode](#delete-mode). |
+| `--syshook ACTION` | n/a | Disabled | Handle one supported definition deletion activity from STDIN as a local-only deletion; see [System Hook deletion](#system-hook-deletion). |
+| `--ignore_missing` | `sync.ignore_missing` | Off | Skip local sources whose type and ID are absent from xyOps, without a warning or failure. Leave their files untouched. |
 | `--up_cmd COMMAND` | `sync.up_cmd` | None | Run a local shell command after at least one successful upsync. |
-| `--down_cmd COMMAND` | `sync.down_cmd` | None | Run a local shell command after at least one successful downsync. |
+| `--down_cmd COMMAND` | `sync.down_cmd` | None | Run a local shell command after at least one successful downsync, or an explicit command after a System Hook deletion. |
 | `--cmd_timeout SECONDS` | `sync.cmd_timeout` | `30` | Timeout for each completion command. |
 | `--error_email ADDRESS` | `sync.error_email` | None | Email collected warnings and errors through xyOps. |
 | `--error_event EVENT_ID` | `sync.error_event` | None | Launch an Event with collected warnings and errors in its input data. |
 | `--lock_file PATH` | `sync.lock_file` | Temporary file keyed by `base_url` | Use an explicit path for the built-in PID lock. |
 | `--dry` | n/a | Off | Dry-Run Mode: Preview without writes, completion commands, or notifications. |
 | `--verbose`, `-v` | n/a | Off | Show complete diffs and additional request, response, and write details. |
-| `--quiet`, `-q` | n/a | Off | Suppress routine output and progress. Fatal errors remain visible, but collected sync warnings and errors can be suppressed. |
+| `--quiet`, `-q` | n/a | Off | Suppress routine output and progress. Warnings and errors remain visible on standard error. |
 
 At least one direction must be enabled. The command is a single run, not a background watcher; repeat it through a scheduler or hook for automatic operation.
 
@@ -417,6 +419,7 @@ At least one direction must be enabled. The command is a single run, not a backg
 | `--file_props PATHS` | Extract string properties into adjacent neighbor files. Accepts comma-separated dot paths or a JSON array. |
 | `--default_ext EXT` | Use this extension instead of `txt` when a neighbor's type cannot be detected. A leading dot is optional. |
 | `--new` | Export only remote definitions whose type and ID are not already present in the current local tree. |
+| `--ignore_missing` | With `--new`, skip local sources whose type and ID are absent from xyOps. Leave their files untouched. |
 | `--down_cmd COMMAND` | Run a local shell command after setup writes one or more definitions. |
 | `--cmd_timeout SECONDS` | Set the setup completion-command timeout in seconds. The default is `30`. |
 | `--stock` | Include stock definitions that ships wit xyOps (e.g. "Shell Plugin"), which setup normally omits. |
@@ -454,12 +457,50 @@ Two-way sync does not propagate deletions. Definition deletions are usually infr
 
 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.
+3. Run sync again, or resume the schedule, after the local files are gone. Without `--ignore_missing`, 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.
+If a sync runs after the xyOps deletion but before local cleanup, the leftover source normally produces a missing-object warning and stops the run before any definition changes. Add `--ignore_missing` to ordinary sync and any following `sync setup --new` command to skip that source and keep processing other definitions. This does not remove the local files or propagate the deletion to Git. Remove those files yourself to complete the deletion. Other scan warnings and errors still stop the run.
 
 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.
 
+### System Hook deletion
+
+xyOps [System Hooks](https://docs.xyops.io/#Docs/syshooks) can launch xyCLI when a standard synced definition is deleted. Configure each deletion action you need separately. The `--syshook` command reads the activity JSON from STDIN, checks that its action matches the command, and uses the deleted object's type and exact ID to find one local XYPDF source. It removes that source and its neighboring external property files. Other local definitions, including new ones not yet in xyOps, are left alone.
+
+| Sync selection | System Hook action |
+| --- | --- |
+| `alerts` | `alert_delete` |
+| `api_keys` | `apikey_delete` |
+| `categories` | `category_delete` |
+| `channels` | `channel_delete` |
+| `events` (including workflows) | `event_delete` |
+| `groups` | `group_delete` |
+| `monitors` | `monitor_delete` |
+| `plugins` | `plugin_delete` |
+| `tags` | `tag_delete` |
+| `web_hooks` | `web_hook_delete` |
+
+Buckets are excluded because a Bucket may have separate JSON data and uploaded files alongside its XYPDF source. The `bucket_delete` activity is not supported by `--syshook`.
+
+For example, configure the following hooks on the primary conductor, adjusting executable and checkout paths:
+
+```json
+{
+	"hooks": {
+		"event_delete": {
+			"shell_exec": "/usr/local/bin/xy sync /srv/xyops-automation --syshook event_delete --down_cmd /usr/local/sbin/commit-xyops-deletion"
+		},
+		"plugin_delete": {
+			"shell_exec": "/usr/local/bin/xy sync /srv/xyops-automation --syshook plugin_delete --down_cmd /usr/local/sbin/commit-xyops-deletion"
+		}
+	}
+}
+```
+
+The `--down_cmd` script can stage, commit, and push the deletions in a dedicated Git checkout. It runs only after at least one file was removed. A missing source is a successful no-op, and duplicate matching sources stop the command before any files are removed. Use `--dry` to preview the selected files without changing them or running the completion command.
+
+This mode does not run ordinary sync, fetch remote definitions, or change xyOps. It ignores saved sync direction settings and requires exactly one directory. No xyOps URL or API Key is needed. The CLI still uses a host-local lock, with a fixed default lock key when no `base_url` is configured. System shell hooks run on the primary conductor from a temporary directory, and xyOps limits them to 60 seconds. The conductor must be able to access the checkout and Git credentials. If regular sync runs on another host, its local lock cannot protect this checkout; arrange for both operations to use the same host and lock if they share a checkout. Watch hook failures and Git push failures, because a failed hook is not automatically retried.
+
 ## Remote-management warnings
 
 Up-only sync records the managed definitions in xyOps's global sync state. The web interface and xyCLI update commands use this information to warn that a definition is under remote management and should not be edited directly.
@@ -544,7 +585,7 @@ xy sync ./ --down events,plugins --down_cmd "./commit-downloads.sh" --cmd_timeou
 ### When commands run
 
 - `up_cmd` runs if at least one object was successfully upsynced (this includes deletes).
-- `down_cmd` runs if at least one object was successfully downsynced.
+- `down_cmd` runs if at least one object was successfully downsynced. In `--syshook` mode, an explicitly supplied `down_cmd` runs after the matching local files are deleted.
 - During setup, an explicitly supplied `down_cmd` runs if at least one definition was written.
 - If both apply, `up_cmd` runs first, then `down_cmd`.
 - Neither runs for an identical/no-op run, a scan that stopped before changes, or a dry run.
@@ -635,7 +676,7 @@ Runs with no warnings or errors exit with status `0`. Scan warnings prevent chan
 
 Every `xy sync` command acquires a host-local PID lock before it loads remote definitions or touches local files. This includes ordinary up, down, two-way, delete, dry-run, and setup operations. The lock remains held through completion commands and error notifications, so every CLI entry point uses the same overlap protection automatically.
 
-By default, xyCLI creates a lock file in the operating system's temporary directory. Its filename contains a hash of the normalized `base_url`, so syncs targeting the same xyOps instance on one host serialize even when they use different directories or API Keys. Syncs for different instances use different default locks.
+By default, xyCLI creates a lock file in the operating system's temporary directory. Its filename contains a hash of the normalized `base_url`, so syncs targeting the same xyOps instance on one host serialize even when they use different directories or API Keys. Syncs for different instances use different default locks. System Hook deletions without a configured `base_url` use a fixed local key instead.
 
 When another live sync process owns the lock, the new command stops before doing any work, prints the owning PID and lock path, and exits nonzero. It does not wait or queue. Schedulers can try again on their next run. If a process was forcibly terminated and left its PID file behind, the next invocation detects that the PID is dead, removes the stale file, atomically acquires a replacement, and continues.
 
@@ -691,7 +732,7 @@ PATH=/usr/local/bin:/usr/bin:/bin
 
 Choose only the item types your tree manages. This example explicitly disables downsync and deletion. Add `--error_event EVENT_ID` if you prefer an error-handling Event, or configure notifications in the account's CLI config file.
 
-`--quiet` keeps routine progress and diffs out of cron's output, avoiding an email for every ordinary run. Fatal CLI errors still print to standard error. Collected sync warnings and errors can be suppressed, so quiet automation should have configured notifications and external monitoring. Remove `--quiet` while investigating a problem.
+`--quiet` keeps routine progress and diffs out of cron's output, avoiding an email for every ordinary run. Warnings and errors still print to standard error. Configure notifications if you also want xyOps to send a message or launch an Event when sync encounters a problem.
 
 If the previous run is still active, the built-in PID lock rejects the overlapping invocation with a nonzero exit status. The next minute tries again. A single sync can therefore take longer than a minute without starting another copy.
 
@@ -946,7 +987,7 @@ Repository concurrency controls these workflow runs. Coordinate all writers to t
 | `down_cmd` does not run | Normal sync requires a successful download. Setup requires at least one written definition and an explicit `--down_cmd`. No-op and dry runs do not trigger it. |
 | A download commit launches another sync | Disable deployment Git hooks for commits made by `down_cmd`. The nested sync will otherwise be rejected by the built-in PID lock. |
 | Sync reports another PID is running | Another local sync owns the lock. Let it finish. If the PID is no longer alive, the next run recovers the stale file automatically. If the PID belongs to an unrelated recycled process, verify that no sync is active before removing the reported lock file. |
-| A scheduled run prints nothing | `--quiet` suppresses routine output and collected reports. Remove it to investigate and configure notifications. |
+| A scheduled run prints nothing | `--quiet` suppresses routine output. Warnings and errors still print to standard error. Check that the scheduler captures it. |
 | Sync exits nonzero after a warning report | Scan warnings prevent changes from being applied, so warnings and errors both exit with status `1`. Resolve the reported problem before retrying. |
 | Notifications never arrive | Check API access, email setup and privileges, the error Event's manual trigger, and failures occurring before reporting. |
 | API Key updates behave differently after import | Portable definitions do not transfer usable secret key material. Treat key credentials separately from their definitions. |

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

@@ -151,6 +151,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 +160,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 +187,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 +211,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 +251,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 +271,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-syshook.js

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

package/lib/sync.js

@@ -28,6 +28,10 @@ module.exports = {
 		// sync a filesystem of XYPDF files to xyOps resources
 		// xy sync --up all --dry
 		// xy sync --up "events,plugins" --delete plugins
+		// System Hook deletion is a separate, local-only command.  Dispatch it
+		// before loading remote lists or interpreting ordinary sync directions.
+		if ('syshook' in this.args) return await this.runSyncSyshook();
+		
 		await this.getMultiple();
 		
 		// Both ordinary sync and setup completion commands report failures through
@@ -48,6 +52,7 @@ module.exports = {
 		
 		// allow sync config in config files and/or cli args
 		var sconfig = this.sconfig = Tools.mergeHashes( this.config.sync || {}, this.args || {} );
+		var ignore_missing = !!sconfig.ignore_missing;
 		if (!sconfig.up && !sconfig.down) {
 			this.die("Please enable sync up and/or down modes.  Type 'xy help sync' for details.");
 		}
@@ -137,6 +142,7 @@ module.exports = {
 		
 		// load all xypdf files
 		var items = [];
+		var seen_sources = new Map();
 		
 		files.filter( file => !!file.path.match(/\.json$/i) && !this.isSyncBucketExtraFile(file.path, bucket_extra_dirs) ).forEach( file => {
 			// file: { path, size, mtime }
@@ -211,16 +217,14 @@ module.exports = {
 				return;
 			}
 			
-			var xy_item = Tools.findObject(list, { id: item.data.id });
-			if (!xy_item) {
-				this.logSyncWarning("Cannot find " + item.type + " in xyOps: " + item.data.title + " (" + item.data.id + "), will be skipped from sync.");
-				return;
-			}
-			
-			if (Tools.findObjectDeep(items, { 'type': item.type, 'data.id': item.data.id })) {
+			// Check duplicate identities even when their remote definition is
+			// missing, so --ignore_missing only relaxes the missing-ID check.
+			var source_key = item.type + '\0' + item.data.id;
+			if (seen_sources.has(source_key)) {
 				this.logSyncWarning("Duplicate source item found: " + file.path + " (skipping)");
 				return;
 			}
+			seen_sources.set(source_key, file.path);
 			
 			// locate any external neighbor prop files
 			var neighbor_error = false;
@@ -287,6 +291,19 @@ module.exports = {
 			// do not include item if neighbor loading or validation failed
 			if (neighbor_error) return;
 			
+			var xy_item = Tools.findObject(list, { id: item.data.id });
+			if (!xy_item) {
+				// An opted-in Git sync can briefly retain a source after its xyOps
+				// definition is deleted.  Skip only that source and keep scanning.
+				if (ignore_missing) {
+					println(" Skipping local " + item.type + " missing from xyOps: " + (item.data.title || item.data.id) + " (" + item.data.id + ")");
+					return;
+				}
+				
+				this.logSyncWarning("Cannot find " + item.type + " in xyOps: " + item.data.title + " (" + item.data.id + "), will be skipped from sync.");
+				return;
+			}
+			
 			// include effective mtime in item for two-way sync
 			item.mtime = file.mtime;
 			
@@ -435,11 +452,14 @@ module.exports = {
 	
 	getSyncLockFile() {
 		// Allow a fixed path for service installations.  Otherwise, serialize all
-		// local syncs targeting the exact same configured xyOps base URL.
+		// local syncs targeting the exact same configured xyOps base URL.  Local
+		// System Hook deletions need no server config, so share a fixed lock key
+		// when no base URL is available.
 		var sconfig = Tools.mergeHashes( this.config.sync || {}, this.args || {} );
 		if (sconfig.lock_file) return Path.resolve('' + sconfig.lock_file);
 		
-		var digest = Tools.digestHex( this.config.base_url, 'sha256', 16);
+		var base_url = this.config.base_url || (('syshook' in this.args) ? 'syshook-local' : '');
+		var digest = Tools.digestHex( base_url, 'sha256', 16);
 		return Path.join( os.tmpdir(), 'xyops-cli-sync-' + digest + '.pid' );
 	},
 	
@@ -824,8 +844,9 @@ module.exports = {
 		}
 		if (new_only && this.args.force) this.die("Sync setup --new cannot be combined with --force.");
 		
+		var ignore_missing = !!this.args.ignore_missing;
 		var default_ext = this.normalizeSyncDefaultExt(this.args.default_ext);
-		var existing_keys = new_only ? this.scanSyncSourceIndex(['.']) : {};
+		var existing_keys = new_only ? this.scanSyncSourceIndex(['.'], { ignore_missing }) : {};
 		
 		this.printBoxList({
 			title: 'Sync Setup',
@@ -889,7 +910,7 @@ module.exports = {
 		return ext;
 	},
 	
-	scanSyncSourceIndex(base_dirs) {
+	scanSyncSourceIndex(base_dirs, opts = {}) {
 		// Build an identity index from an existing sync tree.  Filenames and folders
 		// are deliberately ignored, because sync sources may be freely reorganized.
 		var files = [];
@@ -900,6 +921,7 @@ module.exports = {
 		});
 		
 		var index = {};
+		var seen_sources = new Map();
 		var bucket_extra_dirs = [];
 		files.filter( file => !!file.path.match(/\.json$/i) ).forEach( file => {
 			try {
@@ -941,14 +963,26 @@ module.exports = {
 			if (!type_def) this.die("Cannot locate internal type definition: " + item.type);
 			var list = this[type_def.list];
 			if (!list) this.die("Cannot locate internal list: " + type_def.list);
+			
+			// Keep duplicate detection independent of remote existence, including
+			// for sources intentionally skipped with --ignore_missing.
+			var key = item.type + '-' + item.data.id;
+			if (seen_sources.has(key)) {
+				this.die("Duplicate source item found: " + file.path + " (already found in " + seen_sources.get(key) + ")");
+			}
+			seen_sources.set(key, file.path);
+			
 			if (!Tools.findObject(list, { id: item.data.id })) {
+				// New-only setup needs the same grace period as ordinary sync.
+				// A missing local source does not represent a new remote item.
+				if (opts.ignore_missing) {
+					println(" Skipping local " + item.type + " missing from xyOps: " + (item.data.title || item.data.id) + " (" + item.data.id + ")");
+					return;
+				}
+				
 				this.die("Cannot find " + item.type + " in xyOps: " + (item.data.title || item.data.id) + " (" + item.data.id + ")");
 			}
 			
-			var key = item.type + '-' + item.data.id;
-			if (index[key]) {
-				this.die("Duplicate source item found: " + file.path + " (already found in " + index[key].file + ")");
-			}
 			index[key] = { file: file.path, item: item };
 		});
 		

package/lib/transfer.js

@@ -86,7 +86,7 @@ module.exports = {
 		if (this.format.match(/json/)) return this.jsonOutput({ code: 0, file: filename, count: items.length, warnings: warnings });
 		
 		this.toast('✅', 'green', "Exported " + items.length + " item(s) to: " + filename);
-		warnings.forEach( warning => println(yellow(warning)) );
+		warnings.forEach( warning => warnln(yellow(warning)) );
 	},
 	
 	parseExportDependencies(value) {
@@ -316,7 +316,7 @@ module.exports = {
 		
 		if (this.format.match(/json/)) return this.jsonOutput(report);
 		
-		warnings.forEach( warning => println(yellow(warning)) );
+		warnings.forEach( warning => warnln(yellow(warning)) );
 		
 		this.printBoxTable({
 			title: 'Import Results',
@@ -324,7 +324,7 @@ module.exports = {
 			rows: results.map( item => [item.type, item.id || '(New)', item.title, item.status] )
 		});
 		
-		if (error) println("\n " + red('Import stopped: ' + error) + '\n Earlier successful changes remain in place.');
+		if (error) warnln("\n " + red('Import stopped: ' + error) + '\n Earlier successful changes remain in place.');
 		else this.printSuggestedCommands({
 			"List events": "xy events",
 			"List categories": "xy categories",

package/lib/utils.js

@@ -1011,7 +1011,7 @@ module.exports = {
 		// load client config from xyops and cache for a while
 		var { err, data } = await this.cacheAPI('config', { format: 'json' }, { cache_ttl: 3600 });
 		if (err) {
-			println( "\n" + bold.red("Failed to contact xyOps at: ") + this.config.base_url );
+			warnln( "\n" + bold.red("Failed to contact xyOps at: ") + this.config.base_url );
 			this.die(err);
 		}
 		
@@ -1265,7 +1265,11 @@ module.exports = {
 		// cli.box performs word wrapping at this content width and never ellipsizes.
 		var available_width = Math.max( 1, (cli.width() || 80) - 7 );
 		var max_width = Math.min( available_width, cli.stringWidth(final_text) );
-		println( "\n" + cli.box(final_text, { width: max_width, hspace: 2, vspace: 1, indent: 1, styles: [this.color(color)] }) );
+		var message = "\n" + cli.box(final_text, { width: max_width, hspace: 2, vspace: 1, indent: 1, styles: [this.color(color)] });
+		
+		// Keep warning and error toasts visible when routine output is quiet.
+		if (['⚠️', '🛑', '❌', '☢️'].includes(emoji)) warnln(message);
+		else println(message);
 	},
 	
 	printMutationSummary(opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pixlcore/xycli",
-	"version": "1.0.8",
+	"version": "1.0.9",
 	"description": "A complete command-line interface for the xyOps workflow automation system.",
 	"author": "Joseph Huckaby <jhuckaby@pixlcore.com>",
 	"homepage": "https://github.com/pixlcore/xycli",
@@ -21,7 +21,7 @@
 	],
 	"scripts": {
 		"test": "node test.js",
-		"test:offline": "node --test test/config.test.js test/help.test.js test/markdown.test.js test/sync-buckets-unit.test.js test/sync-unit.test.js test/toast.test.js test/upgrade.test.js test/utils-unit.test.js",
+		"test:offline": "node --test test/config.test.js test/help.test.js test/markdown.test.js test/sync-buckets-unit.test.js test/sync-syshook-unit.test.js test/sync-unit.test.js test/toast.test.js test/upgrade.test.js test/utils-unit.test.js",
 		"changelog": "node tools/changelog.js"
 	},
 	"dependencies": {

package/test/help.test.js

@@ -1,6 +1,7 @@
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
 const Path = require('node:path');
+const { spawnSync } = require('node:child_process');
 const { xy } = require('./helpers/common.js');
 
 // Deliberately shadow any developer-machine configuration. Help and command
@@ -51,3 +52,58 @@ test('unknown top-level command does not suggest an unrelated command', () => {
 	assert.match(output, /Unknown command: completely_unrelated/);
 	assert.doesNotMatch(output, /Did you mean/);
 });
+
+test('quiet mode prints sync diagnostics and bound warnings on stderr', () => {
+	// Run the real CLI startup so this checks the warn override and the global
+	// binding installed by cli.global(), without contacting a server.
+	const script = `
+		process.argv = [process.execPath, require.resolve('./index.js'), 'help', '--quiet'];
+		process.on('beforeExit', () => {
+			const cli = require('pixl-cli');
+			cli.warnln('Fixture cli warning');
+			warnln('Fixture warning');
+			warn('Fixture direct warning\\n');
+			const utils = require('./lib/utils.js');
+			const context = { colors: { orange: [255, 105, 0], red: [251, 44, 54], green: [0, 201, 80] }, color: utils.color };
+			utils.toast.call(context, '⚠️', 'orange', 'Fixture toast warning');
+			utils.toast.call(context, '🛑', 'red', 'Fixture toast error');
+			utils.toast.call(context, '✅', 'green', 'Fixture success');
+			const sync = require('./lib/sync.js');
+			sync.logSyncWarning.call({ warnings: [] }, 'Fixture sync warning');
+			sync.logSyncError.call({ errors: [] }, 'Fixture sync error');
+			println('Routine output');
+		});
+		require('./index.js');
+	`;
+	const result = spawnSync(process.execPath, ['-e', script], {
+		cwd: Path.join(__dirname, '..'),
+		encoding: 'utf8',
+		env: { ...process.env, ...offlineEnv },
+		windowsHide: true
+	});
+	
+	assert.ifError(result.error);
+	assert.equal(result.status, 1);
+	assert.equal(result.stdout, '');
+	assert.match(result.stderr, /Fixture cli warning/);
+	assert.match(result.stderr, /Fixture warning/);
+	assert.match(result.stderr, /Fixture direct warning/);
+	assert.match(result.stderr, /Fixture toast warning/);
+	assert.match(result.stderr, /Fixture toast error/);
+	assert.match(result.stderr, /Fixture sync warning/);
+	assert.match(result.stderr, /Fixture sync error/);
+	assert.doesNotMatch(result.stderr, /Fixture success/);
+});
+
+test('quiet invalid usage reports an error on stderr', () => {
+	const result = spawnSync(process.execPath, [Path.join(__dirname, '..', 'index.js'), 'upgrade', 'unexpected', '--quiet'], {
+		encoding: 'utf8',
+		env: { ...process.env, ...offlineEnv },
+		windowsHide: true
+	});
+	
+	assert.ifError(result.error);
+	assert.equal(result.status, 1);
+	assert.equal(result.stdout, '');
+	assert.match(result.stderr, /Invalid usage.*xy help upgrade/);
+});

package/test/sync-syshook-unit.test.js

@@ -0,0 +1,231 @@
+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 { spawnSync } = require('node:child_process');
+
+function makeTree(t) {
+	var dir = fs.mkdtempSync(Path.join(os.tmpdir(), 'xycli-syshook-test-'));
+	t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+	return dir;
+}
+
+function writeSource(dir, name, type, data) {
+	var file = Path.join(dir, name);
+	fs.mkdirSync(Path.dirname(file), { recursive: true });
+	fs.writeFileSync(file, JSON.stringify({
+		type: 'xypdf', version: '1.0', items: [{ type, data }]
+	}));
+	return file;
+}
+
+function runHook(dir, action, payload, extra = [], use_default_lock = false) {
+	// Strip xyOps connection variables to match the conductor's shell-hook
+	// environment.  The hook must complete without credentials or API access.
+	var env = { ...process.env, HOME: dir };
+	for (const key of Object.keys(env)) {
+		if (key.startsWith('XYOPS_')) delete env[key];
+	}
+	
+	var args = [Path.join(__dirname, '..', 'index.js'), 'sync', dir, '--syshook', action];
+	if (!use_default_lock) args.push('--lock_file', Path.join(dir, '.sync-lock'));
+	args.push(...extra);
+	
+	return spawnSync(process.execPath, args, {
+		input: payload === null ? '' : JSON.stringify(payload) + '\n',
+		encoding: 'utf8',
+		timeout: 10000,
+		env
+	});
+}
+
+function markerCommand(name) {
+	var code = `require('node:fs').writeFileSync(${JSON.stringify(name)}, process.cwd())`;
+	return `${JSON.stringify(process.execPath)} -e ${JSON.stringify(code)}`;
+}
+
+test('syshook deletes only the exact Event and its owned neighbors', t => {
+	var dir = makeTree(t);
+	var event = writeSource(dir, 'events/Ops/Nightly.json', 'event', {
+		id: 'evt_one', title: 'Nightly', params: { script: '(External)' }
+	});
+	var neighbor = Path.join(dir, 'events/Ops/Nightly-params.script.sh');
+	fs.writeFileSync(neighbor, 'echo one\n');
+	var other = writeSource(dir, 'events/Ops/Nightly-V2.json', 'event', {
+		id: 'evt_two', title: 'Nightly V2', params: { script: '(External)' }
+	});
+	var other_neighbor = Path.join(dir, 'events/Ops/Nightly-V2-params.script.sh');
+	fs.writeFileSync(other_neighbor, 'echo two\n');
+	var new_event = writeSource(dir, 'events/Ops/New.json', 'event', { id: 'evt_new', title: 'New' });
+	var same_id_plugin = writeSource(dir, 'plugins/Shared.json', 'plugin', { id: 'evt_one', title: 'Shared' });
+	var marker = Path.join(dir, 'completed.txt');
+	
+	var result = runHook(dir, 'event_delete', {
+		xy: 1, action: 'event_delete', event: { id: 'evt_one', title: 'Nightly' }
+	}, ['--down_cmd', markerCommand('completed.txt')]);
+	
+	assert.ifError(result.error);
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(fs.existsSync(event), false);
+	assert.equal(fs.existsSync(neighbor), false);
+	assert.equal(fs.existsSync(other), true);
+	assert.equal(fs.existsSync(other_neighbor), true);
+	assert.equal(fs.existsSync(new_event), true);
+	assert.equal(fs.existsSync(same_id_plugin), true);
+	assert.equal(fs.readFileSync(marker, 'utf8'), fs.realpathSync(dir));
+});
+
+test('syshook uses its default lock without a configured xyOps URL or API Key', t => {
+	var dir = makeTree(t);
+	var event = writeSource(dir, 'events/Delete-Me.json', 'event', { id: 'evt_no_config' });
+	var result = runHook(dir, 'event_delete', {
+		xy: 1, action: 'event_delete', event: { id: 'evt_no_config' }
+	}, [], true);
+	
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(fs.existsSync(event), false);
+});
+
+test('syshook rejects a mismatched action without deleting files', t => {
+	var dir = makeTree(t);
+	var file = writeSource(dir, 'plugins/Shared.json', 'plugin', { id: 'plugin_one', title: 'Shared' });
+	var result = runHook(dir, 'plugin_delete', {
+		xy: 1, action: 'event_delete', plugin: { id: 'plugin_one' }
+	}, ['--down_cmd', markerCommand('completed.txt')]);
+	
+	assert.equal(result.status, 1);
+	assert.match(result.stderr, /does not match --syshook plugin_delete/);
+	assert.equal(fs.existsSync(file), true);
+	assert.equal(fs.existsSync(Path.join(dir, 'completed.txt')), false);
+});
+
+test('syshook deletes a matching Plugin without changing another Plugin', t => {
+	var dir = makeTree(t);
+	var target = writeSource(dir, 'plugins/Shared.json', 'plugin', { id: 'plugin_one', title: 'Shared' });
+	var other = writeSource(dir, 'plugins/Other.json', 'plugin', { id: 'plugin_two', title: 'Other' });
+	var result = runHook(dir, 'plugin_delete', {
+		xy: 1, action: 'plugin_delete', plugin: { id: 'plugin_one' }
+	});
+	
+	assert.equal(result.status, 0, result.stderr);
+	assert.equal(fs.existsSync(target), false);
+	assert.equal(fs.existsSync(other), true);
+});
+
+// Each remaining standard sync type uses the same exact type-and-ID lookup.
+// Include another Event with the target ID to catch an accidental ID-only
+// match, especially for the API Key action's different spelling.
+for (const [action, type] of [
+	['alert_delete', 'alert'],
+	['apikey_delete', 'api_key'],
+	['category_delete', 'category'],
+	['channel_delete', 'channel'],
+	['group_delete', 'group'],
+	['monitor_delete', 'monitor'],
+	['tag_delete', 'tag'],
+	['web_hook_delete', 'web_hook']
+]) {
+	test('syshook deletes one ' + type + ' for ' + action, t => {
+		var dir = makeTree(t);
+		var target = writeSource(dir, type + '/Target.json', type, { id: 'shared_id' });
+		var other = writeSource(dir, type + '/Other.json', type, { id: 'other_id' });
+		var event = writeSource(dir, 'events/Shared.json', 'event', { id: 'shared_id' });
+		var result = runHook(dir, action, {
+			xy: 1, action, [type]: { id: 'shared_id' }
+		});
+		
+		assert.equal(result.status, 0, result.stderr);
+		assert.equal(fs.existsSync(target), false);
+		assert.equal(fs.existsSync(other), true);
+		assert.equal(fs.existsSync(event), true);
+	});
+}
+
+test('syshook rejects bucket deletion and preserves its source', t => {
+	var dir = makeTree(t);
+	var bucket = writeSource(dir, 'buckets/Shared.json', 'bucket', { id: 'bucket_one' });
+	var result = runHook(dir, 'bucket_delete', {
+		xy: 1, action: 'bucket_delete', bucket: { id: 'bucket_one' }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.stderr, /Invalid --syshook action/);
+	assert.equal(fs.existsSync(bucket), true);
+});
+
+test('syshook checks neighboring files before deleting the source', t => {
+	var dir = makeTree(t);
+	var target = writeSource(dir, 'events/Ops/Nightly.json', 'event', { id: 'evt_one', title: 'Nightly' });
+	var unrelated = Path.join(dir, 'events/Ops/Nightly-other.txt');
+	fs.writeFileSync(unrelated, 'keep me\n');
+	var result = runHook(dir, 'event_delete', {
+		xy: 1, action: 'event_delete', event: { id: 'evt_one' }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.stderr, /Neighbor file does not match a string property/);
+	assert.equal(fs.existsSync(target), true);
+	assert.equal(fs.existsSync(unrelated), true);
+});
+
+test('syshook stops on malformed JSON before deleting a matching source', t => {
+	var dir = makeTree(t);
+	var target = writeSource(dir, 'events/Ops/Nightly.json', 'event', { id: 'evt_one', title: 'Nightly' });
+	fs.writeFileSync(Path.join(dir, 'events/Ops/Broken.json'), '{bad json');
+	var result = runHook(dir, 'event_delete', {
+		xy: 1, action: 'event_delete', event: { id: 'evt_one' }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.stderr, /Failed to parse JSON file/);
+	assert.equal(fs.existsSync(target), true);
+});
+
+test('syshook refuses duplicate XYPDF sources before changing either file', t => {
+	var dir = makeTree(t);
+	var data = { id: 'plugin_one', title: 'Shared', script: '(External)' };
+	var first = writeSource(dir, 'plugins/First.json', 'plugin', data);
+	var second = writeSource(dir, 'plugins/Second.json', 'plugin', data);
+	var result = runHook(dir, 'plugin_delete', {
+		xy: 1, action: 'plugin_delete', plugin: { id: 'plugin_one' }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.stderr, /Duplicate XYPDF sources/);
+	assert.equal(fs.existsSync(first), true);
+	assert.equal(fs.existsSync(second), true);
+});
+
+test('syshook dry run and absent source never run down_cmd', t => {
+	var dir = makeTree(t);
+	var file = writeSource(dir, 'plugins/Shared.json', 'plugin', { id: 'plugin_one', title: 'Shared' });
+	var command = markerCommand('completed.txt');
+	var payload = { xy: 1, action: 'plugin_delete', plugin: { id: 'plugin_one' } };
+	var preview = runHook(dir, 'plugin_delete', payload, ['--dry', '--down_cmd', command]);
+	
+	assert.equal(preview.status, 0, preview.stderr);
+	assert.match(preview.stdout, /Would delete:/);
+	assert.equal(fs.existsSync(file), true);
+	assert.equal(fs.existsSync(Path.join(dir, 'completed.txt')), false);
+	
+	var absent = runHook(dir, 'plugin_delete', {
+		xy: 1, action: 'plugin_delete', plugin: { id: 'other' }
+	}, ['--down_cmd', command]);
+	assert.equal(absent.status, 0, absent.stderr);
+	assert.equal(fs.existsSync(file), true);
+	assert.equal(fs.existsSync(Path.join(dir, 'completed.txt')), false);
+});
+
+test('syshook reports a failed down_cmd after deleting the matched source', t => {
+	var dir = makeTree(t);
+	var file = writeSource(dir, 'plugins/Shared.json', 'plugin', { id: 'plugin_one', title: 'Shared' });
+	var command = `${JSON.stringify(process.execPath)} -e "process.exit(2)"`;
+	var result = runHook(dir, 'plugin_delete', {
+		xy: 1, action: 'plugin_delete', plugin: { id: 'plugin_one' }
+	}, ['--down_cmd', command]);
+	
+	assert.equal(result.status, 1);
+	assert.match(result.stderr, /Command failed/);
+	assert.equal(fs.existsSync(file), false);
+});

package/test/sync-unit.test.js

@@ -227,6 +227,73 @@ test('sync errors exit nonzero even in quiet mode or a dry run', t => {
 	}
 });
 
+test('sync ignore-missing skips only absent remote IDs and continues updates', t => {
+	const remote = { id: 'present', title: 'Present', notes: 'Remote' };
+	const local = { ...remote, notes: 'Local' };
+	const missing = { id: 'gone', title: 'Gone', notes: 'Keep this file' };
+	const result = runSync(t, {
+		categories: [remote],
+		existingSources: [
+			{ path: 'Gone.json', type: 'category', data: missing },
+			{ path: 'Present.json', type: 'category', data: local }
+		],
+		args: { up: 'categories', down: 'categories', delete: false, ignore_missing: true }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.deepEqual(result.report.warnings, []);
+	assert.equal(result.report.calls.includes('update_category'), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'Gone.json')), true);
+	assert.equal(JSON.parse(fs.readFileSync(Path.join(result.dir, 'Gone.json'), 'utf8')).items[0].data.notes, 'Keep this file');
+});
+
+test('sync ignore-missing does not suppress malformed source warnings', t => {
+	const result = runSync(t, {
+		source: { id: 'missing', title: 'Missing' },
+		emptyItems: true,
+		args: { up: 'categories', ignore_missing: true }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.report.warnings[0], /empty, malformed or missing items array/);
+	assert.deepEqual(result.report.calls, []);
+});
+
+test('sync ignore-missing still validates neighbors of missing sources', t => {
+	const result = runSync(t, {
+		source: { id: 'missing', title: 'Missing' },
+		invalidNeighbor: true,
+		args: { up: 'categories', ignore_missing: true }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.report.warnings[0], /Neighbor file does not match/);
+	assert.deepEqual(result.report.calls, []);
+});
+
+test('sync ignore-missing still rejects duplicate missing sources', t => {
+	const result = runSync(t, {
+		source: { id: 'missing', title: 'Missing' },
+		duplicateSource: true,
+		args: { up: 'categories', ignore_missing: true }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.report.warnings[0], /Duplicate source item found/);
+	assert.deepEqual(result.report.calls, []);
+});
+
+test('sync ignore-missing can be disabled over a saved setting', t => {
+	const result = runSync(t, {
+		source: { id: 'missing', title: 'Missing' },
+		config: { up: 'categories', ignore_missing: true },
+		args: { ignore_missing: false }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.report.warnings[0], /Cannot find category in xyOps/);
+});
+
 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' };
@@ -313,6 +380,39 @@ test('sync setup new exports only remote definitions missing from the local tree
 	assert.equal(fs.existsSync(Path.join(result.dir, 'custom', 'layout', 'Renamed-Existing.json')), true);
 });
 
+test('sync setup new ignore-missing leaves stale files and exports new definitions', t => {
+	const missing = { id: 'gone', title: 'Gone' };
+	const added = { id: 'added', title: 'Added Plugin', command: 'node' };
+	const result = runSync(t, {
+		setup: ['plugins'],
+		plugins: [added],
+		existingSources: [{ path: 'old/Gone.json', type: 'plugin', data: missing }],
+		args: { new: true, ignore_missing: true }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.deepEqual(result.report.warnings, []);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'old', 'Gone.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins', 'Added-Plugin.json')), true);
+});
+
+test('sync setup new ignore-missing still rejects duplicate missing sources', t => {
+	const missing = { id: 'gone', title: 'Gone' };
+	const result = runSync(t, {
+		setup: ['plugins'],
+		plugins: [{ id: 'added', title: 'Added Plugin', command: 'node' }],
+		existingSources: [
+			{ path: 'old/Gone.json', type: 'plugin', data: missing },
+			{ path: 'other/Gone.json', type: 'plugin', data: missing }
+		],
+		args: { new: true, ignore_missing: true }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.stderr, /Duplicate source item found/);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins', 'Added-Plugin.json')), false);
+});
+
 test('sync setup runs down_cmd after writing files from the setup directory', t => {
 	const marker = 'setup-complete.txt';
 	const result = runSync(t, {

package/test/toast.test.js

@@ -7,14 +7,14 @@ cli.global();
 
 test('toast wraps within the terminal width without ellipsis', () => {
 	const originalWidth = cli.width;
-	const originalWrite = process.stdout.write;
+	const originalWrite = process.stderr.write;
 	const originalColor = cli.chalk.enabled;
 	let output = '';
 	
 	try {
 		cli.width = function() { return 40; };
 		cli.chalk.enabled = false;
-		process.stdout.write = function(chunk) {
+		process.stderr.write = function(chunk) {
 			output += chunk;
 			return true;
 		};
@@ -27,7 +27,7 @@ test('toast wraps within the terminal width without ellipsis', () => {
 	finally {
 		cli.width = originalWidth;
 		cli.chalk.enabled = originalColor;
-		process.stdout.write = originalWrite;
+		process.stderr.write = originalWrite;
 	}
 	
 	const box_lines = output.split('\n').filter( line => line.match(/[┌│└]/) );