@pixlcore/xycli 1.0.0

package/test/tags.test.js

@@ -0,0 +1,230 @@
+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: apiCall, cleanupFixtures } = require('./helpers/common.js');
+
+test('tags', async t => {
+	loadTestConfig();
+	const check = createCheck(t);
+	
+	// These definitions are never attached to Events, Jobs, Tickets, Actions, or
+	// Limits.  Track every generated ID so cleanup remains exact after failures.
+	const stamp = Date.now();
+	const id = 'cli_tag_test_' + stamp;
+	const title = 'CLI Tag Test ' + stamp;
+	const ids = new Set([id]);
+	const temp = createTempDir(t, 'xycli-tag-test-');
+	
+	try {
+		const original = (await apiCall('getTags')).rows;
+		
+		await check('dry creation fills UI defaults', () => {
+			const req = json(['tag', 'create', '--id', id, '--title', title, '--dry']);
+			assert.deepEqual(req, {
+				icon: 'tag-outline',
+				notes: '',
+				id: id,
+				title: title
+			});
+		});
+		
+		await check('dry creation does not persist', () => assert.deepEqual(json(['tags', '--id', id]), []));
+		
+		const created = json([
+			'tag', 'create', '--id', id, '--title', title,
+			'--icon', 'mdi-alert-rhombus', '--notes', 'First line\nSecond line'
+		]);
+		
+		await check('create persists all editable fields', () => {
+			assert.equal(created.id, id);
+			assert.equal(created.title, title);
+			assert.equal(created.icon, 'alert-rhombus');
+			assert.equal(created.notes, 'First line\nSecond line');
+			assert.equal(created.revision, 1);
+			assert.ok(created.username);
+			assert.ok(created.created);
+			assert.equal(created.created, created.modified);
+		});
+		
+		await check('exact ID get', () => assert.deepEqual(json(['tag', id]), created));
+		
+		await check('fuzzy title get', () => assert.equal(json(['tag', 'get', '--title', title.toLowerCase()]).id, id));
+		
+		await check('named ID get', () => assert.equal(json(['tag', 'get', '--id', id]).id, id));
+		
+		await check('list search and icon filter', () => {
+			assert.deepEqual(json(['tags', title, '--icon', 'alert-rhombus']), [created]);
+			assert.deepEqual(json(['tag', 'list', '--id', id]), [created]);
+		});
+		
+		await check('JSON list ignores human pagination arguments', () => {
+			assert.deepEqual(json(['tags', '--id', id, '--limit', '1', '--page', '2']), [created]);
+		});
+		
+		await check('Tag list is ordered alphabetically', () => {
+			const rows = json(['tags']);
+			assert.ok(rows.every((row, idx) => !idx || rows[idx - 1].title.toLowerCase().localeCompare(row.title.toLowerCase()) <= 0));
+		});
+		
+		await check('human list supports pagination and suggestions', () => {
+			const out = xy(['tags', '--limit', '1', '--page', '1']);
+			assert.match(out, /page 1 of/i);
+			assert.match(out, /Other Commands:/);
+		});
+		
+		await check('empty filtered Tag table', () => {
+			assert.match(xy(['tags', id, '--icon', 'tag-outline']), /No filtered tags found/i);
+		});
+		
+		await check('human detail shows summary and multiline notes', () => {
+			const out = xy(['tag', id]);
+			for (const label of ['Tag Summary', 'Tag ID', 'Icon', 'Events', 'Author', 'Revision', 'Tag Notes', 'First line', 'Second line']) {
+				assert.ok(out.toLowerCase().includes(label.toLowerCase()), label);
+			}
+			assert.match(out, /Other Commands:/);
+		});
+		
+		await check('tagged Event suggestion uses the supported tags filter', () => {
+			assert.deepEqual(json(['events', '--tags', id]), []);
+		});
+		
+		await check('human update shows target and parsed data', () => {
+			const out = xy(['tag', 'update', id, '--notes', 'Preview', '--dry']);
+			assert.match(out, /UPDATE TAG/);
+			assert.match(out, new RegExp('Tag ID:\\s+' + id));
+			assert.match(out, /UPDATE DATA[\s\S]*"notes": "Preview"/);
+		});
+		
+		await check('sparse dry update excludes unrelated fields', () => {
+			assert.deepEqual(json(['tag', 'update', id, '--notes', 'Preview', '--dry']), { notes: 'Preview', id: id });
+		});
+		
+		await check('dry update keeps revision unchanged', () => assert.equal(json(['tag', id]).revision, 1));
+		
+		// Simulate a property introduced by a future xyOps release.  The CLI must
+		// omit unknown saved properties from its sparse update request.
+		await apiCall('updateTag', { id: id, future_property: { enabled: true } });
+		json(['tag', 'update', id, '--title', title + ' Updated', '--notes', 'Updated notes']);
+		
+		await check('sparse update preserves a future server property', () => {
+			const row = json(['tag', id]);
+			assert.equal(row.title, title + ' Updated');
+			assert.equal(row.notes, 'Updated notes');
+			assert.equal(row.icon, 'alert-rhombus');
+			assert.deepEqual(row.future_property, { enabled: true });
+			assert.equal(row.revision, 3);
+		});
+		
+		json(['tag', 'update', id, '--json', '@-'], {
+			input: JSON.stringify({ icon: '', notes: 'From standard input' })
+		});
+		
+		await check('complete JSON update from stdin', () => {
+			const row = json(['tag', id]);
+			assert.equal(row.icon, '');
+			assert.equal(row.notes, 'From standard input');
+			assert.deepEqual(row.future_property, { enabled: true });
+		});
+		
+		const revision = json(['tag', id]).revision;
+		await check('unconfirmed delete shows target and warning toast', () => {
+			for (const args of [['delete', id], ['delete', id, '--confirm', 'false']]) {
+				const out = xy(['tag', ...args]);
+				assert.match(out, /DELETE TAG/);
+				assert.match(out, /⚠️[\s\S]*Please confirm the Tag delete/);
+			}
+		});
+		
+		const rejected = [
+			['update', id],
+			['update', title + ' Updated', '--notes', 'Wrong selector'],
+			['update', id, '--id', 'different', '--notes', 'Wrong ID'],
+			['update', id, '--title', ' '],
+			['update', id, '--icon', 'true'],
+			['update', id, '--notes', 'false'],
+			['update', id, '--revision', '99'],
+			['update', id, '--notess', 'Typo'],
+			['update', id, '--notes.extra', 'Bad path'],
+			['delete', title + ' Updated', '--confirm'],
+			['delete', id, '--confirm', 'maybe']
+		];
+		
+		for (const args of rejected) {
+			await check('reject Tag ' + args.slice(0, 4).join(' '), () => xy(['tag', ...args], { fail: true }));
+		}
+		
+		await check('rejected requests leave revision unchanged', () => assert.equal(json(['tag', id]).revision, revision));
+		
+		await check('duplicate Tag ID error is surfaced', () => {
+			assert.match(xy(['tag', 'create', '--id', id, '--title', title], { fail: true }), /already exists/i);
+		});
+		
+		const auto = json(['tag', 'create', '--title', title + ' Automatic']);
+		ids.add(auto.id);
+		
+		await check('automatic ID and default icon', () => {
+			assert.match(auto.id, /^t/);
+			assert.equal(auto.icon, 'tag-outline');
+			assert.equal(auto.notes, '');
+		});
+		
+		const file = Path.join(temp, 'tag.json');
+		fs.writeFileSync(file, JSON.stringify({
+			title: title + ' File',
+			icon: 'tag-heart-outline',
+			notes: 'Created from JSON'
+		}));
+		const imported = json(['tag', 'create', '--json', '@' + file]);
+		ids.add(imported.id);
+		
+		await check('complete creation from JSON file', () => {
+			assert.equal(imported.icon, 'tag-heart-outline');
+			assert.equal(imported.notes, 'Created from JSON');
+		});
+		
+		const humanID = id + '_human';
+		ids.add(humanID);
+		await check('human creation prints suggested commands', () => {
+			assert.match(xy(['tag', 'create', '--id', humanID, '--title', title + ' Human']), /Other Commands:/);
+		});
+		
+		// Remove auxiliary definitions before the final primary delete checks.
+		for (const tagID of Array.from(ids)) {
+			if (tagID === id) continue;
+			json(['tag', 'delete', tagID, '--confirm']);
+			ids.delete(tagID);
+		}
+		
+		await check('dry delete request contains only the ID', () => {
+			assert.deepEqual(json(['tag', 'delete', id, '--confirm', '--dry']), { id: id });
+		});
+		
+		await check('dry delete leaves the Tag intact', () => assert.equal(json(['tag', id]).id, id));
+		
+		json(['tag', 'delete', id, '--confirm']);
+		ids.delete(id);
+		
+		await check('confirmed delete removes the Tag', () => assert.deepEqual(json(['tags', '--id', id]), []));
+		
+		await check('get after deletion fails', () => xy(['tag', id], { fail: true }));
+		
+		for (const topic of ['tags', 'tag', 'tag list', 'tag get', 'tag create', 'tag update', 'tag delete']) {
+			await check('help ' + topic, () => assert.ok(xy(['help', ...topic.split(' ')]).length > 100));
+		}
+		
+		await check('existing Tags remain unchanged', async () => {
+			const now = (await apiCall('getTags')).rows;
+			for (const tag of original) {
+				const current = now.find(item => item.id === tag.id);
+				assert.ok(current, 'Existing Tag still present: ' + tag.id);
+				assert.equal(JSON.stringify(current), JSON.stringify(tag), 'Existing Tag unchanged: ' + tag.id);
+			}
+		});
+	}
+	finally {
+		await cleanupFixtures([
+			{ list: 'tags', method: 'deleteTag', match: item => ids.has(item.id) || item.title.startsWith(title) }
+		]);
+	}
+});

