@pixlcore/xycli 1.0.0

package/lib/webhook.js

@@ -0,0 +1,414 @@
+// Web Hook Management Layer
+
+const cli = require('pixl-cli');
+const Tools = cli.Tools;
+
+const WEB_HOOK_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const WEB_HOOK_FIELDS = [
+	'title', 'enabled', 'icon', 'url', 'method', 'headers', 'header', 'body',
+	'timeout', 'retries', 'follow', 'ssl_cert_bypass', 'max_per_day', 'notes'
+];
+
+module.exports = {
+	
+	async cmd_hooks() {
+		// Short user-friendly alias for the canonical webhooks command.
+		await this.cmd_webhooks();
+	},
+	
+	async cmd_hook() {
+		// Short user-friendly alias for the canonical webhook command.
+		await this.cmd_webhook();
+	},
+	
+	async cmd_webhooks() {
+		await this.cmd_get_webhooks();
+	},
+	
+	async cmd_webhook() {
+		// Route Web Hook operations, or treat a bare ID or title as a detail lookup.
+		var cmd = this.args.other.shift();
+		if (!cmd) return this.dieUsage('webhook');
+		
+		switch (cmd) {
+			case 'list': await this.cmd_get_webhooks(); break;
+			case 'get': await this.cmd_get_webhook(); break;
+			case 'create': await this.cmd_create_webhook(); break;
+			case 'update': await this.cmd_update_webhook(); break;
+			case 'test': await this.cmd_test_webhook(); break;
+			case 'delete': await this.cmd_delete_webhook(); break;
+			
+			default:
+				this.args.other.unshift(cmd);
+				await this.cmd_get_webhook();
+			break;
+		}
+	},
+	
+	async cmd_get_webhooks() {
+		// Web Hooks are included in getMultiple, so filtering and pagination can
+		// happen locally without extra API requests.
+		this.prepSearchArgs();
+		await this.getMultiple();
+		
+		var hooks = this.web_hooks.slice(0);
+		var is_filtered = !!this.args.other.length;
+		if (is_filtered) {
+			var search = this.args.other.join(' ');
+			hooks = this.findObjectsFuzzy(hooks, {
+				id: search,
+				title: search,
+				url: search,
+				notes: search,
+				username: search
+			}, 1);
+		}
+		delete this.args.other;
+		
+		if ('enabled' in this.args) {
+			var enabled = this.parseWebHookBoolean(this.args.enabled, 'enabled');
+			hooks = hooks.filter( hook => !!hook.enabled === enabled );
+			delete this.args.enabled;
+			is_filtered = true;
+		}
+		if ('method' in this.args) {
+			var method = String(this.args.method).toUpperCase();
+			hooks = hooks.filter( hook => String(hook.method).toUpperCase() === method );
+			delete this.args.method;
+			is_filtered = true;
+		}
+		if (Tools.numKeys(this.args)) {
+			hooks = this.findObjectsFuzzy(hooks, this.args);
+			is_filtered = true;
+		}
+		
+		hooks.sort( (a, b) => String(a.title || '').toLowerCase().localeCompare(String(b.title || '').toLowerCase()) );
+		if (this.format.match(/json/)) return this.jsonOutput(hooks);
+		
+		this.printPaginatedBoxTable({
+			title: is_filtered ? 'Filtered Web Hooks' : 'All Web Hooks',
+			header: ['Hook ID', 'Title', 'Method', 'URL', 'Status', 'Modified'],
+			rows: hooks.slice(this.offset, this.offset + this.limit),
+			list: { length: hooks.length },
+			offset: this.offset,
+			limit: this.limit
+		}, hook => [
+			this.color('theme').bold(hook.id),
+			bold(hook.title),
+			String(hook.method || '').toUpperCase(),
+			hook.url,
+			this.getNiceEnabled(hook.enabled),
+			this.getRelativeDateTime(hook.modified, true)
+		]);
+		
+		this.printSuggestedCommands({
+			"View Hook details": "xy hook HOOK_ID_OR_TITLE",
+			"Create a Hook": 'xy hook create --title "My Hook" --url https://example.com/hook',
+			"List disabled Hooks": "xy hooks --enabled false",
+			"Test a Hook": "xy hook test HOOK_ID"
+		});
+	},
+	
+	async cmd_get_webhook() {
+		// Exact IDs take priority, while fuzzy titles are safe for read-only views.
+		await this.getMultiple();
+		var selector = this.args.other.join(' ') || this.args.id || this.args.title;
+		if (!selector) return this.dieUsage('webhook get');
+		
+		delete this.args.other;
+		delete this.args.id;
+		delete this.args.title;
+		if (Tools.numKeys(this.args)) return this.die("Unsupported Web Hook get option: --" + Tools.firstKey(this.args));
+		
+		var match = Tools.findObject(this.web_hooks, { id: selector }) || this.findObjectFuzzy(this.web_hooks, { title: selector });
+		if (!match) return this.die("Could not find Web Hook based on your criteria: " + selector);
+		var hook = await this.fetchWebHook(match.id);
+		if (this.format.match(/json/)) return this.jsonOutput(hook);
+		
+		this.printBoxList({
+			title: 'Web Hook Summary',
+			rows: [
+				[ 'Hook ID', gray(hook.id) ],
+				[ 'Title', this.color('theme').bold(hook.title) ],
+				[ 'Status', this.getNiceEnabled(hook.enabled) ],
+				[ 'Icon', hook.icon || gray('(None)') ],
+				[ 'URL', hook.url ],
+				[ 'Method', String(hook.method || '').toUpperCase() ],
+				[ 'Timeout', hook.timeout ? Tools.getTextFromSeconds(hook.timeout, false, true) : 'Infinite' ],
+				[ 'Retries', Tools.commify(hook.retries || 0) ],
+				[ 'Follow Redirects', hook.follow ? green('Yes') : gray('No') ],
+				[ 'SSL Cert Bypass', hook.ssl_cert_bypass ? yellow('Yes') : gray('No') ],
+				[ 'Daily Cap', hook.max_per_day ? Tools.commify(hook.max_per_day) : 'Unlimited' ],
+				[ 'Author', hook.username || gray('(Unknown)') ],
+				[ 'Created', this.getNiceDateTime(hook.created, true, true) ],
+				[ 'Modified', this.getNiceDateTime(hook.modified, true, true) ],
+				[ 'Revision', hook.revision || 1 ]
+			]
+		});
+		
+		this.printBoxTable({
+			title: 'Web Hook Headers',
+			header: ['#', 'Name', 'Value'],
+			rows: (hook.headers || []).map( (header, idx) => [idx, header.name, header.value] )
+		});
+		
+		// Bodies may contain JSON, form data, XML, or arbitrary multiline text.
+		this.printWebHookBody(hook.body);
+		if (hook.notes) this.printUserNotes('WEB HOOK NOTES', hook.notes);
+		
+		this.printSuggestedCommands({
+			"Test Hook": `xy hook test ${hook.id}`,
+			"Export Hook": `xy hook ${hook.id} --export hook.json`,
+			"Update Hook": `xy hook update ${hook.id} --timeout 60`,
+			"Replace headers": `xy hook update ${hook.id} --headers @headers.json`,
+			"Delete Hook": `xy hook delete ${hook.id}`
+		});
+	},
+	
+	async cmd_create_webhook() {
+		// Defaults mirror the web editor and provide a useful JSON request template.
+		if (this.args.other.length) return this.dieUsage('webhook create');
+		delete this.args.other;
+		
+		var params = this.prepareWebHookParams({
+			enabled: true,
+			icon: '',
+			url: '',
+			method: 'POST',
+			headers: [
+				{ name: 'Content-Type', value: 'application/json' },
+				{ name: 'User-Agent', value: 'xyOps/WebHook' }
+			],
+			body: JSON.stringify({ content: '[description]', text: '[description]' }, null, "\t"),
+			timeout: 30,
+			retries: 0,
+			follow: false,
+			ssl_cert_bypass: false,
+			max_per_day: 0,
+			notes: ''
+		}, this.args, true);
+		if (!params.title || !params.url) return this.dieUsage('webhook create');
+		
+		var data = await this.callStandardAPI('createWebHook', params, { text: 'Creating Web Hook...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data.web_hook);
+		
+		this.toast('✅', 'green', "Successfully created Web Hook: #" + data.web_hook.id);
+		this.printSuggestedCommands({
+			"View Hook details": `xy hook ${data.web_hook.id}`,
+			"Test Hook": `xy hook test ${data.web_hook.id}`,
+			"Update Hook": `xy hook update ${data.web_hook.id} --timeout 60`,
+			"List all Hooks": "xy hooks"
+		});
+	},
+	
+	async cmd_update_webhook() {
+		var id = this.consumeWebHookID();
+		var hook = await this.fetchWebHook(id);
+		
+		this.printWebHookMutationSummary('Update Web Hook', hook);
+		if (!await this.confirmSyncUpdate('web_hook', hook.id, 'Web Hook')) return;
+		if (!Tools.numKeys(this.args)) return this.die("No updates specified for Web Hook.");
+		this.printUpdateData(this.args);
+		
+		var params = this.prepareWebHookParams(hook, this.args, false);
+		params.id = id;
+		var data = await this.callStandardAPI('updateWebHook', params, { text: 'Updating Web Hook...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data);
+		this.toast('✅', 'green', "Successfully updated Web Hook: #" + id);
+	},
+	
+	async cmd_test_webhook() {
+		// Test starts with the saved definition, then applies temporary CLI changes.
+		// Nothing is persisted, but the resulting HTTP request is real unless --dry.
+		var id = this.consumeWebHookID();
+		var hook = await this.fetchWebHook(id);
+		this.printWebHookMutationSummary('Test Web Hook', hook);
+		
+		var overrides = this.prepareWebHookParams(hook, this.args, false);
+		var params = {};
+		['id'].concat(WEB_HOOK_FIELDS.filter( key => key != 'header' )).forEach( key => {
+			if (key in hook) params[key] = Tools.copyHash({ value: hook[key] }, true).value;
+		});
+		Tools.mergeHashInto(params, overrides);
+		params.id = id;
+		
+		var data = await this.callStandardAPI('testWebHook', params, { text: 'Testing Web Hook...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data.result);
+		
+		var result = data.result || {};
+		var details = String(result.details || '').trim();
+		if (result.description) details = '**Result:** ' + result.description + (details ? "\n\n" + details : '');
+		if (!details) details = result.code ? 'The Web Hook test failed without additional details.' : 'The Web Hook test completed without additional details.';
+		
+		var title = 'WEB HOOK TEST RESULTS';
+		println( "\n " + (result.code ? red.bold(title) : this.color('theme').bold(title)) );
+		println( "\n" + this.markdown(details).trimEnd() );
+	},
+	
+	async cmd_delete_webhook() {
+		var id = this.consumeWebHookID();
+		var hook = await this.fetchWebHook(id);
+		this.printWebHookMutationSummary('Delete Web Hook', hook);
+		
+		if (('confirm' in this.args) && (typeof(this.args.confirm) != 'boolean')) {
+			return this.die("Web Hook delete --confirm must be true or false.");
+		}
+		if (this.args.confirm !== true) {
+			this.toast('⚠️', 'orange', "Please confirm the Web Hook delete by adding '--confirm'.");
+			return;
+		}
+		delete this.args.confirm;
+		if (Tools.numKeys(this.args)) return this.die("Unsupported Web Hook delete option: --" + Tools.firstKey(this.args));
+		
+		var data = await this.callStandardAPI('deleteWebHook', { id: id }, { text: 'Deleting Web Hook...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data);
+		this.toast('✅', 'green', "Successfully deleted Web Hook: #" + id);
+	},
+	
+	async fetchWebHook(id) {
+		// Use the single-resource endpoint for authoritative data and access checks.
+		cli.progress.start({ amount: 1, pct: false, text: gray('→ Loading Web Hook...') });
+		var { err, data } = await this.api.getWebHook({ id: id });
+		cli.progress.end();
+		if (err) this.die(err);
+		return data.web_hook;
+	},
+	
+	consumeWebHookID() {
+		// Updates, tests, and deletes require one exact internal ID.
+		var id = this.args.other.shift() || this.args.id;
+		if (!id) this.die("Missing required Web Hook ID argument.");
+		if (this.args.other.length) this.die("Unexpected argument after Web Hook ID: " + this.args.other[0]);
+		if (this.args.id && (this.args.id !== id)) this.die("Conflicting Web Hook ID arguments.");
+		if ((typeof(id) != 'string') || !id.match(/^[a-z0-9_]+$/)) this.die("Invalid Web Hook ID: " + id);
+		delete this.args.id;
+		delete this.args.other;
+		return id;
+	},
+	
+	prepareWebHookParams(hook, input, creating) {
+		// Whole header arrays replace the saved list.  Dotted edits start from the
+		// current list, and singular --header options append after those edits.
+		var params = creating ? Tools.copyHash(hook, true) : {};
+		var allowed = WEB_HOOK_FIELDS.concat(creating ? ['id'] : []);
+		Object.keys(input).forEach( key => {
+			var root = key.split('.')[0];
+			if (!allowed.includes(root)) this.die("Unsupported Web Hook option: --" + key);
+			if (key.includes('.') && (root != 'headers')) this.die("Invalid argument path: " + key);
+			if (!creating && ['headers', 'header'].includes(root) && !('headers' in params)) {
+				params.headers = Tools.copyHash({ value: hook.headers || [] }, true).value;
+			}
+		});
+		
+		// Apply complete values first, then dotted edits, regardless of CLI order.
+		Object.keys(input).filter( key => !key.includes('.') ).forEach( key => { params[key] = input[key]; } );
+		var dotted = {};
+		Object.keys(input).filter( key => key.includes('.') ).forEach( key => { dotted[key] = input[key]; } );
+		this.mergeDotArgs(params, dotted);
+		
+		if ('header' in params) {
+			if (!('headers' in params)) params.headers = [];
+			if (!Array.isArray(params.headers)) this.die("Web Hook headers must be a JSON array.");
+			Tools.alwaysArray(params.header).forEach( header => {
+				if (typeof(header) == 'string') {
+					try { header = JSON.parse(header); }
+					catch (err) { this.die("Web Hook --header must contain a JSON object."); }
+				}
+				if (!Tools.isaHash(header)) this.die("Web Hook --header must contain a JSON object.");
+				params.headers.push(header);
+			});
+			delete params.header;
+		}
+		if ('headers' in params) params.headers = this.validateWebHookHeaders(params.headers);
+		
+		if ('title' in params) {
+			if ((typeof(params.title) != 'string') || !params.title.trim()) this.die("Web Hook title cannot be empty and must be a string.");
+			params.title = params.title.trim();
+		}
+		if ('url' in params) {
+			if (typeof(params.url) != 'string') this.die("Web Hook url must be a string.");
+			params.url = params.url.trim();
+			if (!params.url.match(/^(?:https?:\/\/|\{\{)/i)) this.die("Web Hook url must begin with http://, https://, or {{.");
+		}
+		if ('method' in params) {
+			if (typeof(params.method) != 'string') this.die("Web Hook method must be a string.");
+			params.method = params.method.toUpperCase();
+			if (!WEB_HOOK_METHODS.includes(params.method)) this.die("Invalid Web Hook method: " + params.method);
+		}
+		['enabled', 'follow', 'ssl_cert_bypass'].forEach( key => {
+			if (key in params) params[key] = this.parseWebHookBoolean(params[key], key);
+		});
+		['timeout', 'retries', 'max_per_day'].forEach( key => {
+			if (!(key in params)) return;
+			params[key] = Number(params[key]);
+			if (!Number.isSafeInteger(params[key]) || (params[key] < 0)) {
+				this.die("Web Hook " + key + " must be a non-negative integer.");
+			}
+		});
+		if (('retries' in params) && (params.retries > 999)) this.die("Web Hook retries cannot exceed 999.");
+		if (('max_per_day' in params) && (params.max_per_day > 9999999)) this.die("Web Hook max_per_day cannot exceed 9999999.");
+		['icon', 'body', 'notes'].forEach( key => {
+			if ((key in params) && (typeof(params[key]) != 'string')) this.die("Web Hook " + key + " must be a string.");
+		});
+		if ('icon' in params) params.icon = params.icon.replace(/^mdi\-/, '');
+		if (('id' in params) && ((typeof(params.id) != 'string') || !params.id.match(/^[a-z0-9_]+$/))) {
+			this.die("Invalid Web Hook ID: " + params.id);
+		}
+		return params;
+	},
+	
+	validateWebHookHeaders(headers) {
+		if (!Array.isArray(headers)) this.die("Web Hook headers must be a JSON array.");
+		return headers.map( (header, idx) => {
+			if (!Tools.isaHash(header)) this.die("Web Hook headers." + idx + " must be a JSON object.");
+			var extra = Object.keys(header).find( key => !['name', 'value'].includes(key) );
+			if (extra) this.die("Unsupported property in Web Hook headers." + idx + ': "' + extra + '".');
+			if ((typeof(header.name) != 'string') || !header.name.match(/^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/)) {
+				this.die("Invalid HTTP header name in Web Hook headers." + idx + ".");
+			}
+			if ((typeof(header.value) != 'string') || !header.value.match(/^[\t\x20-\x7E\x80-\xFF]*$/)) {
+				this.die("Invalid HTTP header value in Web Hook headers." + idx + ".");
+			}
+			return { name: header.name, value: header.value };
+		});
+	},
+	
+	parseWebHookBoolean(value, name) {
+		if ([true, 1, '1', 'true', 'yes', 'on'].includes(value)) return true;
+		if ([false, 0, '0', 'false', 'no', 'off'].includes(value)) return false;
+		this.die("Invalid boolean value for '" + name + "': " + value);
+	},
+	
+	printWebHookMutationSummary(title, hook) {
+		this.printMutationSummary({
+			title: title,
+			rows: [
+				[ 'Hook ID', gray(hook.id) ],
+				[ 'Title', this.color('theme').bold(hook.title) ]
+			]
+		});
+	},
+	
+	printWebHookBody(body) {
+		println( "\n " + this.color('theme').bold('WEB HOOK BODY') );
+		if (!body) {
+			println( " " + gray('(Empty)') );
+			return;
+		}
+		
+		body = String(body).trim();
+		var language = '';
+		if (body.match(/^\{[\s\S]*\}$/) || body.match(/^\[[\s\S]*\]$/)) language = 'json';
+		
+		var source_lines = body.split(/\r?\n/).map( line => '    ' + line ).join("\n");
+		var highlight_opts = { ignoreIllegals: true };
+		if (language) highlight_opts.language = language;
+		
+		println( "\n" + this.highlight(source_lines, highlight_opts) );
+	}
+	
+}; // module.exports

package/package.json

@@ -0,0 +1,38 @@
+{
+	"name": "@pixlcore/xycli",
+	"version": "1.0.0",
+	"description": "A complete command-line interface for the xyOps workflow automation system.",
+	"author": "Joseph Huckaby <jhuckaby@pixlcore.com>",
+	"homepage": "https://github.com/pixlcore/xycli",
+	"license": "MIT",
+	"main": "index.js",
+	"bin": {
+		"xy": "index.js"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/pixlcore/xycli"
+	},
+	"bugs": {
+		"url": "https://github.com/pixlcore/xycli/issues"
+	},
+	"keywords": [
+		"xyops", "cli"
+	],
+	"scripts": {
+		"test": "node test.js"
+	},
+	"dependencies": {
+		"@pixlcore/xyops-sdk": "^1.0.7",
+		"cli-highlight": "2.1.11",
+		"diff": "9.0.0",
+		"pixl-cli": "^1.1.6",
+		"html-to-text": "10.0.1",
+		"marked": "15.0.12",
+		"marked-terminal": "7.3.0",
+		"uncatch": "^1.0.4"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/test/README.md

@@ -0,0 +1,97 @@
+# CLI Integration Tests
+
+These tests exercise the CLI against a running xyOps development server. They use Node.js's built-in test runner and the project's existing dependencies.
+
+## Setup
+
+Use Node.js 22 or newer and install the CLI dependencies with `npm install`.
+
+Start xyOps at `http://localhost:5522` and configure an administrator API key using your normal CLI config file or the `XYOPS_API_KEY` environment variable. The tests read the same configuration as `xy`, including `XYOPS_BASE_URL` overrides. They refuse to run against a different server address.
+
+Use an xyOps version that supports restoring API key IDs, hashes, and masks through `create_api_key`. The Server tests need a connected server, and the Monitor tests also need a server group. The log tests expect the standard log columns and debug entries in the current xyOps log.
+
+## Running Tests
+
+Run every suite, one at a time:
+
+```sh
+npm test
+```
+
+The equivalent controller command is:
+
+```sh
+node test.js
+```
+
+Run selected suites, or list the available names:
+
+```sh
+node test.js categories channels
+npm test -- transfer-apikey
+node test.js --list
+```
+
+The controller discovers `test/*.test.js`, uses a separate process for each suite, and sets native test concurrency to one. Do not run multiple controllers against the same server at once. Some checks compare the definitions before and after a test, so avoid editing server objects while the suite runs.
+
+You can also run one file directly and choose a native reporter:
+
+```sh
+node --test --test-reporter=spec test/monitors.test.js
+```
+
+The controller exits with a nonzero status if any suite fails. A failed lifecycle check stops the remaining dependent steps in that suite, runs cleanup, and allows the next suite to proceed.
+
+The configuration and sync unit suites run offline with disposable directories and do not contact xyOps. Run them directly without configuring a development server:
+
+```sh
+node --test test/config.test.js test/sync-unit.test.js
+```
+
+## Coverage
+
+| Suite | Coverage |
+| --- | --- |
+| `categories` | CRUD, actions and limits, JSON input, validation, pagination, help |
+| `channels` | CRUD, recipients, indexed edits, filters, validation, help |
+| `config` | Offline user-file updates, inherited-setting isolation, missing-file creation, dotted edits, permissions, and read-only display |
+| `log` | Log searches, latest rows, matching, column selection, native output |
+| `markdown` | Terminal rendering, inline formatting inside list items, typographic bullets, and output margins |
+| `monitors` | CRUD, groups, evaluator requests, type conversions, validation, help |
+| `marketplace` | Search, details, README rendering, install preview, confirmed install and upgrade, validation, help |
+| `pagination` | Pagination arguments, search requests, command variants, resource limits |
+| `plugins` | CRUD for all four Plugin types, parameters, groups, validation, help |
+| `secrets` | Vault metadata, assignments, redacted previews, full field replacement, confirmed decryption, deletion, validation, help |
+| `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, 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 |
+| `transfer` | All portable object types, preview and confirmation, dependencies, gzip, validation, partial failures |
+| `transfer-apikey` | Export, deletion, import, and authentication with the original plaintext secret |
+| `transfer-workflow` | Fresh workflow migration with shared dependencies |
+| `webhook` | CRUD, aliases, headers, exact body input, live Markdown test reports, sparse updates, validation, help |
+
+Pagination checks that require saved events, completed jobs, or alert history report a skip when those records are unavailable.
+
+## Fixtures and Cleanup
+
+The mutating suites create uniquely named disposable objects and remove them in cleanup blocks, including after assertion failures. Test events have no active triggers, channels are never invoked, monitor sources use constants, and Plugin definitions are never executed or attached to other objects. Temporary files live in private operating-system temp directories and are removed by native test hooks.
+
+The Marketplace suite installs and upgrades `pixlcore/xyplug-ai`, then deletes it without executing or attaching it to an Event. The suite requires this product to be uninstalled when the test begins and removes its own installation during cleanup. Ticket fixtures remain in `draft` for their entire lifecycle so assigned test users never receive email notifications.
+
+API key tests keep plaintext secrets in memory. Export files contain the stored hash and mask, and are deleted after the test. Captured CLI output is omitted from process failure messages because it can contain credentials.
+
+Secret Vault tests use uniquely generated disposable values. They verify sensitive values by digest wherever practical, ensure dry-run and verbose diagnostics are redacted, and delete the vault during cleanup. Confirmed decrypt checks intentionally exercise the audited API operation.
+
+A forced process termination or an unavailable server can prevent server cleanup. If a run is interrupted, check for its uniquely named `cli_*` fixtures before rerunning. The tests never remove unrelated objects.
+
+## Adding a Suite
+
+Add a CommonJS file named `test/NAME.test.js`. The controller will discover it automatically. Use `node:test` and `node:assert/strict`, and reuse `test/helpers/common.js` for configuration, CLI calls, temporary directories, and sequential lifecycle checks.
+
+Call `loadTestConfig()` before any server request. Register temporary directory cleanup immediately, and put mutations inside a `try` block with fixture cleanup in `finally`. Await each lifecycle check so dependent operations run in order.
+
+Keep helper modules under `test/helpers/`. The pagination preload records only method names and pagination fields at the SDK boundary; it does not record authentication or response data.