@pixlcore/xycli 1.0.0

package/test/config.test.js

@@ -0,0 +1,96 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const Path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+function createConfigFixture(t, initial) {
+	// Give each CLI process a disposable home directory.  Config commands exit
+	// before contacting xyOps, so these checks need no development server.
+	const home_dir = fs.mkdtempSync(Path.join(os.tmpdir(), 'xycli-config-'));
+	t.after(() => fs.rmSync(home_dir, { recursive: true, force: true }));
+	const file = Path.join(home_dir, '.config', 'xyops', 'cli.json');
+	
+	if (initial) {
+		fs.mkdirSync(Path.dirname(file), { recursive: true });
+		fs.writeFileSync(file, JSON.stringify(initial, null, '\t') + '\n');
+	}
+	
+	return {
+		file,
+		run(args) {
+			const result = spawnSync(process.execPath, [Path.join(__dirname, '..', 'index.js'), 'config', ...args], {
+				encoding: 'utf8',
+				timeout: 10000,
+				env: {
+					...process.env,
+					HOME: home_dir,
+					XYOPS_API_KEY: 'fixture-key',
+					XYOPS_BASE_URL: 'https://fixture.invalid',
+					XYOPS_ITEMS_PER_PAGE: '99',
+					XYOPS_COLOR: 'false'
+				}
+			});
+			
+			// Keep captured CLI output out of assertion messages, since a config
+			// command may display settings inherited from the real system file.
+			assert.ifError(result.error);
+			assert.equal(result.status, 0, 'Config command should succeed');
+			return result.stdout;
+		},
+		read() { return JSON.parse(fs.readFileSync(file, 'utf8')); }
+	};
+}
+
+test('config updates only requested user settings without saving inherited overrides', t => {
+	const fixture = createConfigFixture(t, {
+		items_per_page: 10,
+		base_url: 'https://saved.invalid',
+		suggest: true,
+		sync: { up: ['events'], down: false }
+	});
+	fixture.run(['--items_per_page', '25']);
+	
+	// The environment deliberately conflicts with saved values.  Saving one
+	// preference must preserve the original user layer and exclude inherited
+	// credentials, display settings, and any machine-wide configuration.
+	assert.deepEqual(fixture.read(), {
+		items_per_page: 25,
+		base_url: 'https://saved.invalid',
+		suggest: true,
+		sync: { up: ['events'], down: false }
+	});
+	assert.equal(fs.statSync(fixture.file).mode & 0o777, 0o600);
+});
+
+test('config creates a missing user file with only supplied settings', t => {
+	const fixture = createConfigFixture(t);
+	fixture.run(['--items_per_page', '25']);
+	
+	assert.deepEqual(fixture.read(), { items_per_page: 25 });
+	assert.equal(fs.statSync(fixture.file).mode & 0o777, 0o600);
+});
+
+test('config dotted updates preserve sibling user settings and explicit false or zero values', t => {
+	const fixture = createConfigFixture(t, {
+		sync: { up: ['events'], down: ['plugins'], error_email: 'ops@example.com' },
+		suggest: true
+	});
+	fixture.run(['--sync.down', 'false', '--sync.cmd_timeout', '0', '--suggest', 'false']);
+	
+	assert.deepEqual(fixture.read(), {
+		sync: { up: ['events'], down: false, error_email: 'ops@example.com', cmd_timeout: 0 },
+		suggest: false
+	});
+});
+
+test('config display shows effective environment overrides without writing the user file', t => {
+	const fixture = createConfigFixture(t, { items_per_page: 10 });
+	const original = fs.readFileSync(fixture.file, 'utf8');
+	const output = fixture.run([]);
+	
+	assert.match(output, /"items_per_page": 99/);
+	assert.doesNotMatch(output, /fixture-key/);
+	assert.equal(fs.readFileSync(fixture.file, 'utf8'), original);
+});

package/test/doc.test.js