package/test/tickets.test.js

@@ -0,0 +1,261 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const Path = require('node:path');
+const sdk = require('@pixlcore/xyops-sdk');
+const {
+	loadTestConfig, createCheck, createTempDir, runCLI, xy, json,
+	call: apiCall
+} = require('./helpers/common.js');
+
+test('tickets', async t => {
+	loadTestConfig();
+	const check = createCheck(t);
+	const stamp = Date.now();
+	const id = 'tcli_ticket_' + stamp;
+	const subject = 'CLI Ticket Test ' + stamp;
+	const tagID = 'cli_ticket_tag_' + stamp;
+	const temp = createTempDir(t, 'xycli-ticket-test-');
+	const bodyFile = Path.join(temp, 'ticket.md');
+	const firstFile = Path.join(temp, 'first-attachment.txt');
+	const secondFile = Path.join(temp, 'second-attachment.json');
+	const traceFile = Path.join(temp, 'trace.jsonl');
+	const body = '# Test Ticket\n\n- **Bold item** with `code`\n';
+	let ticketCreated = false;
+	let tagCreated = false;
+
+	fs.writeFileSync(bodyFile, body);
+	fs.writeFileSync(firstFile, 'First Ticket attachment.\n');
+	fs.writeFileSync(secondFile, '{\n\t"attachment": true\n}\n');
+
+	try {
+		const multiple = await apiCall('getMultiple', { lists: 'all' });
+		const event = (multiple.events || []).find( item => item.enabled ) || (multiple.events || [])[0];
+
+		await apiCall('createTag', { id: tagID, title: 'CLI Ticket Tag ' + stamp, icon: 'tag-outline' });
+		tagCreated = true;
+
+		await check('dry creation fills web editor defaults', () => {
+			const req = json(['ticket', 'create', '--id', id, '--subject', subject, '--dry']);
+			assert.equal(req.status, 'open');
+			assert.equal(req.type, 'change');
+			assert.equal(req.body, '');
+			assert.deepEqual(req.assignees, []);
+			assert.deepEqual(req.cc, []);
+			assert.deepEqual(req.notify, []);
+			assert.deepEqual(req.tags, []);
+			assert.equal(req.due, 0);
+		});
+
+		// Mark cleanup eligible before the combined create/upload command.  If the
+		// upload fails after creation, the finally block still removes the Ticket.
+		ticketCreated = true;
+		const created = json([
+			'ticket', 'create', '--id', id, '--subject', subject,
+			'--status', 'draft', '--type', 'issue', '--body', '@' + bodyFile,
+			'--file', firstFile
+		]);
+
+		await check('create keeps Ticket draft and uploads a saved attachment', () => {
+			assert.equal(created.id, id);
+			assert.equal(created.subject, subject);
+			assert.equal(created.status, 'draft');
+			assert.equal(created.type, 'issue');
+			assert.equal(created.body, body);
+			assert.deepEqual(created.assignees, []);
+			assert.equal(created.files.length, 1);
+			assert.equal(created.files[0].filename, Path.basename(firstFile));
+			assert.equal(created.files[0].ticket, id);
+		});
+
+		const num = created.num;
+		await check('number, hash-number, named number, and ID fetch the same Ticket', () => {
+			assert.equal(json(['ticket', String(num)]).id, id);
+			assert.equal(json(['ticket', '#' + num]).id, id);
+			assert.equal(json(['ticket', 'get', '--number', String(num)]).id, id);
+			assert.equal(json(['ticket', 'get', '--id', id]).num, num);
+		});
+
+		await check('raw and named Ticket searches find the fixture', () => {
+			assert.ok(json(['tickets', '"' + subject + '"']).some( row => row.id == id));
+			assert.ok(json(['tickets', '--num', String(num), '--status', 'draft', '--type', 'issue']).some( row => row.id == id));
+			assert.ok(json(['ticket', 'list', '--number', String(num)]).some( row => row.id == id));
+		});
+
+		await check('human Ticket search paginates and suggests commands', () => {
+			const out = xy(['tickets', '--status', 'draft', '--limit', '1']);
+			assert.match(out, /TICKET SEARCH RESULTS/);
+			assert.match(out, /Other Commands:/);
+		});
+
+		await check('close, open, and draft actions translate to sparse status updates', () => {
+			assert.deepEqual(json(['ticket', 'update', String(num), 'close', '--dry']), { status: 'closed', id: id });
+			assert.deepEqual(json(['ticket', 'update', String(num), 'open', '--dry']), { status: 'open', id: id });
+			assert.deepEqual(json(['ticket', 'update', String(num), 'draft', '--dry']), { status: 'draft', id: id });
+		});
+
+		json(['ticket', 'update', String(num), '--assign', 'admin', '--tag', tagID]);
+		json(['ticket', 'update', String(num), '--assign', 'admin', '--tag', tagID]);
+		await check('assign and Tag sugar append without duplicates', () => {
+			const row = json(['ticket', String(num)]);
+			assert.deepEqual(row.assignees, ['admin']);
+			assert.deepEqual(row.tags, [tagID]);
+			assert.equal(row.status, 'draft');
+		});
+
+		const comment = 'Investigation update:\n\n- **Checked** the `logs`.';
+		json(['ticket', String(num), '--comment', comment]);
+		await check('comment shortcut stores Markdown while Ticket remains draft', () => {
+			const row = json(['ticket', String(num)]);
+			const saved = row.changes.filter( change => change.type == 'comment' );
+			assert.equal(saved.length, 1);
+			assert.equal(saved[0].body, comment);
+			assert.equal(row.status, 'draft');
+		});
+
+		await check('explicit comment supports stdin and dry run', () => {
+			const req = json(['ticket', 'comment', String(num), '--body', '@-', '--dry'], {
+				input: '{\n\t"markdown": "text"\n}\n'
+			});
+			assert.equal(req.id, id);
+			assert.equal(req.change.type, 'comment');
+			assert.equal(req.change.body, '{\n\t"markdown": "text"\n}\n');
+		});
+
+		const files = json(['ticket', 'upload', String(num), '--file', secondFile]);
+		await check('dedicated upload always saves the attachment', () => {
+			assert.equal(files.length, 2);
+			assert.ok(files.some( file => file.filename == Path.basename(secondFile) && file.ticket == id));
+		});
+
+		const secondMeta = files.find( file => file.filename == Path.basename(secondFile));
+		const downloadedFile = Path.join(temp, 'downloaded-attachment.json');
+		await check('download saves exact attachment bytes by File ID', () => {
+			const out = xy(['ticket', 'download', String(num), secondMeta.id, downloadedFile]);
+			assert.match(out, /Successfully downloaded Ticket file/);
+			assert.equal(fs.readFileSync(downloadedFile, 'utf8'), fs.readFileSync(secondFile, 'utf8'));
+		});
+
+		await check('download dry run resolves filename and default output path', () => {
+			const req = json(['ticket', 'download', String(num), secondMeta.filename, '--dry']);
+			assert.equal(req.ticket, id);
+			assert.equal(req.number, num);
+			assert.equal(req.file, secondMeta.filename);
+			assert.equal(req.request.path, secondMeta.path.replace(/^files\//, ''));
+			assert.equal(req.request.download, secondMeta.filename);
+			assert.equal(req.output, Path.resolve(secondMeta.filename));
+		});
+
+		await check('download refuses unknown files and existing destinations', () => {
+			xy(['ticket', 'download', String(num), 'missing-file-id'], { fail: true });
+			xy(['ticket', 'download', String(num), secondMeta.id, downloadedFile], { fail: true });
+		});
+
+		if (event) await apiCall('updateTicket', { id: id, events: [{ id: event.id, params: {} }] });
+
+		await check('human detail renders body, comments, files, and Events', () => {
+			const out = xy(['ticket', String(num)]);
+			for (const text of [
+				'TICKET #' + num, 'Number', '#' + num, 'Ticket ID', id, subject,
+				'TICKET BODY', 'Test Ticket', '• Bold item with code',
+				'TICKET FILES', Path.basename(firstFile), Path.basename(secondFile), 'Download a file',
+				'Comment by admin', 'Investigation update', '• Checked the logs'
+			]) assert.ok(out.includes(text), text);
+			if (event) {
+				assert.match(out, /TICKET EVENTS/);
+				assert.ok(out.includes(event.id));
+			}
+		});
+
+		await check('Ticket detail searches for associated completed Jobs with pagination', () => {
+			fs.writeFileSync(traceFile, '');
+			runCLI(['ticket', String(num), '--limit', '3', '--page', '2'], {
+				preload: Path.join(__dirname, 'helpers/pagination-preload.cjs'),
+				env: { XYCLI_PAGINATION_TRACE: traceFile }
+			});
+			const trace = fs.readFileSync(traceFile, 'utf8').trim().split('\n').filter(Boolean).map( line => JSON.parse(line) );
+			const search = trace.find( row => row.method == 'searchJobs' );
+			assert.deepEqual(search, { method: 'searchJobs', query: 'tickets:' + id, offset: 3, limit: 3 });
+		});
+
+		await check('exact ID update skips get_ticket when old arrays are unnecessary', () => {
+			fs.writeFileSync(traceFile, '');
+			runCLI(['ticket', 'update', id, '--subject', subject + ' Updated', '--dry'], {
+				preload: Path.join(__dirname, 'helpers/pagination-preload.cjs'),
+				env: { XYCLI_PAGINATION_TRACE: traceFile }
+			});
+			const trace = fs.readFileSync(traceFile, 'utf8').trim().split('\n').filter(Boolean).map( line => JSON.parse(line) );
+			assert.ok(!trace.some( row => row.method == 'getTicket'));
+		});
+
+		await apiCall('updateTicket', { id: id, future_property: { retained: true } });
+		json(['ticket', 'update', id, '--subject', subject + ' Updated']);
+		await check('sparse update preserves future Ticket properties', () => {
+			const row = json(['ticket', String(num)]);
+			assert.equal(row.subject, subject + ' Updated');
+			assert.deepEqual(row.future_property, { retained: true });
+			assert.equal(row.status, 'draft');
+		});
+
+		const rejected = [
+			['update', String(num)],
+			['update', String(num), '--subjec', 'Typo'],
+			['update', String(num), '--status', 'pending'],
+			['update', String(num), '--assignees', '{}'],
+			['update', String(num), '--tag', 'missing_ticket_tag'],
+			['comment', String(num), '--body', ''],
+			['upload', String(num), '--file', Path.join(temp, 'missing.txt')],
+			['delete', String(num), '--confirm', 'maybe']
+		];
+		for (const args of rejected) {
+			await check('reject Ticket ' + args.slice(0, 4).join(' '), () => xy(['ticket', ...args], { fail: true }));
+		}
+
+		await check('unconfirmed delete shows the Ticket and warning toast', () => {
+			const out = xy(['ticket', 'delete', String(num)]);
+			assert.match(out, /DELETE TICKET/);
+			assert.match(out, new RegExp('#' + num));
+			assert.match(out, /⚠️[\s\S]*Please confirm the Ticket delete/);
+		});
+
+		await check('dry delete resolves number to the internal ID', () => {
+			assert.deepEqual(json(['ticket', 'delete', String(num), '--confirm', '--dry']), { id: id });
+		});
+
+		json(['ticket', 'delete', String(num), '--confirm']);
+		ticketCreated = false;
+		await check('confirmed delete removes the Ticket', async () => {
+			const { err } = await sdk.api.getTicket({ id: id });
+			assert.ok(err);
+		});
+
+		for (const topic of [
+			'tickets', 'ticket', 'ticket list', 'ticket get', 'ticket create',
+			'ticket update', 'ticket comment', 'ticket upload', 'ticket download', 'ticket delete'
+		]) {
+			await check('help ' + topic, () => assert.ok(xy(['help', ...topic.split(' ')]).length > 100));
+		}
+	}
+	finally {
+		const cleanupErrors = [];
+		if (ticketCreated) {
+			try {
+				await sdk.api.deleteTicket({ id: id });
+				const result = await sdk.api.getTicket({ id: id });
+				if (!result.err) cleanupErrors.push(new Error('Disposable Ticket remains: ' + id));
+			}
+			catch (error) { cleanupErrors.push(error); }
+		}
+		if (tagCreated) {
+			try {
+				await sdk.api.deleteTag({ id: tagID });
+				const result = await sdk.api.getTags();
+				if (!result.err && result.data.rows.some( tag => tag.id == tagID )) {
+					cleanupErrors.push(new Error('Disposable Tag remains: ' + tagID));
+				}
+			}
+			catch (error) { cleanupErrors.push(error); }
+		}
+		if (cleanupErrors.length) throw new AggregateError(cleanupErrors, 'Ticket fixture cleanup failed.');
+	}
+});

package/test/toast.test.js

@@ -0,0 +1,73 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const cli = require('pixl-cli');
+const utils = require('../lib/utils.js');
+
+cli.global();
+
+test('toast wraps within the terminal width without ellipsis', () => {
+	const originalWidth = cli.width;
+	const originalWrite = process.stdout.write;
+	const originalColor = cli.chalk.enabled;
+	let output = '';
+	
+	try {
+		cli.width = function() { return 40; };
+		cli.chalk.enabled = false;
+		process.stdout.write = function(chunk) {
+			output += chunk;
+			return true;
+		};
+		
+		utils.toast.call({
+			colors: { orange: [255, 105, 0] },
+			color: utils.color
+		}, '⚠️', 'orange', 'Preview only. Review the Plugin data above, then use --confirm to install it.');
+	}
+	finally {
+		cli.width = originalWidth;
+		cli.chalk.enabled = originalColor;
+		process.stdout.write = originalWrite;
+	}
+	
+	const box_lines = output.split('\n').filter( line => line.match(/[┌│└]/) );
+	const plain_text = cli.Tools.stripANSI(output).replace(/[┌─┐│└┘]/g, ' ').replace(/\s+/g, ' ');
+	assert.ok(box_lines.length > 5, 'Long toast wrapped onto multiple content lines');
+	assert.ok(box_lines.every( line => cli.stringWidth(line) <= 40 ), 'Toast stayed within terminal width');
+	assert.doesNotMatch(output, /\.\.\./);
+	assert.match(plain_text, /Preview only\. Review the Plugin data above, then use --confirm to install it\./);
+});
+
+test('user notes preserve explicit lines and wrap within the terminal width', () => {
+	const originalWidth = cli.width;
+	const originalWrite = process.stdout.write;
+	const originalColor = cli.chalk.enabled;
+	let output = '';
+	
+	try {
+		cli.width = function() { return 40; };
+		cli.chalk.enabled = false;
+		process.stdout.write = function(chunk) {
+			output += chunk;
+			return true;
+		};
+		
+		utils.printUserNotes.call({
+			colors: { theme: [0, 0, 0] },
+			color: utils.color
+		}, 'THING NOTES', 'First line\nSecond line that is intentionally very long so it wraps around the terminal width.');
+	}
+	finally {
+		cli.width = originalWidth;
+		cli.chalk.enabled = originalColor;
+		process.stdout.write = originalWrite;
+	}
+	
+	const box_lines = output.split('\n').filter( line => line.match(/[┌│└]/) );
+	const plain_text = cli.Tools.stripANSI(output);
+	assert.match(plain_text, /THING NOTES/);
+	assert.match(plain_text, /First line/);
+	assert.match(plain_text, /Second line that is intentionally/);
+	assert.ok(box_lines.length > 4, 'Long notes wrapped onto multiple content lines');
+	assert.ok(box_lines.every( line => cli.stringWidth(line) <= 40 ), 'Notes stayed within terminal width');
+});

package/test/transfer-apikey.test.js

@@ -0,0 +1,96 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const Path = require('node:path');
+const zlib = require('node:zlib');
+const crypto = require('node:crypto');
+const { loadTestConfig, createCheck, createTempDir, xy, json, call, cleanupFixtures } = require('./helpers/common.js');
+
+test('transfer-apikey', async t => {
+	const config = loadTestConfig();
+	const check = createCheck(t);
+	const verify = (condition, description) => check(description, () => assert.ok(condition, description));
+	
+	// Live API key portability check. Keep plaintext credentials in memory only.
+	const title = 'cli_key_portability_' + Date.now();
+	const temp = createTempDir(t, 'xycli-key-portability-');
+	
+	async function authenticate(secret) {
+		// Use only the disposable secret, with no configured admin credentials or
+		// session cookies. A protected read verifies actual authentication.
+		const response = await fetch(config.base_url.replace(/\/$/, '') + '/api/app/get_events/v1', {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json', 'X-API-Key': secret },
+			body: '{}',
+			signal: AbortSignal.timeout(10000)
+		});
+		
+		return response.json();
+	}
+		
+	const original = (await call('getApiKeys', {})).rows;
+	
+	try {
+		// Create through the CLI, then retain exactly this original secret for
+		// every authentication probe. No replacement secret is ever requested.
+		const description = 'First description line.\nSecond description line with enough text to exercise the dedicated display box.';
+		const created = json(['key', 'create', '--title', title, '--description', description, '--active', 'true']);
+		const id = created.api_key.id;
+		const secret = created.plain_key;
+		
+		await verify(typeof secret === 'string' && secret.length > 0, 'Created disposable key with a plaintext secret');
+		
+		const detail = xy(['key', id]);
+		await verify(/APP DESCRIPTION[\s\S]*First description line\.[\s\S]*Second description line/.test(detail), 'App description has its own multiline section');
+		await verify(!/│ Description\s*:/.test(detail.split('APP DESCRIPTION')[0]), 'App description is omitted from the summary box');
+		
+		await verify((await authenticate(secret)).code === 0, 'Original secret authenticates before export');
+		
+		for (const extension of ['json', 'json.gz']) {
+			const filename = Path.join(temp, 'key.' + extension);
+			const exported = json(['key', id, '--export', filename]);
+			const bytes = fs.readFileSync(filename);
+			const text = (extension.endsWith('.gz') ? zlib.gunzipSync(bytes) : bytes).toString();
+			const payload = JSON.parse(text);
+			const saved = payload.items[0].data;
+			const expectedHash = crypto.createHash('sha256').update(secret + id).digest('hex');
+			
+			await verify(exported.count === 1 && payload.items[0].type === 'api_key', extension + ': exported API key as XYPDF');
+			
+			await verify(saved.id === id && saved.key === expectedHash && saved.mask === created.api_key.mask, extension + ': export preserves ID, salted hash and mask');
+			
+			await verify(!text.includes(secret) && !('plain_key' in saved), extension + ': export contains no plaintext secret');
+			
+			xy(['key', 'delete', id, '--confirm']);
+			
+			await verify(!(await call('getApiKeys', {})).rows.some(key => key.id === id), extension + ': key deleted');
+			const rejected = await authenticate(secret);
+			
+			await verify(rejected.code !== 0 && /Invalid API Key/i.test(rejected.description || ''), extension + ': original secret rejected after deletion');
+			
+			const preview = json(['import', filename]);
+			
+			await verify(preview.preview === true && preview.items.length === 1 && preview.items[0].operation === 'create', extension + ': import preview plans creation');
+			
+			await verify((await authenticate(secret)).code !== 0, extension + ': preview does not restore access');
+			
+			const imported = json(['import', filename, '--confirm']);
+			
+			await verify(imported.code === 0 && imported.items[0].status === 'created' && imported.items[0].id === id, extension + ': confirmed import recreates original ID');
+			const restored = (await call('getApiKeys', {})).rows.find(key => key.id === id);
+			
+			await verify(restored && restored.key === saved.key && restored.mask === saved.mask && !!restored.active, extension + ': restored credential fields and active state match');
+			
+			await verify((await authenticate(secret)).code === 0, extension + ': SAME original plaintext secret authenticates after import');
+		}
+		
+		const now = (await call('getApiKeys', {})).rows.filter(key => key.title !== title);
+		
+		await verify(JSON.stringify(now) === JSON.stringify(original), 'Existing API key definitions unchanged');
+	}
+	finally {
+		await cleanupFixtures([
+			{ list: 'api_keys', method: 'deleteApiKey', match: item => item.title === title }
+		]);
+	}
+});