@pixlcore/xycli 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# xyCLI Changelog
+
+## Version v1.0.0
+
+> September 20, 2026
+
+- Initial release!

package/README.md

@@ -26,6 +26,7 @@ Browse the [screenshot gallery](docs/screenshots.md) for more views, or jump to
 - [Configuration](#configuration)
 - [Global CLI switches](#global-cli-switches)
 - [Tutorial: your first Event, job, and Web Hook](docs/tutorial.md)
+- [Tutorial: two-way sync with Git](docs/two-way-git-tutorial.md)
 - [Explore and manage xyOps](#explore-and-manage-xyops)
 - [Transfer data between systems](#transfer-data-between-systems)
 - [Sync your automation with local files](#sync-your-automation-with-local-files)
@@ -483,7 +484,7 @@ cd xyops-automation
 xy sync setup events plugins categories --file_props script,params.script
 ```
 
-Setup creates one file per definition and can extract scripts into adjacent source files. You choose how to organize the tree afterward; sync scans subdirectories and matches definitions by resource type and exact ID.
+Setup creates one file per definition and can extract scripts into adjacent source files. Events and workflows are automatically grouped into subfolders named after their Categories. You can reorganize the tree afterward; sync scans subdirectories and matches definitions by resource type and exact ID.
 
 Preview a push or pull, then apply the direction you want:
 
@@ -499,6 +500,8 @@ Sync supports Alerts, API Keys, Categories, Channels, Events and workflows, Grou
 
 Delete mode is for up-sync only: it removes eligible xyOps objects missing from your local inventory. Objects with a `stock` or `marketplace` property are always protected from deletion and need no local files. Keep a complete inventory of the other objects you intend to retain for each selected type, and review a dry run before applying it. Sync applies changes without a confirmation step unless you use `--dry`.
 
+Follow the [Two-Way Git Sync Tutorial](docs/two-way-git-tutorial.md) to connect one persistent checkout to a shared repository, commit downloaded changes, discover new Events, and schedule the complete workflow with cron or xySat.
+
 Read the dedicated [Sync Guide](docs/sync.md) for setup, file layouts, every option, saved defaults, two-way sync, deletion, notifications, and automation with cron, Git hooks, and GitHub Actions.
 
 - **Command reference:** [Sync commands](docs/help.md#sync) and [Sync setup](docs/help.md#sync-setup).
@@ -540,4 +543,4 @@ xy api runEvent --id EVENT_ID --params.example VALUE --dry
 xy api updateEvent --json @./request.json --dry
 ```
 
-The examples with `--dry` display the request without calling the API. Many resource views also accept `--format json` to display their data as JSON. See the [xyOps API Reference](https://docs.xyops.io/api), [API command](docs/help.md#api), and [documentation command](docs/help.md#doc) for more.
+The examples with `--dry` display the request without calling the API. Many resource views also accept `--format json` to display their data as JSON. See the [xyOps API Reference](https://docs.xyops.io/#Docs/api), [API command](docs/help.md#api), and [documentation command](docs/help.md#doc) for more.

package/docs/help.md

@@ -281,6 +281,9 @@ Export existing xyOps definitions into a starter sync tree in the current direct
 ```sh
 xy sync setup events plugins categories --dry
 xy sync setup events plugins categories --file_props script,params.script
+xy sync setup events --file_props params.script --default_ext ps1
+xy sync setup events plugins --new
+xy sync setup events --new --down_cmd "./commit-downloads.sh"
 xy sync setup all
 xy sync setup all --stock --marketplace
 xy sync setup events plugins --force
@@ -289,17 +292,25 @@ xy sync --setup events,plugins --file_props script,params.script
 
 Choose one or more resource types separated by spaces, or use `all`. Supported types are the same as for `xy sync`. The `--setup TYPES` form also accepts a comma-separated list.
 
-Setup creates one folder per resource type and one XYPDF JSON file per object, using its title as a filename slug. Selecting `events` exports both Events and workflows, with workflows placed in a separate `workflows` folder. Both are synced with `--up events` or `--down events`.
+Setup creates one folder per resource type and one XYPDF JSON file per object, using its title as a filename slug. Selecting `events` exports both Events and workflows, with workflows placed in a separate `workflows` folder. Events and workflows are grouped into subfolders using their Category title as a slug. Both are synced with `--up events` or `--down events`. Setup stops before writing if an Event or workflow selected for export refers to a missing Category.
 
 - `--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.
+- `--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.
 - `--marketplace` includes Marketplace objects, which are omitted by default.
 - `--force` allows generated files to overwrite existing destinations.
 - `--dry` previews the layout without creating directories or writing files.
 
-For `--file_props`, use comma-separated property names or dot paths, such as `script,params.script`. Only nonempty string values are extracted. The JSON value becomes `(External)`, and sync loads the external file automatically.
+For `--file_props`, use comma-separated property names or dot paths, such as `script,params.script`. Only nonempty string values are extracted. The JSON value becomes `(External)`, and sync loads the external file automatically. Setup chooses extensions from executable commands, shebangs, and JSON content when possible. Use `--default_ext ps1` (or `--default_ext .ps1`) to replace the `.txt` fallback for properties whose type cannot be detected. The override does not replace an extension that setup successfully detects.
 
-Without `--force`, setup stops when an output file already exists. Files written before an error are not rolled back. Ensure object titles produce distinct filename slugs, especially when using `--force`, and back up any local edits before rerunning setup. For a delete-mode inventory, verify that every object eligible for deletion that you intend to keep has a source file. Stock and Marketplace objects are protected from deletion and may be omitted.
+Use `--new` from the root of an existing sync tree to add definitions that exist in xyOps but have no local source. Setup scans recursively and matches existing sources by item type and exact ID, so renamed files and custom folder layouts are preserved. New definitions use the normal suggested type and Category folders. Malformed, duplicate, unsupported, or orphaned local sources stop the operation before any new files are written. `--new` cannot be combined with `--force`, and it does not create new definitions in xyOps.
+
+An explicitly supplied `--down_cmd` runs from the current setup directory after at least one definition is written. It does not run when `--new` finds nothing or during a dry run. Saved sync completion commands are not inherited by setup.
+
+Without `--force`, ordinary setup stops when an output file already exists. Files written before an error are not rolled back. Ensure object titles produce distinct filename slugs, especially when using `--force`, and back up any local edits before rerunning setup. For a delete-mode inventory, verify that every object eligible for deletion that you intend to keep has a source file. Stock and Marketplace objects are protected from deletion and may be omitted.
 
 ## api
 

package/docs/sync.md

@@ -113,18 +113,20 @@ xyops-automation/
     categories/
         Backups.json
     events/
-        Nightly-Backup.json
-        Nightly-Backup-params.script.sh
+        Operations/
+            Nightly-Backup.json
+            Nightly-Backup-params.script.sh
     plugins/
         Custom-Runner.json
         Custom-Runner-script.js
     workflows/
-        Release-Pipeline.json
+        Deployments/
+            Release-Pipeline.json
 ```
 
-Setup creates one folder per selected resource type and one JSON file per definition. Event and workflow exports are separated into `events/` and `workflows/`. Both participate in normal sync through the `events` selection.
+Setup creates one folder per selected resource type and one JSON file per definition. Event and workflow exports are separated into `events/` and `workflows/`, then grouped into subfolders using their Category titles. Both participate in normal sync through the `events` selection.
 
-Filenames come from each definition's title: sequences of non-word characters become hyphens, and leading or trailing hyphens are removed. For example, `Nightly Backup` becomes `Nightly-Backup.json`. Different titles can produce the same filename, so review the preview for collisions.
+Folder and filenames come from Category and definition titles: sequences of non-word characters become hyphens, and leading or trailing hyphens are removed. For example, the Event `Nightly Backup` in the `Operations` Category becomes `events/Operations/Nightly-Backup.json`. Different titles can produce the same path, so review the preview for collisions. Setup stops before writing anything if an Event or workflow selected for export refers to a Category that is not present in xyOps.
 
 ### 4. Review and version the tree
 
@@ -159,6 +161,17 @@ xy sync setup events plugins --force
 
 `--force` allows generated JSON and external files to be overwritten. It does not clean up old filenames, solve filename collisions, or preserve your local edits. Export into a fresh directory when adding newly created objects, then move their reviewed files into the existing tree. 
 
+To add only definitions that are new to an existing sync tree, run setup from the tree's root with `--new`:
+
+```sh
+xy sync setup events plugins categories --new --file_props script,params.script --dry
+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`.
+
+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.
+
 Alternatively, you can export single objects at a time:
 
 ```sh
@@ -232,6 +245,8 @@ This extracts the selected content, if found, and moves it to a neighboring file
 
 The general naming pattern is **`BASENAME-PROPERTY.EXT`**, in the same directory as `BASENAME.json`. Dot paths such as `params.script` identify nested properties. Setup chooses an extension from the executable command or a script's shebang when possible, falling back to JSON-looking content or `.txt`. Normal sync accepts your chosen extension.
 
+Use `--default_ext EXT` to replace the `.txt` fallback when setup cannot detect a type. For example, `--default_ext ps1` and `--default_ext .ps1` both produce `.ps1` neighbors. Detected interpreter and JSON extensions still take precedence. The fallback applies to every undetected property selected by that setup command, so group properties with the same expected file type or run setup separately when needed.
+
 External properties are detected automatically when sync runs; you do not need to repeat `--file_props`. The neighbor's text replaces that property in the local definition before comparison and before an upload. A pull writes the latest value into the existing neighbor file.
 
 You can use this for other string properties too, such as `body` or `notes`. Keep only one neighbor file per unique property path. A neighbor must resolve to a valid property path, and multiple matching neighbors are not treated as alternative versions.
@@ -393,12 +408,16 @@ At least one direction must be enabled. The command is a single run, not a backg
 | `xy sync setup TYPES...` | Export the selected types to the current directory. Separate type names with spaces, or use `all`. |
 | `--setup TYPES` | Alternative setup syntax, accepting comma-separated type names. For example, `xy sync --setup events,plugins`. |
 | `--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. |
+| `--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. |
 | `--marketplace` | Include Marketplace Plugins, which setup normally omits. |
 | `--force` | Allow generated files to overwrite existing destinations. |
 | `--dry` | Preview setup's output without creating folders or files. |
 
-Workflow defaults in the `sync` configuration object are not used by setup. Pass setup choices explicitly on the command line. The common `lock_file` setting still applies so setup cannot overlap another sync operation for the same instance.
+Workflow defaults in the `sync` configuration object are not used by setup. Pass setup choices explicitly on the command line. An explicitly supplied `down_cmd` runs from the current setup directory only after real files are written, so it does not run during a dry run or when `--new` finds nothing. The common `lock_file` setting still applies so setup cannot overlap another sync operation for the same instance.
 
 ## Two-way sync and modification times
 
@@ -501,6 +520,7 @@ xy sync ./ --down events,plugins --down_cmd "./commit-downloads.sh" --cmd_timeou
 
 - `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.
+- 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.
 - A completion command can run after partial success even if another item failed. It is not proof that the whole run succeeded.
@@ -898,7 +918,7 @@ Repository concurrency controls these workflow runs. Coordinate all writers to t
 | A script edit has no effect | Check the matching JSON stem, property suffix, filename extension, and property path. Hidden paths are skipped. |
 | Two-way sync overwrites an unexpected side | Compare the remote modification time with the newest JSON/property-file mtime. Fresh checkouts, clock skew, or touched files can make local sources appear newer. |
 | An Event or workflow does not execute | Sync saves definitions; it does not run them. Use `xy run EVENT_ID` separately. |
-| `down_cmd` does not run | It requires at least one successful download. A no-op, dry run, scan failure, or deletion alone does not trigger it. |
+| `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. |

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

@@ -0,0 +1,262 @@
+# Two-Way Git Sync Tutorial
+
+> [!IMPORTANT]
+> Some of the features used in this tutorial require xyCLI v1.0.2 or newer.
+
+This tutorial sets up one persistent Git checkout as the bridge between xyOps and a shared repository. Team members can edit and push Event files through Git, while changes made in the xyOps web interface are downloaded, committed, and pushed back to the repository.
+
+The finished workflow looks like this:
+
+```text
+Developers <-> Git repository <-> Dedicated sync checkout <-> xyOps
+```
+
+One machine and operating-system account should own the dedicated sync checkout. That machine can be an xyOps worker running xySat, but xySat is not required. Cron, another scheduler, or a manually launched script works too.
+
+This tutorial manages Events and workflows. You can expand the commands to other [supported resource types](sync.md#supported-resources-and-requirements) after the Event flow is working.
+
+## Before you begin
+
+You will need:
+
+- xyCLI installed and connected to xyOps.
+- A dedicated Git repository and a persistent clone on the sync machine.
+- A xyOps API Key that can read and edit Events and update the global sync state.
+- Git credentials that allow the sync account to pull and push without an interactive prompt.
+- A configured Git author name and email for automated commits.
+- Accurate clocks on the sync machine and the xyOps conductor, preferably synchronized through NTP.
+- The `flock` command on the scheduler host if you plan to use cron.
+
+Two-way sync is experimental. When the local and remote definitions differ, xyCLI compares the xyOps modification timestamp with the newest modification time among the local JSON file and its external property files. The newer side wins, and equal timestamps favor the local copy.
+
+Do not periodically replace the dedicated checkout with a fresh clone. Git checkout operations can change filesystem timestamps, which are part of two-way conflict resolution.
+
+## 1. Prepare the dedicated checkout
+
+Clone the repository into a permanent location. Replace the example URL and path with your own:
+
+```sh
+git clone git@github.com:YOUR_ORG/xyops-automation.git /srv/xyops-automation
+cd /srv/xyops-automation
+```
+
+Configure the identity used for commits created by sync:
+
+```sh
+git config user.name "xyOps Sync"
+git config user.email "xyops-sync@example.com"
+```
+
+Run all remaining setup commands as the same operating-system account that will run the scheduled job. Configure xyCLI for that account if you have not already done so:
+
+```sh
+xy config --base_url https://xyops.example.com --api_key YOUR_API_KEY
+xy dashboard
+```
+
+The dashboard command verifies the connection. Keep the API Key and Git credentials out of the repository.
+
+## 2. Export the initial Event tree
+
+Preview the initial setup from the repository root:
+
+```sh
+cd /srv/xyops-automation
+xy sync setup events --file_props script,params.script --default_ext ps1 --dry
+```
+
+The `events` selection includes both Events and workflows. Setup places workflows in their own `workflows/` directory, then groups Events and workflows into subfolders named after their Categories.
+
+`--file_props script,params.script` extracts common Plugin and Event script properties into neighboring files. If your Plugin uses another property, add its dot path to the list. For example, use `script,params.script,params.command` when an Event stores its PowerShell source in `params.command`.
+
+The optional `--default_ext ps1` uses `.ps1` when setup cannot detect a neighbor file's language from an executable command, shebang, or JSON content. Remove it or choose another extension if PowerShell is not the appropriate fallback for your repository.
+
+When the preview looks correct, write the files:
+
+```sh
+xy sync setup events --file_props script,params.script --default_ext ps1
+```
+
+Review the generated files before publishing them. Definitions can contain scripts, request headers, and other sensitive configuration.
+
+```sh
+git status --short
+find events workflows -type f -print 2>/dev/null
+```
+
+Commit and push the initial tree:
+
+```sh
+git add --all
+git commit -m "Add xyOps Event definitions"
+git push -u origin HEAD
+```
+
+Setup is only responsible for creating the local source files. Normal sync identifies each definition by its resource type and exact ID inside the JSON, so you may reorganize or rename the generated files afterward.
+
+## 3. Preview two-way sync
+
+Run a dry pass before enabling automation:
+
+```sh
+xy sync . --up events --down events --delete false --dry
+```
+
+This considers both directions for every local Event and workflow source:
+
+- A newer local file is uploaded to its existing xyOps definition.
+- A newer xyOps definition is downloaded to its existing local file.
+- Identical definitions are left alone.
+
+The `--delete false` switch is intentional. Two-way sync does not propagate deletions safely. Delete an item deliberately on both sides, and keep deletion disabled in the scheduled command.
+
+Review the displayed diffs carefully. If the wrong side would win, check the clocks and file modification times before continuing.
+
+## 4. Create the scheduled sync script
+
+Save the following script as `/usr/local/sbin/xyops-git-sync`. Adjust `PATH`, `REPO_DIR`, `XY_BIN`, the extracted property list, and the fallback extension for your environment.
+
+```sh
+#!/bin/sh
+set -eu
+
+# Cron and xySat jobs often receive a minimal environment. Include the
+# directories containing Node.js, xyCLI, Git, and standard system tools.
+PATH="/usr/local/bin:/usr/bin:/bin"
+export PATH
+
+REPO_DIR="/srv/xyops-automation"
+XY_BIN="/usr/local/bin/xy"
+
+cd "$REPO_DIR"
+
+# This should be a dedicated automated checkout. Stop instead of accidentally
+# committing an operator's unfinished work or leftovers from a failed run.
+if [ -n "$(git status --porcelain)" ]; then
+	echo "The sync checkout has uncommitted changes. Resolve them before retrying."
+	exit 1
+fi
+
+# Bring in changes pushed by contributors. The extra push retries a commit
+# that may have succeeded during an earlier run whose network push then failed.
+git pull --quiet --ff-only
+git push --quiet
+
+# xyCLI runs this only after it writes local definitions.
+GIT_DOWN_CMD="git add --all && git commit -m 'Sync from xyOps' && git push"
+
+# Sync changes to existing local definitions in both directions. If this
+# command fails, set -e stops the script before the setup pass.
+"$XY_BIN" sync . \
+	--up events \
+	--down events \
+	--delete false \
+	--down_cmd "$GIT_DOWN_CMD" \
+	--cmd_timeout 120
+
+# Discover definitions created in xyOps since the initial setup. Existing
+# sources are identified by type and ID, regardless of their paths or names.
+# The setup completion command runs only when new files were actually written.
+"$XY_BIN" sync setup events \
+	--new \
+	--file_props script,params.script \
+	--default_ext ps1 \
+	--down_cmd "$GIT_DOWN_CMD" \
+	--cmd_timeout 120
+```
+
+Make the script executable:
+
+```sh
+chmod 755 /usr/local/sbin/xyops-git-sync
+```
+
+Run it manually as the eventual scheduler account before installing a schedule:
+
+```sh
+/usr/local/sbin/xyops-git-sync
+```
+
+The script intentionally does not implement its own outer lock. A cron caller will use `flock` to protect the complete pull, normal sync, and new-definition setup sequence. When xyOps schedules the script through xySat, the Event's job concurrency setting provides this protection instead. xyCLI's built-in lock still protects each individual sync command.
+
+The two uses of `--down_cmd` are deliberately identical:
+
+- Ordinary sync runs it only after at least one existing definition is successfully downloaded.
+- `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 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
+
+Open the crontab for the sync account:
+
+```sh
+crontab -e
+```
+
+Locate `flock` and adjust the path in the cron entry if necessary:
+
+```sh
+command -v flock
+```
+
+Run the script every minute, with `flock` outside the script:
+
+```cron
+* * * * * /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.
+
+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.
+
+`--nonblock` makes an overlapping invocation exit immediately instead of waiting. `--conflict-exit-code 0` treats that expected skip as a successful scheduler run, while an executed sync script still returns its own exit status. The operating system releases the advisory lock automatically when `flock` exits, including when the sync script fails. The `/tmp/xyops-git-sync.lock` file may remain afterward, which is normal and does not mean the lock is still held. See the [`flock` manual](https://man7.org/linux/man-pages/man1/flock.1.html) for details.
+
+## 6. Or schedule it through xySat
+
+On a machine running xySat, create an Event using the Shell Plugin and target only the dedicated sync worker. Give it a recurring one-minute schedule and use this script body:
+
+```sh
+/usr/local/sbin/xyops-git-sync
+```
+
+Keep the Event's [job concurrency setting](https://docs.xyops.io/#Docs/limits/max-jobs-limit) at `1`, which is the default. xyOps will then prevent a second copy of the Event from running while the first job is still active, so this invocation does not need `flock`.
+
+The xySat service account must be able to execute the script, read and write the repository, run Node.js and xyCLI, access that account's xyCLI configuration, and use the Git credentials. Test the Event manually before enabling its schedule.
+
+Schedule only one copy of this workflow, and do not run both cron and xySat for the same checkout.
+
+## 7. Understand the daily workflow
+
+After setup, contributors work through Git as usual:
+
+```sh
+git pull
+# Edit Event JSON or neighboring script files.
+git add --all
+git commit -m "Update nightly report"
+git push
+```
+
+The next scheduled pass pulls the commit and uploads newer local definitions to xyOps. If someone edits an existing Event in the xyOps web interface, the next pass downloads the newer definition, and `--down_cmd` commits and pushes the changed files.
+
+When someone creates a new Event in xyOps, the ordinary sync pass does not know where to create its local source. The following `sync setup events --new` pass discovers it, creates the suggested files in its Category folder, then commits and pushes them through its own `--down_cmd`.
+
+`--new` is additive. It does not overwrite existing sources, and it matches existing definitions by type and exact ID rather than filename. This preserves renamed files and custom folder layouts.
+
+## Troubleshooting
+
+| Symptom | What to check |
+| --- | --- |
+| `git pull --ff-only` fails | The sync clone and remote branch have diverged, or the working tree changed. Resolve the Git state manually. Do not force-reset the automated checkout without reviewing its commits. |
+| `git push` prompts or fails under cron or xySat | Configure noninteractive SSH or HTTPS credentials for the scheduler account and confirm the branch allows that account to push. |
+| Git reports an unknown author | Set `user.name` and `user.email` in the dedicated clone for the scheduler account. |
+| The wrong side wins a two-way conflict | Check NTP, the xyOps conductor clock, and the modification times of the JSON and neighboring files. A checkout, restore, or file copy can refresh local timestamps. |
+| A new Event is not exported | Confirm `sync setup events --new` runs from the repository root and that the API Key can see the Event. Add the correct property path if its script is stored somewhere other than `params.script`. |
+| A new Git file is not created in xyOps | Ordinary sync updates definitions that already exist on both sides. Create or import the definition into xyOps first, then let sync manage subsequent changes. |
+| A deleted item reappears or causes an error | Two-way deletion is not supported. Remove the local source and the xyOps definition deliberately as one coordinated operation. |
+| A 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. |
+
+For the complete behavior and option reference, see the [Filesystem Sync Guide](sync.md) and the [`sync` command reference](help.md#sync).

package/lib/sync.js

@@ -30,6 +30,11 @@ module.exports = {
 		// xy sync --up "events,plugins" --delete plugins
 		await this.getMultiple();
 		
+		// Both ordinary sync and setup completion commands report failures through
+		// the shared warning and error collectors.
+		this.warnings = [];
+		this.errors = [];
+		
 		// optionally setup local filesystem for sync
 		if (this.args.other && (this.args.other[0] === 'setup')) {
 			this.args.other.shift();
@@ -72,9 +77,6 @@ module.exports = {
 			this.die("Delete mode requires up-only sync. Enable --up and disable --down.");
 		}
 		
-		this.warnings = [];
-		this.errors = [];
-		
 		// scan all base directories, default to cwd
 		var files = [];
 		if (!this.args.other || !this.args.other.length) {
@@ -635,17 +637,19 @@ module.exports = {
 		} // run_event
 	},
 	
-	syncFinishCmd(cmd) {
+	syncFinishCmd(cmd, opts) {
 		// spawn command and log output
-		var sconfig = this.sconfig;
-		var cwd = this.args.other[0]; // use first base dir as cwd for shell commands
+		opts = opts || {};
+		var sconfig = this.sconfig || {};
+		var cwd = opts.cwd || this.args.other[0]; // default to first normal sync base dir
+		var cmd_timeout = opts.cmd_timeout || sconfig.cmd_timeout || 30;
 		
 		println( "\n " + green.bold("Running completion command: ") + cyan.bold(cmd) );
 		
 		try {
 			const output = cp.execSync(cmd, {
 				cwd: cwd,
-				timeout: (sconfig.cmd_timeout || 30) * 1000,
+				timeout: cmd_timeout * 1000,
 				encoding: 'utf8',
 				stdio: ['ignore', 'pipe', 'pipe']
 			});
@@ -732,12 +736,8 @@ module.exports = {
 	async setupSync() {
 		// export select resources to local XYPDF files in suggested layout
 		// xy sync --setup all --file_props "script,params.script"
+		// xy sync --setup events --new
 		// xy sync --setup all --marketplace --stock --force
-		var data_types = this.config.ui.data_types;
-		var list_data_types = Object.keys(data_types).map( key => {
-			return { ...data_types[key], id: key };
-		} );
-		
 		if ((this.args.setup === 'all') || (this.args.setup[0] === 'all')) {
 			this.args.setup = this.config.ui.list_list.map( list => list.id ).filter( id => !id.match(/^(buckets|secrets|users|roles)$/) );
 		}
@@ -760,87 +760,279 @@ module.exports = {
 			if (!Array.isArray(this.args.file_props)) this.dieUsage('sync setup');
 		}
 		
+		// New-only setup is intentionally an additive operation.  It must never be
+		// combined with the overwrite behavior of --force.
+		var new_only = false;
+		if (this.args.new !== undefined) {
+			if ((this.args.new !== true) && (this.args.new !== false)) {
+				this.die("Invalid --new value (use --new or --new false).");
+			}
+			new_only = this.args.new;
+		}
+		if (new_only && this.args.force) this.die("Sync setup --new cannot be combined with --force.");
+		
+		var default_ext = this.normalizeSyncDefaultExt(this.args.default_ext);
+		var existing_keys = new_only ? this.scanSyncSourceIndex(['.']) : {};
+		
 		this.printBoxList({
 			title: 'Sync Setup',
 			rows: [
 				['Item Types', this.args.setup.join(', ')],
 				['File Props', this.args.file_props ? this.args.file_props.join(', ') : '(None)'],
+				['Default Ext', '.' + default_ext],
+				new_only ? ['New Only', 'Yes'] : null,
 				this.dry ? ['Dry Run', 'No changes will be made.'] : null
 			]
 		});
 		
 		println( "\n " + this.color('theme').bold("WRITING FILES:") );
 		
-		// split up workflows into their own folder
-		if (this.args.setup.includes('events')) {
-			this.workflows = this.events.filter( event => event.type == 'workflow' );
-			this.events = this.events.filter( event => event.type != 'workflow' );
-			this.args.setup.push('workflows');
-			list_data_types.push( { id: "event", "list": "workflows" } );
+		var result = this.writeSyncSetupFiles(this.args.setup, {
+			base_dir: '.',
+			existing_keys: existing_keys,
+			new_only: new_only,
+			file_props: this.args.file_props || [],
+			default_ext: default_ext,
+			stock: !!this.args.stock,
+			marketplace: !!this.args.marketplace,
+			force: !!this.args.force,
+			dry: !!this.dry
+		});
+		
+		if (new_only && !result.written) println( "\n " + gray("No new definitions found.") );
+		
+		println( "\n " + this.color('theme').bold("Setup complete!") );
+		
+		// Setup writes into the current directory, not a positional base directory.
+		// Only run an explicitly supplied down command after real files were written.
+		if (!this.dry && result.written && this.args.down_cmd) {
+			this.syncFinishCmd(this.args.down_cmd, {
+				cwd: '.',
+				cmd_timeout: this.args.cmd_timeout
+			});
+		}
+	},
+	
+	normalizeSyncDefaultExt(value) {
+		// Allow users to choose the fallback extension for extracted properties whose
+		// language cannot be detected.  A leading dot is accepted for convenience,
+		// but paths and compound values are rejected before any files are written.
+		if (value === undefined) return 'txt';
+		if (typeof(value) != 'string') {
+			this.die("Invalid --default_ext value (use a filename extension such as ps1 or .ps1).");
 		}
 		
-		this.args.setup.forEach( (list_name) => {
-			var list = this[list_name];
-			if (!list || !list.length) return;
+		var ext = value.trim().replace(/^\./, '');
+		if (!ext.match(/^[A-Za-z0-9][A-Za-z0-9_]*$/)) {
+			this.die("Invalid --default_ext value (use a filename extension such as ps1 or .ps1).");
+		}
+		return ext;
+	},
+	
+	scanSyncSourceIndex(base_dirs) {
+		// Build an identity index from an existing sync tree.  Filenames and folders
+		// are deliberately ignored, because sync sources may be freely reorganized.
+		var files = [];
+		base_dirs.forEach( dir => {
+			dir = Path.normalize(dir).replace(/[\\/]+$/, '') || '.';
+			if (!fs.existsSync(dir)) this.die("Sync base dir does not exist: " + dir);
+			files = files.concat( Tools.findFilesSync(dir, { stats: true }) );
+		});
+		
+		var index = {};
+		files.filter( file => !!file.path.match(/\.json$/i) ).forEach( file => {
+			var xypdf = null;
+			try { xypdf = Tools.parseJSON( fs.readFileSync(file.path, 'utf8') ); }
+			catch (err) { this.die("Failed to parse JSON file: " + file.path + ": " + err); }
 			
-			var type_def = Tools.findObject( list_data_types, { list: list_name } );
-			if (!type_def) return; // sanity
+			// Ordinary JSON files are unrelated and may coexist in the tree.
+			if (!xypdf || !Tools.isaHash(xypdf) || (xypdf.type !== 'xypdf')) return;
+			if (xypdf.version !== '1.0') this.die("File is not a compatible version of XYPDF: " + file.path);
+			if (xypdf.xyops !== undefined && this.compareVersions(xypdf.xyops, this.xyopsVersion) > 0) {
+				this.die("Item requires xyOps v" + xypdf.xyops + " or higher: " + file.path);
+			}
+			if (!Array.isArray(xypdf.items) || (xypdf.items.length !== 1)) {
+				this.die("Sync source must contain exactly one item: " + file.path);
+			}
 			
-			if (!this.dry) Tools.mkdirp.sync( list_name );
-			println( "\n " + cli.emoji('📂') + " " + bold.cyan(list_name + '/') );
+			var item = xypdf.items[0];
+			if (!item || !Tools.isaHash(item) || !item.type || (typeof(item.type) != 'string')) {
+				this.die("Malformed item type in file: " + file.path);
+			}
+			if (item.type.match(/^(bucket|secret|user|role)$/)) {
+				this.die("Unsupported item type: " + item.type + " in file: " + file.path);
+			}
+			if (!item.data || !Tools.isaHash(item.data) || !item.data.id || (typeof(item.data.id) != 'string')) {
+				this.die("Malformed or missing item data or ID in file: " + file.path);
+			}
 			
-			list.forEach( (item) => {
-				// exclude marketplace and stock items
-				if (item.marketplace && !this.args.marketplace) return;
-				if (item.stock && !this.args.stock) return;
+			var type_def = this.config.ui.data_types[item.type];
+			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);
+			if (!Tools.findObject(list, { id: item.data.id })) {
+				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 };
+		});
+		
+		return index;
+	},
+	
+	writeSyncSetupFiles(list_names, opts = {}) {
+		// Write selected remote definitions using setup's suggested layout.  Keeping
+		// this operation separate allows a future downsync to append newly discovered
+		// remote definitions after it finishes updating existing local sources.
+		var data_types = this.config.ui.data_types;
+		var list_data_types = Object.keys(data_types).map( key => {
+			return { ...data_types[key], id: key };
+		});
+		var targets = [];
+		
+		list_names.forEach( list_name => {
+			if (list_name == 'events') {
+				targets.push({ name: 'events', type: 'event', items: this.events.filter( event => event.type != 'workflow' ) });
+				targets.push({ name: 'workflows', type: 'event', items: this.events.filter( event => event.type == 'workflow' ) });
+				return;
+			}
+			
+			var type_def = Tools.findObject( list_data_types, { list: list_name } );
+			if (type_def) targets.push({ name: list_name, type: type_def.id, items: this[list_name] || [] });
+		});
+		
+		var result = { written: 0, skipped: 0 };
+		var existing_keys = opts.existing_keys || {};
+		var base_dir = opts.base_dir || '.';
+		var default_ext = this.normalizeSyncDefaultExt(opts.default_ext);
+		
+		// Build and validate the complete write plan before creating any directories.
+		// Events and workflows are grouped under their xyOps Category titles.  A
+		// missing Category indicates inconsistent remote data, so setup must stop
+		// without leaving behind a partially generated tree.
+		targets.forEach( target => {
+			var items = target.items.filter( item => {
+				if (item.marketplace && !opts.marketplace) return false;
+				if (item.stock && !opts.stock) return false;
+				if (opts.new_only && existing_keys[target.type + '-' + item.id]) {
+					result.skipped++;
+					return false;
+				}
+				return true;
+			});
+			
+			target.plans = items.map( source_item => {
+				var dir = Path.join(base_dir, target.name);
+				var display_dir = target.name + '/';
+				
+				if (target.type == 'event') {
+					var category = Tools.findObject( this.categories, { id: source_item.category } );
+					if (!category) {
+						this.die("Cannot find Category for " + (source_item.type == 'workflow' ? 'workflow' : 'Event') + ": " + (source_item.title || source_item.id) + " (" + (source_item.category || 'missing ID') + ")");
+					}
+					
+					var category_slug = this.getSyncSetupTitleSlug(category.title, 'Category', category.id);
+					dir = Path.join(dir, category_slug);
+					display_dir += category_slug + '/';
+				}
 				
-				// extract extras first
+				var title = this.getSyncSetupTitleSlug(source_item.title, (source_item.type == 'workflow' ? 'workflow' : target.type), source_item.id);
+				return { source_item, title, dir, display_dir };
+			});
+			
+			// Remote Event order is not guaranteed to keep Categories together. Group
+			// plans explicitly so each printed folder heading owns every file shown
+			// beneath it, while preserving the first-seen order of folders and items.
+			var groups_by_dir = new Map();
+			var plan_groups = [];
+			target.plans.forEach( plan => {
+				var group = groups_by_dir.get(plan.dir);
+				if (!group) {
+					group = [];
+					groups_by_dir.set(plan.dir, group);
+					plan_groups.push(group);
+				}
+				group.push(plan);
+			});
+			target.plans = [].concat(...plan_groups);
+		});
+		
+		// All Categories are now known to be valid, so it is safe to start writing.
+		targets.forEach( target => {
+			var active_dir = '';
+			target.plans.forEach( plan => {
+				var dir = plan.dir;
+				if (dir != active_dir) {
+					if (!opts.dry) Tools.mkdirp.sync(dir);
+					println( "\n " + cli.emoji('📂') + " " + bold.cyan(plan.display_dir) );
+					active_dir = dir;
+				}
+			
+				// Work on a deep copy so setup never changes the cached remote definition.
+				var item = Tools.copyHash(plan.source_item, true);
 				var extras = [];
-				(this.args.file_props || []).forEach( (path) => {
+				(opts.file_props || []).forEach( path => {
 					var extra = Tools.getPath(item, path);
 					if ((typeof(extra) == 'string') && extra.match(/\S/)) {
 						extras.push({ path, content: extra });
-						
-						// we do not need to check the return value of setPath here,
-						// because this path is guaranteed to exist at this point
 						Tools.setPath( item, path, "(External)" );
 					}
-				} );
+				});
 				
-				var data = this.getItemExportData(type_def.id, item);
-				var title = item.title.replace(/\W+/g, '-').replace(/\-+$/, '').replace(/^\-+/, '');
+				var data = this.getItemExportData(target.type, item);
+				var title = plan.title;
 				var filename = title + '.json';
-				var file = Path.join(list_name, filename);
+				var file = Path.join(dir, filename);
 				
-				if (!this.dry) {
-					if (!this.args.force && fs.existsSync(file)) this.die("File exists, add '--force' to overwrite all: " + file);
+				if (!opts.dry) {
+					if (!opts.force && fs.existsSync(file)) this.die("File exists, add '--force' to overwrite all: " + file);
 					Tools.writeFileAtomicSync( file, JSON.stringify(data, null, "\t") + "\n" );
 				}
 				println( "    " + cli.emoji('📄') + " " + bold.green(filename) );
+				result.written++;
 				
-				// now handle extras
-				extras.forEach( (extra) => {
+				extras.forEach( extra => {
 					var command = item.command;
 					if (!command && extra.content.match(/^\s*\#\!(.+?)\n/)) command = RegExp.$1;
 					
-					var ext = 'txt';
-					if (command) ext = this.getExtFromBinary(command);
+					var ext = default_ext;
+					if (command) {
+						var detected_ext = this.getExtFromBinary(command);
+						if (detected_ext != 'txt') ext = detected_ext;
+					}
 					else if (extra.content.trim().match(/^\{[\S\s]*\}$/) || extra.content.trim().match(/^\[[\S\s]*\]$/)) ext = 'json';
 					
 					var extra_filename = title + '-' + extra.path + '.' + ext;
-					var extra_file = Path.join(list_name, extra_filename);
-					
-					if (!this.dry) {
-						if (!this.args.force && fs.existsSync(extra_file)) this.die("File exists, add '--force' to overwrite all: " + extra_file);
+					var extra_file = Path.join(dir, extra_filename);
+					if (!opts.dry) {
+						if (!opts.force && fs.existsSync(extra_file)) this.die("File exists, add '--force' to overwrite all: " + extra_file);
 						Tools.writeFileAtomicSync( extra_file, extra.content );
 					}
-					
 					println( "    " + cli.emoji('📜') + " " + bold.yellow(extra_filename) );
-				} );
-			} ); // foreach item
-		} ); // foreach list
+				});
+			});
+		});
 		
-		println( "\n " + this.color('theme').bold("Setup complete!") );
+		return result;
+	},
+	
+	getSyncSetupTitleSlug(title, item_type, item_id) {
+		// Use one filename-safe transformation for definitions and Category folders.
+		// Reject unusable titles explicitly instead of silently producing `.json` or
+		// collapsing an Event back into the top-level resource directory.
+		if (typeof(title) != 'string') {
+			this.die("Cannot create sync setup path for " + item_type + ": Missing title (" + item_id + ")");
+		}
+		
+		var slug = title.replace(/\W+/g, '-').replace(/\-+$/, '').replace(/^\-+/, '');
+		if (!slug) {
+			this.die("Cannot create sync setup path for " + item_type + ": Title has no usable filename characters (" + item_id + ")");
+		}
+		return slug;
 	},
 	
 	getItemExportData(type, item) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pixlcore/xycli",
-	"version": "1.0.1",
+	"version": "1.0.2",
 	"description": "A complete command-line interface for the xyOps workflow automation system.",
 	"author": "Joseph Huckaby <jhuckaby@pixlcore.com>",
 	"homepage": "https://github.com/pixlcore/xycli",
@@ -20,7 +20,8 @@
 		"xyops", "cli"
 	],
 	"scripts": {
-		"test": "node test.js"
+		"test": "node test.js",
+		"changelog": "node tools/changelog.js"
 	},
 	"dependencies": {
 		"@pixlcore/xyops-sdk": "^1.0.7",

package/test/README.md

@@ -67,7 +67,7 @@ node --test test/config.test.js test/sync-unit.test.js
 | `servers` | Active and recently offline lists, local filters, installer generation, historical search, live and historical Server details, charts, processes, connections, pagination, validation, help |
 | `system` | Admin dashboard, conductors, connected users, export, maintenance, optimization, rate resets, diagnostics, broadcasts, help |
 | `sync` | Setup export, isolated filesystem discovery, external property files, dry-run, upsync, downsync, composite global-state governance, no-op detection, and guarded delete mode |
-| `sync-unit` | Offline PID locking and stale recovery, up-only deletion guards, pre-delete failure blocking, stock/Marketplace deletion protection, inherited settings and CLI overrides, warning/error exit status, duplicates, quiet/dry runs, completion failures, and notification delivery after warnings or errors |
+| `sync-unit` | Offline setup extension fallbacks, new-only exports and setup completion commands, PID locking and stale recovery, up-only deletion guards, pre-delete failure blocking, stock/Marketplace deletion protection, inherited settings and CLI overrides, warning/error exit status, duplicates, quiet/dry runs, completion failures, and notification delivery after warnings or errors |
 | `tags` | CRUD, metadata search, sparse future-proof updates, JSON input, validation, pagination, help |
 | `tickets` | Search, CRUD, number resolution, comments, attachment uploads/downloads, Events, related Job lookup, sparse updates, validation, help |
 | `toast` | Warning-box word wrapping and terminal-width limits |

package/test/sync-unit.test.js

@@ -13,28 +13,31 @@ const script = `
 	const cli = require('pixl-cli');
 	cli.global();
 	const options = JSON.parse(process.argv[1]);
-	cli.args.quiet = true;
+	cli.args.quiet = options.quiet !== false;
+	const sync = require('./lib/sync.js');
+	if (options.setupCwd) process.chdir(options.setupCwd);
 	const calls = [];
 	const requests = [];
 	const app = {
-		...require('./lib/sync.js'),
+		...sync,
 		args: options.args,
 		config: {
 			base_url: 'https://fixture.invalid',
 			sync: options.config || {},
 			ui: {
 				list_list: ['categories', 'events', 'plugins'].map(id => ({ id })),
-				data_types: { category: { list: 'categories' }, plugin: { list: 'plugins' } }
+				data_types: { category: { list: 'categories' }, event: { list: 'events' }, plugin: { list: 'plugins' } }
 			}
 		},
 		state: {},
 		categories: options.categories || [],
-		events: [],
+		events: options.events || [],
 		plugins: options.plugins || [],
 		version: 'test',
 		dry: !!options.args.dry,
 		color() { return cli.chalk.white; },
 		markdown(text) { return text; },
+		printBoxList() {},
 		compareVersions() { return 0; },
 		async getMultiple() {},
 		die(message) { throw new Error(message); },
@@ -58,6 +61,7 @@ function runSync(t, options) {
 	const dir = fs.mkdtempSync(Path.join(os.tmpdir(), 'xycli-sync-unit-'));
 	t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
 	const args = { other: [dir], ...options.args };
+	if (options.setup) args.other = ['setup', ...options.setup];
 	
 	if (options.source) {
 		fs.writeFileSync(Path.join(dir, 'Category.json'), JSON.stringify({
@@ -79,9 +83,25 @@ function runSync(t, options) {
 			fs.copyFileSync(Path.join(dir, 'Category.json'), Path.join(dir, 'Duplicate.json'));
 		}
 	}
+	if (options.existingSources) {
+		options.existingSources.forEach(source => {
+			const file = Path.join(dir, source.path);
+			fs.mkdirSync(Path.dirname(file), { recursive: true });
+			const contents = source.contents !== undefined ? source.contents : JSON.stringify({
+				type: 'xypdf',
+				version: '1.0',
+				items: [{ type: source.type, data: source.data }]
+			});
+			fs.writeFileSync(file, contents);
+		});
+	}
 	if (options.missingDir) args.other = [Path.join(dir, 'missing')];
 	
-	const result = spawnSync(process.execPath, ['-e', script, JSON.stringify({ ...options, args })], {
+	const result = spawnSync(process.execPath, ['-e', script, JSON.stringify({
+		...options,
+		args,
+		setupCwd: options.setup ? dir : undefined
+	})], {
 		cwd: Path.join(__dirname, '..'),
 		encoding: 'utf8',
 		timeout: 10000
@@ -89,7 +109,14 @@ function runSync(t, options) {
 	assert.ifError(result.error);
 	assert.equal(result.signal, null);
 	const report = JSON.parse(result.stdout.trim().split('\n').pop());
-	return { ...result, report };
+	return { ...result, report, dir };
+}
+
+function getSetupMarkerCommand(filename) {
+	// Use the current Node.js binary so the completion-command fixture is
+	// portable and does not depend on a separate shell utility being installed.
+	const code = `require('node:fs').writeFileSync(${JSON.stringify(filename)}, process.cwd())`;
+	return `${JSON.stringify(process.execPath)} -e ${JSON.stringify(code)}`;
 }
 
 test('sync update guard requires confirmation only for the exact managed object', async () => {
@@ -217,6 +244,247 @@ test('sync API errors preserve failure status while still sending both notificat
 	}
 });
 
+test('sync setup uses a custom extension only when detection falls back to txt', t => {
+	const result = runSync(t, {
+		setup: ['plugins'],
+		plugins: [
+			{ id: 'fallback', title: 'Fallback', command: 'custom-runner', script: 'Write-Host "Hello"\n' },
+			{ id: 'detected', title: 'Detected', command: 'pwsh -File', script: 'Write-Host "Hello"\n' },
+			{ id: 'json', title: 'JSON Data', command: '', script: '{ "hello": true }\n' }
+		],
+		args: { file_props: 'script', default_ext: '.code' }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins', 'Fallback-script.code')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins', 'Detected-script.ps1')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins', 'JSON-Data-script.json')), true);
+});
+
+test('sync setup rejects unsafe or malformed default extensions before writing', t => {
+	for (const defaultExt of [true, '', '.', '../ps1', 'ps/1', 'ps-1', 'tar.gz']) {
+		const result = runSync(t, {
+			setup: ['plugins'],
+			plugins: [{ id: 'fixture', title: 'Fixture', command: 'custom-runner', script: 'Example\n' }],
+			args: { file_props: 'script', default_ext: defaultExt }
+		});
+		
+		assert.equal(result.status, 1);
+		assert.match(result.stderr, /Invalid --default_ext value/);
+		assert.equal(fs.existsSync(Path.join(result.dir, 'plugins')), false);
+	}
+});
+
+test('sync setup new exports only remote definitions missing from the local tree', t => {
+	const existing = { id: 'existing', title: 'Existing', command: 'node', script: 'console.log("Existing");\n' };
+	const added = { id: 'added', title: 'Added Plugin', command: 'custom-runner', script: 'Write-Host "Added"\n' };
+	const result = runSync(t, {
+		setup: ['plugins'],
+		plugins: [existing, added],
+		existingSources: [{
+			path: 'custom/layout/Renamed-Existing.json',
+			type: 'plugin',
+			data: existing
+		}],
+		args: { new: true, file_props: 'script', default_ext: 'ps1' }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins', 'Added-Plugin.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins', 'Added-Plugin-script.ps1')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins', 'Existing.json')), false);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'custom', 'layout', 'Renamed-Existing.json')), true);
+});
+
+test('sync setup runs down_cmd after writing files from the setup directory', t => {
+	const marker = 'setup-complete.txt';
+	const result = runSync(t, {
+		setup: ['plugins'],
+		plugins: [{ id: 'added', title: 'Added', command: 'node', script: 'Added\n' }],
+		args: {
+			file_props: 'script',
+			down_cmd: getSetupMarkerCommand(marker)
+		}
+	});
+	
+	assert.equal(result.status, 0);
+	assert.equal(fs.readFileSync(Path.join(result.dir, marker), 'utf8'), fs.realpathSync(result.dir));
+});
+
+test('sync setup new runs down_cmd only when it writes new files', t => {
+	const existing = { id: 'existing', title: 'Existing', command: 'node', script: 'Existing\n' };
+	const marker = 'setup-new-complete.txt';
+	const command = getSetupMarkerCommand(marker);
+	const added = runSync(t, {
+		setup: ['plugins'],
+		plugins: [existing, { id: 'added', title: 'Added', command: 'node', script: 'Added\n' }],
+		existingSources: [{ path: 'Existing.json', type: 'plugin', data: existing }],
+		args: { new: true, down_cmd: command }
+	});
+	
+	assert.equal(added.status, 0);
+	assert.equal(fs.existsSync(Path.join(added.dir, marker)), true);
+	
+	const unchanged = runSync(t, {
+		setup: ['plugins'],
+		plugins: [existing],
+		existingSources: [{ path: 'Existing.json', type: 'plugin', data: existing }],
+		args: { new: true, down_cmd: command }
+	});
+	
+	assert.equal(unchanged.status, 0);
+	assert.equal(fs.existsSync(Path.join(unchanged.dir, marker)), false);
+});
+
+test('sync setup does not run down_cmd during a dry run', t => {
+	const marker = 'setup-dry-complete.txt';
+	const result = runSync(t, {
+		setup: ['plugins'],
+		plugins: [{ id: 'added', title: 'Added', command: 'node', script: 'Added\n' }],
+		args: { dry: true, down_cmd: getSetupMarkerCommand(marker) }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.equal(fs.existsSync(Path.join(result.dir, marker)), false);
+});
+
+test('sync setup completion-command errors exit nonzero', t => {
+	const result = runSync(t, {
+		setup: ['plugins'],
+		plugins: [{ id: 'added', title: 'Added', command: 'node', script: 'Added\n' }],
+		args: { down_cmd: `${JSON.stringify(process.execPath)} -e "process.exit(2)"` }
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.report.errors[0], /Command failed/);
+});
+
+test('sync setup new dry run discovers additions without writing them', t => {
+	const existing = { id: 'existing', title: 'Existing', command: 'node', script: 'Existing\n' };
+	const result = runSync(t, {
+		setup: ['plugins'],
+		plugins: [existing, { id: 'added', title: 'Added', command: 'node', script: 'Added\n' }],
+		existingSources: [{ path: 'Existing-Renamed.json', type: 'plugin', data: existing }],
+		args: { new: true, dry: true, file_props: 'script' }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins')), false);
+});
+
+test('sync setup new preserves existing Events and writes new workflows separately', t => {
+	const category = { id: 'operations', title: 'Operations Team' };
+	const existing = { id: 'existing-event', title: 'Existing Event', type: 'event', category: category.id };
+	const workflow = { id: 'new-workflow', title: 'New Workflow', type: 'workflow', category: category.id };
+	const result = runSync(t, {
+		setup: ['events'],
+		categories: [category],
+		events: [existing, workflow],
+		existingSources: [{ path: 'custom/Event.json', type: 'event', data: existing }],
+		args: { new: true }
+	});
+	
+	assert.equal(result.status, 0);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'events')), false);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'workflows', 'Operations-Team', 'New-Workflow.json')), true);
+});
+
+test('sync setup groups Events and workflows into Category folders', t => {
+	const operations = { id: 'operations', title: 'Operations Team' };
+	const limited = { id: 'limited', title: 'Limited Run' };
+	const engineering = { id: 'engineering', title: 'Engineering & QA' };
+	const result = runSync(t, {
+		setup: ['events'],
+		categories: [operations, limited, engineering],
+		events: [
+			{ id: 'nightly', title: 'Nightly Backup', type: 'event', category: operations.id, params: { script: '#!/bin/sh\necho backup\n' } },
+			{ id: 'limited', title: 'Limited Event', type: 'event', category: limited.id },
+			{ id: 'release', title: 'Release Pipeline', type: 'workflow', category: engineering.id },
+			{ id: 'ondemand', title: 'On Demand Backup', type: 'event', category: operations.id }
+		],
+		args: { file_props: 'params.script' },
+		quiet: false
+	});
+	
+	assert.equal(result.status, 0);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'events', 'Operations-Team', 'Nightly-Backup.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'events', 'Operations-Team', 'Nightly-Backup-params.script.sh')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'events', 'Operations-Team', 'On-Demand-Backup.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'events', 'Limited-Run', 'Limited-Event.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'workflows', 'Engineering-QA', 'Release-Pipeline.json')), true);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'events', 'Nightly-Backup.json')), false);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'workflows', 'Release-Pipeline.json')), false);
+	
+	// The source order deliberately returns to Operations after Limited Run.
+	// Its two Events must still print beneath one folder heading.
+	const operationsHeader = result.stdout.indexOf('events/Operations-Team/');
+	const nightlyFile = result.stdout.indexOf('Nightly-Backup.json');
+	const onDemandFile = result.stdout.indexOf('On-Demand-Backup.json');
+	const limitedHeader = result.stdout.indexOf('events/Limited-Run/');
+	const limitedFile = result.stdout.indexOf('Limited-Event.json');
+	const workflowHeader = result.stdout.indexOf('workflows/Engineering-QA/');
+	assert.ok(operationsHeader < nightlyFile);
+	assert.ok(nightlyFile < onDemandFile);
+	assert.ok(onDemandFile < limitedHeader);
+	assert.ok(limitedHeader < limitedFile);
+	assert.ok(limitedFile < workflowHeader);
+	assert.equal(result.stdout.indexOf('events/Operations-Team/', operationsHeader + 1), -1);
+});
+
+test('sync setup validates all Event Categories before writing any files', t => {
+	const result = runSync(t, {
+		setup: ['plugins', 'events'],
+		plugins: [{ id: 'plugin', title: 'Plugin', script: 'Hello\n' }],
+		events: [{ id: 'orphan', title: 'Orphan Event', type: 'event', category: 'missing' }],
+		args: {}
+	});
+	
+	assert.equal(result.status, 1);
+	assert.match(result.stderr, /Cannot find Category for Event: Orphan Event \(missing\)/);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'plugins')), false);
+	assert.equal(fs.existsSync(Path.join(result.dir, 'events')), false);
+});
+
+test('sync setup new rejects overwrite mode and malformed values before writing', t => {
+	for (const args of [
+		{ new: true, force: true },
+		{ new: 'yes' }
+	]) {
+		const result = runSync(t, {
+			setup: ['plugins'],
+			plugins: [{ id: 'added', title: 'Added', command: 'node', script: 'Added\n' }],
+			args
+		});
+		
+		assert.equal(result.status, 1);
+		assert.match(result.stderr, /--new/);
+		assert.equal(fs.existsSync(Path.join(result.dir, 'plugins')), false);
+	}
+});
+
+test('sync setup new aborts on duplicate or malformed existing sources before writing', t => {
+	const existing = { id: 'existing', title: 'Existing', command: 'node', script: 'Existing\n' };
+	for (const existingSources of [
+		[
+			{ path: 'one.json', type: 'plugin', data: existing },
+			{ path: 'nested/two.json', type: 'plugin', data: existing }
+		],
+		[{ path: 'broken.json', contents: '{ nope' }],
+		[{ path: 'orphan.json', type: 'plugin', data: { id: 'missing', title: 'Missing' } }]
+	]) {
+		const result = runSync(t, {
+			setup: ['plugins'],
+			plugins: [existing, { id: 'added', title: 'Added', command: 'node', script: 'Added\n' }],
+			existingSources,
+			args: { new: true }
+		});
+		
+		assert.equal(result.status, 1);
+		assert.match(result.stderr, /Duplicate source item|Failed to parse JSON file|Cannot find plugin in xyOps/);
+		assert.equal(fs.existsSync(Path.join(result.dir, 'plugins')), false);
+	}
+});
+
 test('sync skips the entire delete pass after an update or state API failure', t => {
 	const category = { id: 'fixture', title: 'Fixture', notes: 'Remote' };
 	const orphan = { id: 'orphan', title: 'Orphan', notes: 'Delete candidate' };

package/test/sync.test.js

@@ -171,8 +171,9 @@ test('sync', async t => {
 		const categoryExport = Path.join(temp, 'categories', slugify(categoryTitle) + '.json');
 		const pluginExport = Path.join(temp, 'plugins', slugify(pluginTitle) + '.json');
 		const pluginScriptExport = Path.join(temp, 'plugins', slugify(pluginTitle) + '-script.js');
-		const eventExport = Path.join(temp, 'events', slugify(eventTitle) + '.json');
-		const eventScriptExport = Path.join(temp, 'events', slugify(eventTitle) + '-params.script.sh');
+		const eventDir = Path.join(temp, 'events', slugify(categoryTitle));
+		const eventExport = Path.join(eventDir, slugify(eventTitle) + '.json');
+		const eventScriptExport = Path.join(eventDir, slugify(eventTitle) + '-params.script.sh');
 		
 		await check('setup writes valid XYPDF and external property files', () => {
 			const category = readXYPDF(categoryExport);

package/tools/changelog.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+// Build xyCLI CHANGELOG.md file
+
+var fs = require('fs');
+var Path = require('path');
+var cp = require('child_process');
+var Tools = require('pixl-tools');
+
+var debug = (process.argv[2] == 'debug');
+
+// make sure we're in the correct dir
+process.chdir( Path.dirname( __dirname ) );
+
+// make sure git sandbox is clean
+var porcelain = cp.execSync('git status --porcelain', { encoding: 'utf8' }).trim();
+if (!debug && porcelain.length) {
+	console.error("\nERROR: Git sandbox has local changes.  Please commit these before updating the changelog.\n");
+	process.exit(1);
+}
+
+// get list of tags
+var tags = cp.execSync('git tag --list --sort=version:refname', { encoding: 'utf8' }).trim().split(/\n/).reverse();
+
+var md = '';
+md += "# xyCLI Changelog\n";
+
+var last_tag = tags.pop();
+if (!tags.length) {
+	console.error("\nERROR: No tags found after popping first one.  Please push another tag before running changelog.\n");
+	process.exit(1);
+}
+
+tags.forEach( function(tag, idx) {
+	var prev_tag = tags[idx + 1] || last_tag;
+	md += `\n## Version ${tag}\n\n`;
+	
+	var cmd = `git log ${prev_tag}..${tag} --no-merges --pretty=format:'%h %H %ad %s%n%n%b%n----PX----' --date=short`;
+	var output = cp.execSync(cmd, { encoding: 'utf8' }).trim();
+	var commits = output.split('----PX----');
+	var first = true;
+	
+	// 029a96a 029a96aebd721fe565b1b5c8f2b661564c9017f3 2025-12-30 Version 0.9.2
+	commits.forEach( function(chunk) {
+		var lines = chunk.trim().split(/\n/);
+		var line = lines.shift();
+		
+		var matches = line.trim().match(/^(\w+)\s+(\w+)\s+([\d\-]+)\s+(.+)$/);
+		if (!matches) return;
+		if (matches[4].match(/\b(CHANGELOG)\b/)) return;
+		
+		var url = 'https://github.com/pixlcore/xycli/commit/' + matches[2];
+		
+		if (first) {
+			md += `> ` + Tools.formatDate( matches[3] + ' 00:00:00', '[mmmm] [mday], [yyyy]' ) + "\n\n";
+			first = false;
+		}
+		
+		md += `- [\`${matches[1]}\`](${url}): ` + matches[4] + "\n";
+		
+		if (matches[4].match(/^Version/)) lines.forEach( function(extra) {
+			if (!extra.match(/\S/)) return;
+			extra = extra.trim();
+			if (!extra.match(/^\-/)) extra = '- ' + extra;
+			md += "\t" + extra + "\n";
+		} );
+	} );
+} );
+
+md += `\n## Version ${last_tag}\n\n> September 20, 2026\n\n- Initial release!\n`;
+
+if (debug) {
+	console.log(md);
+	process.exit(0);
+}
+
+fs.writeFileSync( 'CHANGELOG.md', md );
+
+// make sure log has actually changed
+porcelain = cp.execSync('git status --porcelain', { encoding: 'utf8' }).trim();
+if (!porcelain.length) {
+	console.error("\nWarning: Changelog has not changed since last run.  Skipping actions.\n");
+	process.exit(1);
+}
+
+cp.execSync('git add CHANGELOG.md && git commit -m "Update CHANGELOG" && git push', { stdio: 'inherit' } );