@pixlcore/xycli 1.0.0

package/test/markdown.test.js

@@ -0,0 +1,61 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const cli = require('pixl-cli');
+const utils = require('../lib/utils.js');
+
+test('markdown renders inline formatting inside list items', () => {
+	const output = utils.markdown([
+		'- **Node.js** and `npx`',
+		'\t- Nested **bold** and `code`'
+	].join('\n'));
+	const plain_text = cli.Tools.stripANSI(output);
+	
+	// Test the visible terminal text, regardless of whether the test runner was
+	// launched from a color-capable terminal.  The important regression check is
+	// that Markdown delimiters do not leak through from either list item.
+	assert.match(plain_text, /• Node\.js and npx/);
+	assert.match(plain_text, /• Nested bold and code/);
+	assert.doesNotMatch(plain_text, /\*\*|`/);
+});
+
+test('markdown uses typographic bullets without changing ordered lists', () => {
+	const output = utils.markdown([
+		'- First item',
+		'- Second item',
+		'',
+		'1. First numbered item',
+		'2. Second numbered item'
+	].join('\n'));
+	const plain_text = cli.Tools.stripANSI(output);
+
+	assert.match(plain_text, /• First item/);
+	assert.match(plain_text, /• Second item/);
+	assert.match(plain_text, /1\. First numbered item/);
+	assert.match(plain_text, /2\. Second numbered item/);
+	assert.doesNotMatch(plain_text, /^\s*\* /m);
+});
+
+test('markdown indents list levels by two spaces', () => {
+	const output = utils.markdown([
+		'- Parent item',
+		'    - Nested item'
+	].join('\n'));
+	const plain_text = cli.Tools.stripANSI(output);
+
+	// The first space is the global Markdown margin.  Each list level then
+	// contributes the configured two-space marked-terminal indentation.
+	assert.match(plain_text, /^ {3}• Parent item$/m);
+	assert.match(plain_text, /^ {5}• Nested item$/m);
+});
+
+test('markdown adds a left margin and reserves room for both sides', () => {
+	const output = utils.markdown('This is a deliberately long paragraph. '.repeat(12));
+	const terminalWidth = Math.min(process.stdout.columns || 80, 120);
+
+	// Every rendered line receives one visible leading space.  marked-terminal
+	// reflows against a width reduced by two, leaving the opposite margin free.
+	output.split('\n').forEach( line => {
+		assert.match(cli.Tools.stripANSI(line), /^ /);
+		assert.ok(cli.stringWidth(line) <= terminalWidth - 1);
+	});
+});

package/test/marketplace.test.js

@@ -0,0 +1,229 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { loadTestConfig, createCheck, xy, json, call: apiCall } = require('./helpers/common.js');
+
+test('marketplace', async t => {
+	loadTestConfig();
+	const check = createCheck(t);
+	const marketplaceID = 'pixlcore/xyplug-ai';
+	let original = [];
+	let cleanupAllowed = false;
+	let pluginID = '';
+	
+	try {
+		original = (await apiCall('getPlugins')).rows;
+		assert.ok(!original.some(plugin => plugin.marketplace && (plugin.marketplace.id == marketplaceID)),
+			marketplaceID + ' must be uninstalled before running this suite');
+		cleanupAllowed = true;
+		
+		await check('search by positional text', () => {
+			const rows = json(['marketplace', 'AI Generation', '--limit', '5']);
+			assert.ok(Array.isArray(rows));
+			assert.ok(rows.some(product => product.id == marketplaceID));
+			assert.ok(rows.every(product => product.type == 'plugin'));
+		});
+		
+		await check('search filters and descending sort', () => {
+			const rows = json([
+				'marketplace', '--query', 'AI', '--plugin_type', 'event',
+				'--author', 'pixl core', '--license', 'mit', '--requires', 'npx',
+				'--tags', 'AI', '--status', 'not', '--sort_by', 'modified',
+				'--sort_dir', 'desc', '--limit', '10'
+			]);
+			assert.ok(rows.some(product => product.id == marketplaceID));
+			assert.ok(rows.every(product => product.plugin_type == 'event'));
+		});
+		
+		await check('repeated list filters require all values', () => {
+			const rows = json(['marketplace', '--tags', 'AI', '--tags', 'Prompt', '--requires', 'npx']);
+			assert.ok(rows.some(product => product.id == marketplaceID));
+		});
+		
+		await check('human search pagination and suggestions', () => {
+			const out = xy(['marketplace', '--limit', '1']);
+			assert.match(out, /PLUGIN MARKETPLACE/);
+			assert.match(out, /page 1 of/i);
+			assert.match(out, /Other Commands:/);
+		});
+		
+		await check('README image cleanup preserves useful text and links', () => {
+			const clean = require('../lib/marketplace.js').cleanMarketplaceReadme([
+				'<p align="center"><img src="logo.png" alt="Logo"/></p>',
+				'<h1 align="center">Example Plugin</h1>',
+				'[![Version](badge.svg)](https://example.com/releases)',
+				'![Screenshot](screen.png)',
+				'\x1b[31mBody\x1b[0m'
+			].join('\n'));
+			assert.doesNotMatch(clean, /<img|!\[/i);
+			assert.doesNotMatch(clean, /\x1b/);
+			assert.match(clean, /^# Example Plugin/m);
+			assert.match(clean, /\[Version\]\(https:\/\/example\.com\/releases\)/);
+			assert.match(clean, /Body/);
+		});
+		
+		await check('JSON details include listing, version and original README', () => {
+			const detail = json(['marketplace', marketplaceID]);
+			assert.equal(detail.item.id, marketplaceID);
+			assert.equal(detail.item.type, 'plugin');
+			assert.equal(detail.item.plugin_type, 'event');
+			assert.equal(detail.version, detail.item.versions[0]);
+			assert.match(detail.text, /<img/i);
+			assert.match(detail.text, /Plugin Parameters/);
+		});
+		
+		await check('human details show summary and terminal-safe full README', () => {
+			const out = xy(['marketplace', 'get', marketplaceID]);
+			assert.match(out, /MARKETPLACE PLUGIN SUMMARY/);
+			assert.match(out, /PLUGIN README/);
+			assert.match(out, /AI Generation Plugin/);
+			assert.match(out, /Environment Variables/);
+			assert.match(out, /Not Installed/);
+			assert.doesNotMatch(out, /<img|!\[/i);
+		});
+		
+		const preview = json(['marketplace', 'install', marketplaceID, '--version', 'v1.0.9']);
+		pluginID = preview.plugin.id;
+		
+		await check('human install preview focuses on the Plugin definition', () => {
+			const out = xy(['marketplace', 'install', marketplaceID, '--version', 'v1.0.9']);
+			assert.match(out, /MARKETPLACE PLUGIN INSTALL PREVIEW/);
+			assert.match(out, /Plugin Name:\s+AI Generation/);
+			assert.match(out, /Author:\s+PixlCore/);
+			assert.match(out, /Version:\s+v1\.0\.9/);
+			assert.match(out, /This is the Plugin definition that will be created/);
+			assert.match(out, new RegExp('"id": "' + pluginID + '"'));
+			assert.match(out, /⚠️[\s\S]*Preview only\./);
+			assert.doesNotMatch(out, /"product":|"operation":|"preview": true|"warnings":/);
+		});
+		
+		await check('scripted preview extracts source without mutating Plugin data', () => {
+			const marketplace = require('../lib/marketplace.js');
+			const plugin = { id: 'sample', command: 'node', script: 'console.log("Hello");\n' };
+			const display = marketplace.prepareMarketplacePreviewPlugin(plugin);
+			assert.equal(display.script, plugin.script);
+			assert.ok(!('script' in display.plugin));
+			assert.equal(plugin.script, 'console.log("Hello");\n');
+		});
+		
+		await check('scripted Marketplace Plugin shows source below preview JSON', () => {
+			const out = xy(['marketplace', 'install', 'pixlcore/xyplug-upgrade']);
+			const script_pos = out.indexOf('PLUGIN SCRIPT');
+			assert.ok(script_pos > 0);
+			assert.doesNotMatch(out.slice(0, script_pos), /"script":/);
+			assert.match(out.slice(script_pos), /Auto Upgrade Plugin for xyOps/);
+			assert.match(out.slice(script_pos), /const fs = require\('fs'\);/);
+		});
+		
+		await check('install defaults to a complete create preview', () => {
+			assert.equal(preview.preview, true);
+			assert.equal(preview.operation, 'create');
+			assert.equal(preview.marketplace.id, marketplaceID);
+			assert.equal(preview.product.id, marketplaceID);
+			assert.equal(preview.version, 'v1.0.9');
+			assert.deepEqual(preview.warnings, []);
+			assert.deepEqual(preview.plugin.marketplace, { id: marketplaceID, version: 'v1.0.9' });
+			assert.equal(preview.plugin.type, 'event');
+			assert.ok(!('created' in preview.plugin));
+			assert.ok(!('modified' in preview.plugin));
+			assert.ok(!('revision' in preview.plugin));
+			assert.ok(!('username' in preview.plugin));
+			assert.ok(!('uid' in preview.plugin));
+			assert.ok(!('gid' in preview.plugin));
+		});
+		
+		await check('preview does not install Plugin', () => {
+			assert.deepEqual(json(['plugins', '--id', pluginID]), []);
+		});
+		
+		await check('false confirmation and dry confirmation remain previews', () => {
+			assert.equal(json(['marketplace', 'install', marketplaceID, '--confirm', 'false']).preview, true);
+			assert.equal(json(['marketplace', 'install', marketplaceID, '--confirm', '--dry']).preview, true);
+			assert.deepEqual(json(['plugins', '--id', pluginID]), []);
+		});
+		
+		const rejected = [
+			['get', 'invalid-id'],
+			['get', marketplaceID, '--unknown', 'x'],
+			['install'],
+			['install', marketplaceID, '--unknown', 'x'],
+			['install', marketplaceID, '--confirm', 'yes'],
+			['--plugin_type', 'bogus'],
+			['--status', 'outdated'],
+			['--sort_by', 'bogus'],
+			['--sort_dir', 'sideways'],
+			['--query', 'AI', 'extra search']
+		];
+		for (const args of rejected) {
+			await check('reject marketplace ' + args.join(' '), () => xy(['marketplace', ...args], { fail: true }));
+		}
+		
+		const installed = json(['marketplace', 'install', marketplaceID, '--version', 'v1.0.9', '--confirm']);
+		
+		await check('confirmed install creates selected Marketplace version', () => {
+			assert.equal(installed.operation, 'created');
+			assert.equal(installed.plugin.id, pluginID);
+			assert.equal(installed.plugin.marketplace.id, marketplaceID);
+			assert.equal(installed.plugin.marketplace.version, 'v1.0.9');
+			assert.match(installed.plugin.command, /1\.0\.9/);
+			assert.ok(!('uid' in installed.plugin));
+			assert.ok(!('gid' in installed.plugin));
+		});
+		
+		await check('installed product is reported as outdated', () => {
+			const rows = json(['marketplace', '--query', 'AI Generation', '--status', 'installed']);
+			assert.ok(rows.some(product => product.id == marketplaceID));
+			const out = xy(['marketplace', marketplaceID]);
+			assert.match(out, /Outdated/);
+			assert.match(out, new RegExp(pluginID));
+			assert.match(out, /v1\.0\.9/);
+		});
+		
+		const upgradePreview = json(['marketplace', 'install', marketplaceID]);
+		await check('latest installation previews an update', () => {
+			assert.equal(upgradePreview.operation, 'update');
+			assert.equal(upgradePreview.version, upgradePreview.product.versions[0]);
+			assert.equal(upgradePreview.plugin.id, pluginID);
+		});
+		
+		const upgraded = json(['marketplace', 'install', marketplaceID, '--confirm']);
+		await check('confirmed upgrade updates Plugin and Marketplace version', () => {
+			assert.equal(upgraded.operation, 'updated');
+			assert.equal(upgraded.plugin.id, pluginID);
+			assert.equal(upgraded.plugin.marketplace.version, upgraded.marketplace.version);
+			assert.equal(upgraded.plugin.marketplace.version, upgradePreview.product.versions[0]);
+			assert.match(upgraded.plugin.command, new RegExp(upgraded.marketplace.version.replace(/^v/, '').replace(/\./g, '\\.')));
+			assert.ok(upgraded.plugin.revision > installed.plugin.revision);
+		});
+		
+		await check('latest version is reported as up to date', () => {
+			assert.match(xy(['marketplace', marketplaceID]), /Up to Date/);
+			assert.match(xy(['plugin', pluginID]), /Marketplace/);
+		});
+		
+		json(['plugin', 'delete', pluginID, '--confirm']);
+		
+		await check('delete returns product to not-installed state', () => {
+			assert.deepEqual(json(['plugins', '--id', pluginID]), []);
+			const rows = json(['marketplace', '--query', 'AI Generation', '--status', 'not']);
+			assert.ok(rows.some(product => product.id == marketplaceID));
+		});
+		
+		for (const topic of ['marketplace', 'marketplace list', 'marketplace search', 'marketplace get', 'marketplace install']) {
+			await check('help ' + topic, () => assert.match(xy(['help', ...topic.split(' ')]), /Marketplace/i));
+		}
+		
+		await check('existing Plugins remain unchanged', async () => {
+			assert.deepEqual((await apiCall('getPlugins')).rows, original);
+		});
+	}
+	finally {
+		// Only clean up after confirming this product was absent at suite start.
+		// This catches failures after a successful create but before normal delete.
+		if (cleanupAllowed) {
+			const rows = (await apiCall('getPlugins')).rows.filter(plugin => {
+				return plugin.marketplace && (plugin.marketplace.id == marketplaceID);
+			});
+			for (const plugin of rows) await apiCall('deletePlugin', { id: plugin.id });
+		}
+	}
+});

package/test/monitors.test.js

@@ -0,0 +1,227 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const Path = require('node:path');
+const { loadTestConfig, createCheck, createTempDir, xy, json, call, call: apiCall, cleanupFixtures } = require('./helpers/common.js');
+
+test('monitors', async t => {
+	loadTestConfig();
+	const check = createCheck(t);
+	
+	// Disposable live lifecycle.  Use constant sources and remove every fixture.
+	const id = 'cli_monitor_test_' + Date.now();
+	const title = 'CLI Monitor Test ' + id;
+	const ids = new Set([id]);
+	const temp = createTempDir(t, 'xycli-monitor-test-');
+	try {
+		const original = (await apiCall('getMonitors')).rows;
+		const multi = await apiCall('getMultiple', { lists: 'all', servers: 1 });
+		const server = Object.values(multi.servers)[0];
+		const group = multi.groups[0];
+		assert.ok(server && group, 'Live server and group required');
+		
+		await check('dry create defaults and numeric constant', () => {
+			const req = json(['monitor', 'create', '--id', id, '--title', title, '--source', '0', '--dry']);
+			assert.equal(req.source, '0');
+			assert.equal(req.display, true);
+			assert.equal(req.data_type, 'float');
+			assert.equal(req.delta_min_value, false);
+			assert.deepEqual(req.groups, []);
+		});
+		
+		await check('dry create does not persist', () => assert.deepEqual(json(['monitors', '--id', id]), []));
+		
+		const created = json(['monitor', 'create', '--id', id, '--title', title, '--source', '12.5', '--display', 'false', '--groups', group.id, '--group', group.id, '--delta', 'true', '--divide_by_delta', 'true', '--delta_min_value', '0', '--min_vert_scale', '100', '--suffix', '/sec', '--icon', 'chart-line', '--notes', 'Hello']);
+		
+		await check('create persists configuration and deduplicates groups', () => {
+			assert.equal(created.id, id);
+			assert.equal(created.source, '12.5');
+			assert.equal(created.display, false);
+			assert.equal(created.delta, true);
+			assert.equal(created.divide_by_delta, true);
+			assert.equal(created.delta_min_value, 0);
+			assert.equal(created.min_vert_scale, 100);
+			assert.equal(created.suffix, '/sec');
+			assert.equal(created.notes, 'Hello');
+			assert.equal(created.icon, 'chart-line');
+			assert.equal(created.revision, 1);
+			assert.deepEqual(created.groups, [group.id]);
+		});
+		
+		await check('exact ID detail', () => assert.deepEqual(json(['monitor', id]), created));
+		
+		await check('fuzzy title detail', () => assert.equal(json(['monitor', 'get', '--title', title.toLowerCase()]).id, id));
+		
+		await check('named ID detail', () => assert.equal(json(['monitor', 'get', '--id', id]).id, id));
+		
+		await check('combined filters', () => assert.deepEqual(json(['monitors', title, '--display', 'false', '--delta', 'true', '--divide_by_delta', 'true', '--data_type', 'float']), [created]));
+		
+		await check('group title lookup', () => assert.equal(json(['monitors', title, '--group', group.title]).length, 1));
+		
+		await check('JSON list ignores pagination as filters', () => assert.deepEqual(json(['monitor', 'list', '--id', id, '--limit', '1', '--page', '2']), [created]));
+		
+		await check('human pagination and suggestions', () => {
+			const out = xy(['monitors', '--limit', '1', '--page', '2']);
+			assert.match(out, /page 2 of/);
+			assert.match(out, /Other Commands:/);
+		});
+		
+		await check('empty filtered table', () => assert.match(xy(['monitors', title, '--display', 'true']), /No filtered monitors found/));
+		
+		await check('human detail includes all settings', () => {
+			const out = xy(['monitor', id]);
+			fs.writeFileSync(Path.join(temp, 'detail.txt'), out);
+			for (const label of ['Monitor Summary', 'Hidden', 'Source', 'Data Match', 'Delta Min', 'Sort Order', 'Revision', 'Monitor Notes', 'Hello']) assert.ok(out.toLowerCase().includes(label.toLowerCase()), label);
+		});
+		
+		await check('human update shows target and parsed data', () => {
+			const out = xy(['monitor', 'update', id, '--notes', 'Preview', '--dry']);
+			assert.match(out, /UPDATE MONITOR/);
+			assert.match(out, new RegExp('Monitor ID:\\s+' + id));
+			assert.match(out, /UPDATE DATA[\s\S]*"notes": "Preview"/);
+		});
+		
+		await check('sparse dry update', () => assert.deepEqual(json(['monitor', 'update', id, '--notes', 'Preview', '--dry']), { notes: 'Preview', id }));
+		
+		await check('dry update leaves revision', () => assert.equal(json(['monitor', id]).revision, 1));
+		
+		await check('saved test returns absolute value despite delta settings', () => assert.deepEqual(json(['monitor', 'test', id, '--server', server.id]), { code: 0, value: 12.5 }));
+		
+		await check('test fuzzy monitor and server lookup', () => assert.equal(json(['monitor', 'test', title.toLowerCase(), '--server', server.title || server.hostname]).value, 12.5));
+		
+		await check('test zero success', () => assert.deepEqual(json(['monitor', 'test', '--id', id, '--server', server.id, '--source', '0']), { code: 0, value: 0 }));
+		
+		await check('test unresolved expression', () => assert.deepEqual(json(['monitor', 'test', '--server', server.id, '--source', 'missing_monitor_test_field']), { code: 0, fail: true }));
+		
+		await check('human No Value', () => assert.match(xy(['monitor', 'test', '--server', server.id, '--source', 'missing_monitor_test_field']), /No Value/));
+		
+		for (const type of ['integer', 'float', 'bytes', 'seconds', 'milliseconds']) {
+			await check('test type conversion ' + type, () => assert.equal(json(['monitor', 'test', '--server', server.id, '--source', '12.75', '--data_type', type]).value, type === 'float' ? 12.75 : 12));
+		}
+		
+		await check('human bytes formatting', () => assert.match(xy(['monitor', 'test', '--server', server.id, '--source', '2048', '--data_type', 'bytes']), /2 K/));
+		
+		await check('regex first capture', () => assert.equal(json(['monitor', 'test', '--server', server.id, '--source', '"42 workers"', '--data_match', '(\\d+)', '--data_type', 'integer']).value, 42));
+		
+		await check('regex full match', () => assert.equal(json(['monitor', 'test', '--server', server.id, '--source', '"42 workers"', '--data_match', '\\d+']).value, 42));
+		
+		await check('test dry request includes only evaluator fields', () => assert.deepEqual(json(['monitor', 'test', id, '--server', server.id, '--dry']), { source: '12.5', data_type: 'float', data_match: '', server: server.id }));
+		
+		await check('test overrides do not change saved definition', () => assert.deepEqual(json(['monitor', id]), created));
+		
+		json(['monitor', 'update', '--id', id, '--json', '@-'], { input: JSON.stringify({ display: true, delta_min_value: false, notes: 'From stdin' }) });
+		
+		await check('stdin sparse update and disabled minimum', () => {
+			const row = json(['monitor', id]);
+			assert.equal(row.display, true);
+			assert.equal(row.delta_min_value, false);
+			assert.equal(row.notes, 'From stdin');
+			assert.equal(row.source, created.source);
+			assert.equal(row.created, created.created);
+			assert.equal(row.revision, 2);
+		});
+		
+		// Group assignments use IDs; extra IDs are only temporary test definitions.
+		json(['monitor', 'update', id, '--groups.0', group.id, '--groups', '["first","second"]', '--group', 'third', '--group', group.id]);
+		
+		await check('replacement before indexed edits and append', () => assert.deepEqual(json(['monitor', id]).groups, [group.id, 'second', 'third']));
+		
+		const groupFile = Path.join(temp, 'groups.json');
+		fs.writeFileSync(groupFile, JSON.stringify([group.id]));
+		json(['monitor', 'update', id, '--groups', '@' + groupFile]);
+		
+		await check('groups from file', () => assert.deepEqual(json(['monitor', id]).groups, [group.id]));
+		
+		json(['monitor', 'update', id, '--groups', '[]', '--suffix', '', '--notes', '', '--data_match', '', '--json', '@-'], { input: JSON.stringify({ delta_min_value: -5, sort_order: -1 }) });
+		
+		await check('clearing settings, numeric minimum and ordering', () => {
+			const row = json(['monitor', id]);
+			assert.deepEqual(row.groups, []);
+			assert.equal(row.suffix, '');
+			assert.equal(row.notes, '');
+			assert.equal(row.delta_min_value, -5);
+			assert.equal(json(['monitors'])[0].id, id);
+		});
+		
+		await check('all-group monitors included in group filter', () => assert.equal(json(['monitors', title, '--group', group.id]).length, 1));
+		
+		const revision = json(['monitor', id]).revision;
+		await check('unconfirmed delete shows target and warning toast', () => {
+			for (const args of [['delete', id], ['delete', id, '--confirm', 'false']]) {
+				const out = xy(['monitor', ...args]);
+				assert.match(out, /DELETE MONITOR/);
+				assert.match(out, /⚠️[\s\S]*Please confirm the monitor delete/);
+			}
+		});
+		
+		for (const args of [
+			['update', id, '--groups.99', group.id], ['update', id, '--groups.__proto__.x', 'bad'],
+			['update', id, '--groups', '{}'], ['update', id, '--groups', '[5]'], ['update', id, '--group', ''],
+			['update', id, '--title', ' '], ['update', id, '--source', ''], ['update', id, '--source', 'cpu.('],
+			['update', id, '--display', 'perhaps'], ['update', id, '--delta_min_value', 'true'],
+			['update', id, '--sort_order', '1.5'], ['update', id, '--data_type', 'string'], ['update', id, '--data_match', '['],
+			['update', id, '--revision', '99'], ['update', id, '--enabled', 'false'], ['update', id],
+			['update', title, '--notes', 'wrong'], ['update', id, '--id', 'cpu_usage', '--notes', 'wrong'],
+			['delete', title, '--confirm'],
+			['create', '--title', title], ['create', '--title', title, '--source', 'cpu.('],
+			['test', id], ['test', '--server', server.id], ['test', id, '--server', 'missing_test_server'],
+			['test', id, '--server', server.id, '--source', 'cpu.('],
+			['test', id, '--server', server.id, '--data_match', 'never_matches'],
+			['test', id, '--server', server.id, '--delta', 'true']
+		]) await check('reject ' + args.slice(0,3).join(' '), () => xy(['monitor', ...args], { fail: true }));
+		
+		await check('reject negative chart range', () => xy(['monitor', 'update', id, '--json', '@-'], { input: '{"min_vert_scale":-1}', fail: true }));
+		
+		await check('rejected requests preserve revision', () => assert.equal(json(['monitor', id]).revision, revision));
+		
+		await check('duplicate ID error', () => assert.match(xy(['monitor', 'create', '--id', id, '--title', title, '--source', '0'], { fail: true }), /already exists/));
+		
+		const reqFile = Path.join(temp, 'monitor.json');
+		fs.writeFileSync(reqFile, JSON.stringify({ title: title + ' file', source: '0', data_type: 'integer', display: false }));
+		const imported = json(['monitor', 'create', '--json', '@' + reqFile]);
+		ids.add(imported.id);
+		
+		await check('file create with auto ID and integer defaults', () => {
+			assert.match(imported.id, /^m/);
+			assert.equal(imported.min_vert_scale, 1);
+			assert.equal(imported.display, false);
+		});
+		
+		const humanID = id + '_human';
+		ids.add(humanID);
+		
+		await check('human creation suggestions', () => assert.match(xy(['monitor', 'create', '--id', humanID, '--title', title, '--source', '0', '--display', 'false']), /Other Commands:/));
+		
+		for (const monitorID of Array.from(ids)) {
+			if (monitorID === id) continue;
+			json(['monitor', 'delete', monitorID, '--confirm']);
+			ids.delete(monitorID);
+		}
+		
+		await check('dry delete request', () => assert.deepEqual(json(['monitor', 'delete', id, '--confirm', '--dry']), { id }));
+		
+		await check('dry delete leaves monitor', () => assert.equal(json(['monitor', id]).id, id));
+		
+		json(['monitor', 'delete', id, '--confirm']);
+		ids.delete(id);
+		
+		await check('delete removes monitor', () => assert.deepEqual(json(['monitors', '--id', id]), []));
+		
+		await check('get after delete fails', () => xy(['monitor', id], { fail: true }));
+		
+		for (const topic of ['monitors', 'monitor', 'monitor list', 'monitor get', 'monitor create', 'monitor update', 'monitor test', 'monitor delete']) {
+			await check('help ' + topic, () => assert.ok(xy(['help', ...topic.split(' ')]).length > 100));
+		}
+		
+		await check('existing monitors remain unchanged', () => {
+			const now = json(['monitors']);
+			assert.equal(now.length, original.length);
+			for (const monitor of original) assert.deepEqual(now.find(item => item.id === monitor.id), monitor);
+		});
+	}
+	finally {
+		await cleanupFixtures([
+			{ list: 'monitors', method: 'deleteMonitor', match: item => ids.has(item.id) || item.title.startsWith(title) }
+		]);
+	}
+});

package/test/pagination.test.js

@@ -0,0 +1,138 @@
+const { test } = require('node:test');
+const fs = require('node:fs');
+const Path = require('node:path');
+const assert = require('node:assert/strict');
+const { loadTestConfig, createCheck, createTempDir, runCLI } = require('./helpers/common.js');
+
+test('pagination', async t => {
+	loadTestConfig();
+	const check = createCheck(t);
+	
+	// End-to-end, read-only checks for search pagination and mutation dry runs.
+	const traceFile = Path.join(createTempDir(t, 'xycli-page-test-'), 'trace.jsonl');
+	
+	function run(args) {
+		fs.writeFileSync(traceFile, '');
+		const output = runCLI(args, {
+			preload: Path.join(__dirname, 'helpers/pagination-preload.cjs'),
+			env: { XYOPS_SUGGEST: 'false', XYCLI_PAGINATION_TRACE: traceFile }
+		});
+		
+		const trace = fs.readFileSync(traceFile, 'utf8').trim().split('\n').filter(Boolean).map(line => JSON.parse(line));
+		return { output, trace };
+	}
+	
+	function json(args) {
+		const result = run([...args, '--format', 'jsonc']);
+		return JSON.parse(result.output.split('\n').find(line => /^[\[{]/.test(line)));
+	}
+	
+	function search(args, method, offset = 2, limit = 2) {
+		const result = run([...args, '--limit', String(limit), '--page', '2']);
+		const call = result.trace.find(row => row.method === method);
+		assert.ok(call, JSON.stringify(result.trace));
+		assert.equal(call.offset, offset);
+		assert.equal(call.limit, limit);
+		assert.ok(!call.query || !/\b(limit|offset|page):/.test(call.query), call.query);
+		return result;
+	}
+	
+	for (const command of ['categories', 'buckets', 'keys', 'alerts']) {
+		await check(command + ' pagination stays out of local filters', () => {
+			const base = json([command]);
+			assert.deepEqual(json([command, '--limit', '1', '--page', '2']), base);
+			const result = run([command, '--limit', '1', '--page', '2']);
+			assert.ok(!result.output.includes('FILTERED'), result.output);
+			if (base.length > 1) assert.match(result.output, /page 2 of/);
+		});
+	}
+	
+	await check('jobs search page arithmetic and query isolation', () => search(['jobs'], 'searchJobs'));
+	
+	await check('jobs explicit offset', () => {
+		const result = run(['jobs', '--limit', '3', '--offset', '4']);
+		assert.deepEqual(result.trace.find(row => row.method === 'searchJobs'), { method: 'searchJobs', query: '*', offset: 4, limit: 3 });
+	});
+	
+	await check('page takes precedence over offset', () => search(['jobs', '--offset', '80'], 'searchJobs'));
+	
+	await check('alert search pagination and query isolation', () => search(['alerts', 'search'], 'searchAlerts'));
+	
+	await check('singular alert search alias', () => search(['alert', 'search'], 'searchAlerts'));
+	
+	const events = json(['events']);
+	const event = events.find(event => !event.workflow) || events[0];
+	
+	if (event) {
+		await check('event completed variant', () => search(['event', event.id, '--completed'], 'searchJobs'));
+		
+		await check('event queued variant', () => search(['event', event.id, '--queued'], 'getActiveJobs'));
+		
+		await check('event queue alias', () => search(['event', event.id, '--queue'], 'getActiveJobs'));
+	}
+	else await t.test('event detail pagination', { skip: 'No saved events on this server.' }, () => {});
+	
+	const upcoming = [['dashboard', '--upcoming'], ['dashboard', 'upcoming'], ['upcoming'], ['jobs', '--upcoming'], ['jobs', 'upcoming']];
+	if (event) upcoming.push(['event', event.id, '--upcoming']);
+	
+	for (const args of upcoming) {
+		await check(args.join(' ') + ' paginates predictions', () => {
+			const result = run([...args, '--limit', '1', '--page', '2']);
+			assert.match(result.output, /UPCOMING JOBS/);
+			const section = result.output.slice(result.output.indexOf('UPCOMING JOBS'));
+			if (section.includes('items found')) assert.match(section, /page 2 of/);
+		});
+	}
+	
+	const jobRows = (() => {
+		const result = run(['api', 'searchJobs', '--query', '*', '--limit', '1', '--offset', '0', '--format', 'jsonc']);
+		const lines = result.output.split('\n').filter(line => line.startsWith('{'));
+		return JSON.parse(lines[lines.length - 1]).rows;
+	})();
+	if (jobRows.length) {
+		await check('job details paginate every related search', () => {
+			const result = run(['job', jobRows[0].id, '--limit', '2', '--page', '2']);
+			for (const method of ['searchAlerts', 'searchSnapshots']) {
+				const call = result.trace.find(row => row.method === method);
+				assert.equal(call.offset, 2);
+				assert.equal(call.limit, 2);
+			}
+		});
+	}
+	else await t.test('job detail pagination', { skip: 'No completed jobs on this server.' }, () => {});
+	
+	const invocations = json(['alerts', 'search', '--limit', '1']);
+	if (invocations.length) {
+		await check('alert invocation details prepare related-record pagination', () => {
+			const result = run(['alert', invocations[0].id, '--limit', '2', '--page', '2']);
+			const call = result.trace.find(row => row.method === 'searchSnapshots');
+			
+			// Alert detail intentionally anchors embedded sections at offset zero.
+			assert.equal(call.offset, 0);
+			assert.equal(call.limit, 2);
+		});
+	}
+	else await t.test('alert invocation pagination', { skip: 'No alert history on this server.' }, () => {});
+	
+	await check('generic API retains raw pagination properties', () => {
+		const payload = json(['api', 'searchJobs', '--offset', '7', '--limit', '3', '--page', '4', '--dry']);
+		assert.deepEqual(payload, { offset: 7, limit: 3, page: 4 });
+	});
+	
+	const resourceLimit = { type: 'time', enabled: true, duration: 300 };
+	for (const command of ['category', 'event']) {
+		await check(command + ' resource limit survives creation', () => {
+			const payload = json([command, 'create', '--title', 'Pagination dry test', '--limit', JSON.stringify(resourceLimit), '--dry']);
+			assert.ok(payload.limits.some(item => item.duration === 300));
+		});
+	}
+	
+	await check('mutation pagination properties reach CRUD validation', () => {
+		for (const [key, value] of [['offset', '7'], ['page', '3']]) {
+			const output = runCLI(['event', 'create', '--title', 'Pagination dry test', '--' + key, value, '--dry'], { fail: true });
+			assert.match(output, new RegExp('Unsupported property for create_event: "' + key + '"'));
+		}
+	});
+	
+	await check('category color remains a resource property', () => assert.equal(json(['category', 'create', '--title', 'Color dry test', '--color', 'blue', '--dry']).color, 'blue'));
+});