@@ -0,0 +1,84 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const doc = require('../lib/doc.js');
+const utils = require('../lib/utils.js');
+const { loadTestConfig, xy } = require('./helpers/common.js');
+
+function createDocContext() {
+	return {
+		...utils,
+		...doc,
+		die(message) { throw new Error(message); }
+	};
+}
+
+test('documentation chapter extraction includes descendants and ignores code fences', () => {
+	const context = createDocContext();
+	const markdown = [
+		'# Example',
+		'## Selected Chapter',
+		'Chapter introduction.',
+		'### Child Section',
+		'Child text.',
+		'```md',
+		'## Not A Real Heading',
+		'```',
+		'#### Grandchild Section',
+		'Grandchild text.',
+		'## Next Chapter',
+		'Excluded text.'
+	].join('\n');
+	const selected = context.extractDocChapter(markdown, 'example', 'selected-chapter');
+	
+	assert.match(selected, /^## Selected Chapter/);
+	assert.match(selected, /### Child Section/);
+	assert.match(selected, /## Not A Real Heading/);
+	assert.match(selected, /#### Grandchild Section/);
+	assert.doesNotMatch(selected, /## Next Chapter|Excluded text/);
+});
+
+test('internal documentation links become copyable doc commands', () => {
+	const context = createDocContext();
+	const markdown = [
+		'[Plugins](plugins.md), [Output](#output-data), and [Website](https://example.com).',
+		'```md',
+		'[Example Link](example.md)',
+		'```'
+	].join('\n');
+	const prepared = context.prepareDocMarkdown(markdown, 'events');
+	
+	assert.match(prepared, /Plugins \(`xy doc plugins`\)/);
+	assert.match(prepared, /Output \(`xy doc events\/output-data`\)/);
+	assert.match(prepared, /\[Website\]\(https:\/\/example\.com\)/);
+	assert.match(prepared, /\[Example Link\]\(example\.md\)/);
+});
+
+test('doc command renders the index, full documents, and slash or space chapters', () => {
+	loadTestConfig();
+	const index = xy(['doc']);
+	const full = xy(['doc', 'plugins']);
+	const slash = xy(['doc', 'plugins/output-data']);
+	const space = xy(['doc', 'plugins', 'output-data']);
+	
+	assert.match(index, /Documentation Index/i);
+	assert.match(index, /xy doc plugins/);
+	assert.match(full, /Plugins/i);
+	assert.match(full, /Plugin Types/i);
+	assert.match(slash, /Output Data/i);
+	assert.match(slash, /arbitrary data output/i);
+	assert.doesNotMatch(slash, /Output Files/i);
+	assert.match(space, /Output Data/i);
+	assert.match(space, /arbitrary data output/i);
+});
+
+test('doc command rejects unsafe names, missing chapters, and search', () => {
+	loadTestConfig();
+	assert.match(xy(['doc', '../plugins'], { fail: true }), /Invalid documentation name/);
+	assert.match(xy(['doc', 'plugins/not-a-real-chapter'], { fail: true }), /Could not find documentation chapter/);
+	assert.match(xy(['doc', 'search'], { fail: true }), /Documentation search is not supported/);
+});
+
+test('doc help chapter renders', () => {
+	loadTestConfig();
+	assert.match(xy(['help', 'doc']), /HELP: DOC/);
+});

package/test/groups.test.js

@@ -0,0 +1,211 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { loadTestConfig, createCheck, xy, json, call, cleanupFixtures } = require('./helpers/common.js');
+
+test('groups', async t => {
+	loadTestConfig();
+	const check = createCheck(t);
+	const id = 'cli_group_test_' + Date.now();
+	const title = 'CLI Group Test ' + id;
+	const groups = new Set([id]);
+	
+	try {
+		const action = {
+			type: 'web_hook',
+			enabled: true,
+			condition: 'alert_new',
+			web_hook: 'example_hook',
+			text: ''
+		};
+		let preview = json(['group', 'create', '--id', id, '--title', title, '--max_jobs_per_server', '2', '--action', JSON.stringify(action), '--dry']);
+		
+		await check('dry create applies defaults and action syntax', () => {
+			assert.equal(preview.id, id);
+			assert.equal(preview.hostname_match, '(?!)');
+			assert.equal(preview.max_jobs_per_server, 2);
+			assert.deepEqual(preview.alert_actions, [action]);
+		});
+		
+		await check('dry create makes no Group', () => assert.equal(json(['groups', '--id', id]).length, 0));
+		
+		const created = json([
+			'group', 'create', '--id', id, '--title', title,
+			'--hostname_match', '^cli-group-no-server$', '--icon', 'mdi-server-network',
+			'--notes', 'Hello Group', '--max_jobs_per_server', '3', '--action', JSON.stringify(action)
+		]);
+		
+		await check('create persists the complete Group definition', () => {
+			assert.equal(created.id, id);
+			assert.equal(created.title, title);
+			assert.equal(created.hostname_match, '^cli-group-no-server$');
+			assert.equal(created.icon, 'server-network');
+			assert.equal(created.notes, 'Hello Group');
+			assert.equal(created.max_jobs_per_server, 3);
+			assert.deepEqual(created.alert_actions, [action]);
+		});
+		
+		await check('list supports positional and named filters', () => {
+			assert.equal(json(['groups', title]).length, 1);
+			assert.equal(json(['groups', '--hostname_match', 'no-server']).length, 1);
+			assert.equal(json(['group', 'list', '--id', id]).length, 1);
+		});
+		
+		await check('detail accepts an exact ID and fuzzy title', () => {
+			assert.equal(json(['group', id]).group.id, id);
+			assert.equal(json(['group', 'get', title.toLowerCase()]).group.id, id);
+		});
+		
+		await check('human detail renders the stable sections and expansion hints', () => {
+			const output = xy(['group', id]);
+			assert.match(output, /LIVE GROUP VIEW - Real-time/);
+			assert.match(output, /GROUP SUMMARY/);
+			assert.match(output, /GROUP NOTES[\s\S]*Hello Group/);
+			assert.match(output, /GROUP SERVERS/);
+			assert.match(output, /GROUP JOBS/);
+			assert.match(output, /GROUP MONITORS\n \(Shown in verbose mode, or add --monitors\.\)/);
+			assert.match(output, /GROUP PROCESSES\n \(Shown in verbose mode, or add --processes\.\)/);
+			assert.match(output, /GROUP NETWORK CONNECTIONS\n \(Shown in verbose mode, or add --connections\.\)/);
+		});
+		
+		json(['group', 'update', id, '--title', title + ' Updated', '--hostname_match', '', '--alert_actions.0.enabled', 'false', '--max_jobs_per_server', '4']);
+		let updated = (await call('getGroup', { id })).group;
+		
+		await check('update preserves untouched fields and supports dotted actions', () => {
+			assert.equal(updated.title, title + ' Updated');
+			assert.equal(updated.hostname_match, '(?!)');
+			assert.equal(updated.max_jobs_per_server, 4);
+			assert.equal(updated.alert_actions[0].enabled, false);
+			assert.equal(updated.notes, 'Hello Group');
+		});
+		
+		json(['group', 'update', id, '--action', JSON.stringify({ ...action, enabled: false })]);
+		updated = (await call('getGroup', { id })).group;
+		
+		await check('singular action appends to the saved array', () => assert.equal(updated.alert_actions.length, 2));
+		
+		for (const args of [
+			['update', id, '--alert_actions.99.enabled', 'true'],
+			['update', id, '--alert_actions.0.__proto__.polluted', 'true'],
+			['update', id, '--hostname_match', '['],
+			['update', id, '--max_jobs_per_server', '-1'],
+			['update', id, '--alert_actions', '{}'],
+			['update', id, '--unknown', 'value'],
+			['update', title, '--notes', 'Wrong target'],
+			['update', id],
+			['delete', title, '--confirm']
+		]) {
+			await check('reject ' + args.slice(0, 3).join(' '), () => xy(['group', ...args], { fail: true }));
+		}
+		
+		await check('unconfirmed deletion shows the selected Group', () => {
+			const output = xy(['group', 'delete', id]);
+			assert.match(output, /DELETE SERVER GROUP/);
+			assert.match(output, new RegExp('Group ID:\\s+' + id));
+			assert.match(output, /Please confirm the server group delete/);
+		});
+		
+		json(['group', 'delete', id, '--confirm', '--dry']);
+		await check('dry deletion preserves the Group', async () => assert.equal((await call('getGroup', { id })).group.id, id));
+		
+		json(['group', 'delete', id, '--confirm']);
+		groups.delete(id);
+		await check('confirmed deletion removes the Group', () => assert.equal(json(['groups', '--id', id]).length, 0));
+		
+		// The built-in main Group exercises the combined monitoring views without
+		// mutating any Server assignments or monitoring records.
+		const multiple = await call('getMultiple', {
+			lists: ['groups', 'monitors'],
+			jobs: 1,
+			alerts: 1,
+			servers: 1,
+			serverCache: 1
+		});
+		const group = multiple.groups.find(item => item.id == 'main') || multiple.groups.find(item => {
+			return Object.values(multiple.servers || {}).some(server => (server.groups || []).includes(item.id));
+		});
+		assert.ok(group, 'Group tests require a Group with connected Servers');
+		const active = Object.values(multiple.servers || {}).filter(server => (server.groups || []).includes(group.id));
+		assert.ok(active.length, 'Group tests require connected Group members');
+		
+		await check('live view loads one snapshot and timeline per selected Server', () => {
+			const result = json(['group', group.id]);
+			assert.equal(result.group.id, group.id);
+			assert.equal(result.merge, 'average');
+			assert.equal(result.snapshots.length, result.servers.length);
+			assert.ok(result.snapshots.length >= active.length);
+			assert.ok(result.snapshots.every(item => item.data && item.data.memory && Array.isArray(item.rows)));
+		});
+		
+		await check('live view applies Server filters before loading and normalizes merge aliases', () => {
+			const server = active[0];
+			const ip = String((server.info && server.info.ip) || server.ip || '');
+			const partial = ip.slice(0, Math.max(1, Math.floor(ip.length / 2)));
+			const result = json(['group', group.id, '--ip', partial, '--merge', 'max']);
+			assert.equal(result.merge, 'maximum');
+			assert.ok(result.servers.length);
+			assert.ok(result.servers.every(item => String((item.info && item.info.ip) || item.ip || '').includes(partial)));
+			assert.equal(result.snapshots.length, result.servers.length);
+		});
+		
+		await check('live human view renders merged charts, detail tables, and opt-in sections', () => {
+			const output = xy(['group', group.id, '--monitors', '--processes', '--connections', '--merge', 'avg', '--limit', '1']);
+			assert.match(output, /GROUP SERVERS/);
+			assert.match(output, /GROUP QUICK LOOK - LAST MINUTE/);
+			assert.match(output, /Average CPU Load/);
+			assert.match(output, /AVERAGE GROUP MEMORY DETAILS/);
+			assert.match(output, /AVERAGE GROUP CPU DETAILS/);
+			assert.match(output, /GROUP MONITORS - LAST HOUR/);
+			assert.match(output, /GROUP PROCESSES/);
+			assert.match(output, /GROUP NETWORK CONNECTIONS/);
+			assert.doesNotMatch(output, /Shown in verbose mode/);
+		});
+		
+		await check('live view rejects invalid merge modes and misspelled options', () => {
+			assert.match(xy(['group', group.id, '--merge', 'median'], { fail: true }), /Group --merge must be one of/);
+			const option = xy(['group', group.id, '--proceses'], { fail: true });
+			assert.match(option, /Unsupported group view option: "--proceses"/);
+			assert.match(option, /Did you mean "--processes"\?/);
+		});
+		
+		const latest = await call('getLatestMonitorData', { server: active[0].id, sys: 'hourly', limit: 1 });
+		assert.ok(latest.rows && latest.rows.length, 'Group history tests require recent monitoring data');
+		const history_date = new Date(latest.rows[latest.rows.length - 1].date * 1000);
+		const pad = number => String(number).padStart(2, '0');
+		const history_spec = history_date.getFullYear() + '/' + pad(history_date.getMonth() + 1) + '/' + pad(history_date.getDate()) + '/' + pad(history_date.getHours());
+		
+		await check('historical view reconstructs membership and loads every Monitor timeline', () => {
+			const result = json(['group', 'history', group.id, history_spec, '--merge', 'total', '--limit', '1']);
+			assert.equal(result.group.id, group.id);
+			assert.equal(result.merge, 'total');
+			assert.equal(result.range.mode, 'hourly');
+			assert.ok(result.servers.length >= active.length);
+			assert.equal(result.monitors.length, result.servers.length);
+			assert.ok(result.monitors.every(item => Array.isArray(item.rows)));
+			assert.ok(Array.isArray(result.alerts.rows));
+			assert.ok(Array.isArray(result.jobs.rows));
+			assert.ok(result.alerts.rows.length <= 1);
+			assert.ok(result.jobs.rows.length <= 1);
+		});
+		
+		await check('historical human view renders all required sections in order', () => {
+			const output = xy(['group', 'history', group.id, history_spec, '--merge', 'min', '--limit', '1']);
+			assert.match(output, /HOURLY GROUP HISTORY/);
+			assert.ok(output.indexOf('GROUP SUMMARY') < output.indexOf('GROUP SERVERS'));
+			assert.ok(output.indexOf('GROUP SERVERS') < output.indexOf('GROUP MONITORS'));
+			assert.ok(output.indexOf('GROUP MONITORS') < output.indexOf('GROUP ALERTS'));
+			assert.ok(output.indexOf('GROUP ALERTS') < output.indexOf('GROUP JOBS'));
+			assert.match(output, /Minimum CPU Load/);
+		});
+		
+		await check('Group help chapters render', () => {
+			for (const section of ['groups', 'group', 'group list', 'group get', 'group history', 'group create', 'group update', 'group delete']) {
+				assert.match(xy(['help', ...section.split(' ')]), new RegExp('HELP: ' + section.toUpperCase()));
+			}
+		});
+	}
+	finally {
+		await cleanupFixtures([
+			{ list: 'groups', method: 'deleteGroup', match: item => groups.has(item.id) || item.title.startsWith(title) }
+		]);
+	}
+});

package/test/help.test.js

@@ -0,0 +1,26 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { xy } = require('./helpers/common.js');
+
+test('help suggests the closest chapter for a typo', () => {
+	const output = xy(['help', 'event', 'udpate'], { fail: true });
+	assert.match(output, /Could not find help chapter for "event udpate"\. Did you mean "event update"\?/);
+});
+
+test('help does not suggest an unrelated chapter', () => {
+	const output = xy(['help', 'completely', 'unrelated', 'words'], { fail: true });
+	assert.match(output, /Could not find help chapter for "completely unrelated words"\./);
+	assert.doesNotMatch(output, /Did you mean/);
+});
+
+test('unknown top-level command suggests the closest command', () => {
+	const output = xy(['evnets'], { fail: true });
+	assert.match(output, /Unknown command: evnets\. Did you mean "events"\?/);
+	assert.match(output, /Available Commands:.*events/);
+});
+
+test('unknown top-level command does not suggest an unrelated command', () => {
+	const output = xy(['completely_unrelated'], { fail: true });
+	assert.match(output, /Unknown command: completely_unrelated/);
+	assert.doesNotMatch(output, /Did you mean/);
+});

package/test/helpers/common.js

@@ -0,0 +1,127 @@
+// Shared setup for the live CLI integration tests. No third-party test framework.
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const Path = require('node:path');
+const cp = require('node:child_process');
+const root = Path.resolve(__dirname, '../..');
+
+function loadTestConfig() {
+	// Use the same config files and environment overrides as the CLI. Every
+	// suite checks the destination, including when run directly with node --test.
+	const app = {};
+	require('../../lib/config.js').loadConfig.call(app);
+	
+	assert.ok(/^http:\/\/localhost:5522\/?$/.test(app.config.base_url || ''),
+		'Tests require XYOPS_BASE_URL=http://localhost:5522 (or the equivalent CLI config).');
+	assert.ok(app.config.api_key, 'Tests require an administrator API key in the CLI config or XYOPS_API_KEY.');
+	
+	return app.config;
+}
+
+function createCheck(t) {
+	// Each check gets its own native test result. Lifecycle steps depend on
+	// earlier steps, so stop this suite on failure and let its cleanup run.
+	return async function check(name, callback) {
+		let passed = false;
+		
+		await t.test(name, async () => {
+			await callback();
+			passed = true;
+		});
+		
+		if (!passed) throw new Error('Lifecycle stopped after failed check: ' + name);
+	};
+}
+
+function createTempDir(t, prefix) {
+	// Register immediately so local files are removed even if setup or server
+	// cleanup fails. Each suite has a private directory outside the repository.
+	const dir = fs.mkdtempSync(Path.join(os.tmpdir(), prefix));
+	t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+	
+	return dir;
+}
+
+function runCLI(args, options = {}) {
+	// These tests deliberately exercise the public executable in fresh processes.
+	// Captured output can contain API secrets, so keep it out of failure reports.
+	const result = cp.spawnSync(process.execPath, [
+		...(options.preload ? ['--require', options.preload] : []),
+		Path.join(root, 'index.js'),
+		...args
+	], {
+		// Most suites run from the project root. Filesystem-oriented commands can
+		// override this with a private temporary directory while still invoking the
+		// real CLI executable by its absolute path.
+		cwd: options.cwd || root,
+		encoding: 'utf8',
+		timeout: 30000,
+		maxBuffer: 16 * 1024 * 1024,
+		input: options.input,
+		env: {
+			...process.env,
+			XYOPS_COLOR: 'false',
+			XYOPS_SUGGEST: 'true',
+			XYOPS_DEBUG: 'false',
+			XYOPS_VERBOSE: 'false',
+			...options.env
+		}
+	});
+	
+	assert.ok(!result.error && result.signal === null, 'CLI process completed: ' + args[0]);
+	assert.equal(result.status === 0, !options.fail, 'Unexpected CLI exit status: ' + args.slice(0, 2).join(' '));
+	
+	return result.stdout + result.stderr;
+}
+
+function xy(args, options = {}) {
+	// Accept the boolean failure shorthand used by the export and log suites.
+	return runCLI(args, typeof options === 'boolean' ? { fail: options } : options);
+}
+
+function json(args, options) {
+	const output = xy([...args, '--format', 'jsonc'], options);
+	const line = output.split('\n').find(line => /^[\[{]/.test(line));
+	assert.ok(line, 'CLI returned JSON: ' + args[0]);
+	
+	return JSON.parse(line);
+}
+
+async function call(method, params) {
+	const { api } = require('@pixlcore/xyops-sdk');
+	const result = await api[method](params);
+	assert.ok(!result.err && result.data && result.data.code === 0, 'API request succeeded: ' + method);
+	
+	return result.data;
+}
+
+async function cleanupFixtures(resources) {
+	// Match only this run's unique IDs/titles. Continue deleting other fixtures
+	// if one deletion fails, then report cleanup failures without response data.
+	const data = await call('getMultiple', { lists: 'all' });
+	const errors = [];
+	
+	for (const resource of resources) {
+		const objects = data[resource.list].filter(resource.match);
+		if (resource.sort) objects.sort(resource.sort);
+		
+		for (const object of objects) {
+			try { await call(resource.method, { id: object.id }); }
+			catch (error) { errors.push(error); }
+		}
+	}
+	
+	// Verify deletion even when an API returned success. Only names of resource
+	// lists appear in failures; never dump complete definitions or credentials.
+	const remaining = await call('getMultiple', { lists: 'all' });
+	for (const resource of resources) {
+		if (remaining[resource.list].some(resource.match)) {
+			errors.push(new Error('Disposable fixtures remain in ' + resource.list));
+		}
+	}
+	
+	if (errors.length) throw new AggregateError(errors, 'Fixture cleanup failed. Check the local server before rerunning.');
+}
+
+module.exports = { loadTestConfig, createCheck, createTempDir, runCLI, xy, json, call, cleanupFixtures };

package/test/helpers/pagination-preload.cjs

@@ -0,0 +1,18 @@
+// Record pagination at the SDK boundary without logging authentication or data.
+const fs = require('node:fs');
+const sdk = require('@pixlcore/xyops-sdk');
+const original = sdk.api;
+
+sdk.api = new Proxy({}, {
+	get(target, method) {
+		return async function(params, ...rest) {
+			const trace = { method };
+			for (const key of ['query', 'offset', 'limit', 'page']) {
+				if (params && (key in params)) trace[key] = params[key];
+			}
+			
+			fs.appendFileSync(process.env.XYCLI_PAGINATION_TRACE, JSON.stringify(trace) + '\n');
+			return original[method](params, ...rest);
+		};
+	}
+});

package/test/log.test.js

@@ -0,0 +1,103 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { loadTestConfig, createCheck, xy, json } = require('./helpers/common.js');
+
+test('log', async t => {
+	loadTestConfig();
+	const check = createCheck(t);
+	
+	// Read-only integration checks for the system log search CLI.
+	
+	await check('default request selects xyOps and 100 rows', () => assert.deepEqual(json(['log', '--dry']), { log: 'xyOps', rows: 100 }));
+	
+	await check('positional name and explicit row limit', () => assert.deepEqual(json(['log', 'xyOps', '--rows', '1000', '--dry']), { log: 'xyOps', rows: 1000 }));
+	
+	await check('named log selector', () => assert.deepEqual(json(['log', '--log', 'xyOps', '--rows', '1', '--dry']), { log: 'xyOps', rows: 1 }));
+	
+	await check('numeric match becomes text', () => assert.equal(json(['log', '--match', '123', '--dry']).match, '123'));
+	
+	await check('boolean flags serialize correctly', () => {
+		const req = json(['log', '--match', 'error', '--regex', 'false', '--case', 'true', '--dry']);
+		assert.equal(req.regex, false);
+		assert.equal(req.case, true);
+	});
+	
+	await check('display sort stays out of API request', () => assert.deepEqual(json(['log', '--sort', 'date_desc', '--dry']), { log: 'xyOps', rows: 100 }));
+	
+	await check('default live search returns at most 100 rows', () => {
+		const rows = json(['log']);
+		assert.ok(rows.length > 0 && rows.length <= 100);
+		for (const key of ['hires_epoch', 'category', 'code', 'msg', 'data']) assert.ok(key in rows[0]);
+	});
+	
+	await check('explicit limit returns latest subset', () => assert.equal(json(['log', 'xyOps', '--rows', '3']).length, 3));
+	
+	await check('ascending file order', () => {
+		const rows = json(['log', '--rows', '5', '--cols', 'hires_epoch']);
+		assert.ok(rows.every((row, idx) => !idx || row.hires_epoch >= rows[idx - 1].hires_epoch));
+	});
+	
+	await check('descending display order', () => {
+		const rows = json(['log', '--rows', '5', '--cols', 'hires_epoch', '--sort', 'date_desc']);
+		assert.ok(rows.every((row, idx) => !idx || row.hires_epoch <= rows[idx - 1].hires_epoch));
+	});
+	
+	await check('CSV columns project JSON output', () => {
+		const rows = json(['log', '--rows', '2', '--cols', 'category,code']);
+		assert.equal(rows.length, 2);
+		assert.deepEqual(Object.keys(rows[0]), ['category', 'code']);
+	});
+	
+	await check('JSON column array', () => {
+		const rows = json(['log', '--rows', '1', '--cols', '["msg","data"]']);
+		assert.deepEqual(Object.keys(rows[0]), ['msg', 'data']);
+		assert.equal(typeof(rows[0].data), 'string');
+	});
+	
+	await check('matching searches fields omitted from output', () => {
+		const rows = json(['log', '--rows', '2', '--match', 'debug', '--cols', 'hires_epoch']);
+		assert.ok(rows.length);
+		assert.deepEqual(Object.keys(rows[0]), ['hires_epoch']);
+	});
+	
+	await check('case insensitive regex match', () => {
+		const rows = json(['log', '--rows', '2', '--match', '\\]\\[DeBuG\\]\\[', '--regex', '--cols', 'category']);
+		assert.ok(rows.length);
+		assert.ok(rows.every(row => row.category === 'debug'));
+	});
+	
+	await check('case sensitive regex match', () => assert.deepEqual(json(['log', '--match', '\\]\\[DeBuG\\]\\[', '--regex', '--case']), []));
+	
+	await check('literal matching escapes regex syntax', () => assert.deepEqual(json(['log', '--match', '^.*$']), []));
+	
+	await check('regex matching supports syntax', () => assert.equal(json(['log', '--rows', '2', '--match', '^.*$', '--regex']).length, 2));
+	
+	await check('missing archive returns an empty array', () => assert.deepEqual(json(['log', '--date', '1900-01-01']), []));
+	
+	await check('missing log returns an empty array', () => assert.deepEqual(json(['log', 'xycli_nonexistent_log_test']), []));
+	
+	await check('native log lines, total line count, and suggestions', () => {
+		const output = xy(['log', '--rows', '2', '--cols', 'category,code']);
+		assert.match(output, /2 rows returned, [\d,]+ total log rows/);
+		assert.match(output, /Other Commands:/);
+		assert.ok(!output.includes('page 2'));
+		assert.equal(output.split('\n').filter(line => /^\[[^\]]*\]\[[^\]]*\]$/.test(line)).length, 2);
+	});
+	
+	await check('empty human output', () => assert.match(xy(['log', '--date', '1900-01-01']), /0 rows returned/));
+	
+	for (const args of [
+		['--rows', '0'], ['--rows', '1001'], ['--rows', '1.5'], ['--rows', 'nope'],
+		['--match', '(', '--regex'], ['--regex', 'maybe'], ['--case', 'maybe'],
+		['--cols', 'bad_column'], ['--cols', '[]'], ['--cols', '{}'],
+		['--date', '2026-02-30'], ['--date', 'yesterday'], ['--date', '2026-13-01'],
+		['--sort', 'wrong'], ['--limit', '5'], ['--offset', '1'], ['--page', '2'],
+		['../xyOps'], ['xyOps.log'], ['xyOps', 'extra'], ['xyOps', '--log', 'other'], ['--match', '{}']
+	]) await check('reject ' + args.join(' '), () => xy(['log', ...args], true));
+	
+	await check('help documents default of 100 rows', () => {
+		const output = xy(['help', 'log']);
+		assert.match(output, /defaults to 100/);
+		assert.match(output, /--rows/);
+	});
+});