@pixlcore/xycli 1.0.0

package/lib/categories.js

@@ -0,0 +1,323 @@
+// Event Categories Layer
+
+const cli = require('pixl-cli');
+const Tools = cli.Tools;
+
+module.exports = {
+	
+	async cmd_categories() {
+		// The plural command always lists categories, with optional filters.
+		await this.cmd_get_categories();
+	},
+	
+	async cmd_category() {
+		// Route category operations, or treat a bare ID or title as a detail lookup.
+		var cmd = this.args.other.shift();
+		if (!cmd) return this.dieUsage('category');
+		switch (cmd) {
+			case 'list': await this.cmd_get_categories(); break;
+			case 'get': await this.cmd_get_category(); break;
+			case 'create': await this.cmd_create_category(); break;
+			case 'update': await this.cmd_update_category(); break;
+			case 'delete': await this.cmd_delete_category(); break;
+			default:
+				this.args.other.unshift(cmd);
+				await this.cmd_get_category();
+			break;
+		}
+	},
+	
+	async cmd_get_categories() {
+		// Load shared state for event counts and the established display helpers.
+		this.prepSearchArgs();
+		await this.getMultiple();
+		var categories = this.categories.slice(0);
+		var is_filtered = !!this.args.other.length;
+		if (is_filtered) {
+			var search = this.args.other.join(' ');
+			categories = this.findObjectsFuzzy(categories, { id: search, title: search, notes: search }, 1);
+		}
+		delete this.args.other;
+		
+		if ('enabled' in this.args) {
+			var enabled = this.parseCategoryBoolean(this.args.enabled, 'enabled');
+			categories = categories.filter( category => !!category.enabled === enabled );
+			delete this.args.enabled;
+			is_filtered = true;
+		}
+		if (Tools.numKeys(this.args)) {
+			categories = this.findObjectsFuzzy(categories, this.args);
+			is_filtered = true;
+		}
+		
+		// Preserve the same category ordering used by the web UI and event lists.
+		categories.sort( function(a, b) {
+			return ((a.sort_order || 0) - (b.sort_order || 0)) || String(a.title).localeCompare(String(b.title));
+		});
+		if (this.format.match(/json/)) return this.jsonOutput(categories);
+		
+		var counts = {};
+		this.events.forEach( event => { counts[event.category] = (counts[event.category] || 0) + 1; } );
+		this.printPaginatedBoxTable({
+			title: is_filtered ? 'Filtered Categories' : 'All Categories',
+			header: ['Category ID', 'Title', 'Status', 'Events', 'Author', 'Modified'],
+			rows: categories.slice(this.offset, this.offset + this.limit),
+			list: { length: categories.length },
+			offset: this.offset,
+			limit: this.limit
+		}, category => [
+			this.color('theme').bold(category.id),
+			this.getNiceCategory(category),
+			this.getNiceEnabled(category.enabled),
+			Tools.commify(counts[category.id] || 0),
+			category.username || gray('(Unknown)'),
+			this.getRelativeDateTime(category.modified, true)
+		]);
+		
+		this.printSuggestedCommands({
+			"View category details": "xy category CAT_ID_OR_TITLE",
+			"Create a category": 'xy category create --title "My Category" --notes "Hello"',
+			"List disabled categories": "xy categories --enabled false",
+			"List category events": "xy events --category CAT_ID"
+		});
+	},
+	
+	async cmd_get_category() {
+		// Read-only selection accepts an exact ID first, then a fuzzy title.
+		await this.getMultiple();
+		var selector = this.args.other.join(' ') || this.args.id || this.args.title;
+		if (!selector) return this.dieUsage('category get');
+		var match = Tools.findObject(this.categories, { id: selector }) ||
+			this.findObjectFuzzy(this.categories, { title: selector });
+		if (!match) return this.die("Could not find category based on your criteria: " + selector);
+		var category = await this.fetchCategory(match.id);
+		if (this.format.match(/json/)) return this.jsonOutput(category);
+		
+		this.printBoxList({
+			title: 'Category Summary',
+			rows: [
+				[ 'Category ID', gray(category.id) ],
+				[ 'Title', this.getNiceCategory(category) ],
+				[ 'Status', this.getNiceEnabled(category.enabled) ],
+				[ 'Color', category.color || 'plain' ],
+				[ 'Icon', category.icon || gray('(None)') ],
+				[ 'Events', Tools.commify(Tools.findObjects(this.events, { category: category.id }).length) ],
+				[ 'Sort Order', category.sort_order || 0 ],
+				[ 'Author', category.username || gray('(Unknown)') ],
+				[ 'Created', this.getNiceDateTime(category.created, true, true) ],
+				[ 'Modified', this.getNiceDateTime(category.modified, true, true) ],
+				[ 'Revision', category.revision || 1 ]
+			]
+		});
+		
+		// User notes may contain multiple lines, so keep them out of the summary box.
+		if (category.notes) {
+			this.printUserNotes('CATEGORY NOTES', category.notes);
+		}
+		
+		// Display only the category's own arrays so indexes map to update paths.
+		// Descriptions and disabled styling mirror the event detail tables.
+		this.printBoxTable({
+			title: 'Category Actions',
+			header: ['#', 'Status', 'Condition', 'Type', 'Description'],
+			rows: (category.actions || []).map( (item, idx) => {
+				var disp = this.getJobActionDisplayArgs(item);
+				return [
+					idx,
+					this.getNiceEnabled(item.enabled),
+					item.enabled ? this.color(disp.condition.color).bold(disp.condition.title) : gray(disp.condition.title),
+					item.enabled ? disp.type : gray(disp.type),
+					item.enabled ? disp.desc : gray(disp.desc)
+				];
+			})
+		});
+		this.printBoxTable({
+			title: 'Category Limits',
+			header: ['#', 'Status', 'Limit', 'Description'],
+			rows: (category.limits || []).map( (item, idx) => {
+				var disp = this.getResLimitDisplayArgs(item);
+				return [
+					idx,
+					this.getNiceEnabled(item.enabled),
+					item.enabled ? bold(disp.nice_title) : gray(disp.nice_title),
+					item.enabled ? disp.nice_desc : gray(disp.nice_desc)
+				];
+			})
+		});
+		this.printSuggestedCommands({
+			"List category events": `xy events --category ${category.id}`,
+			"Export category": `xy category ${category.id} --export category.json`,
+			"Update category": `xy category update ${category.id} --notes "Updated notes"`,
+			"Append an action": `xy category update ${category.id} --action @action.json`,
+			"Append a limit": `xy category update ${category.id} --limit @limit.json`,
+			"Delete category": `xy category delete ${category.id}`
+		});
+	},
+	
+	async cmd_create_category() {
+		// Defaults match the web editor.  The server assigns ID and audit fields.
+		if (this.args.other.length) return this.dieUsage('category create');
+		delete this.args.other;
+		var params = this.prepareCategoryParams({
+			enabled: true,
+			color: 'plain',
+			icon: '',
+			notes: '',
+			actions: [],
+			limits: []
+		}, this.args, true);
+		if (!params.title) return this.dieUsage('category create');
+		
+		var data = await this.callStandardAPI('createCategory', params, { text: 'Creating category...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data.category);
+		this.toast('✅', 'green', "Successfully created category: #" + data.category.id);
+		this.printSuggestedCommands({
+			"View category details": `xy category ${data.category.id}`,
+			"Update category": `xy category update ${data.category.id} --enabled false`,
+			"Create an event": `xy event create --title "My Event" --category ${data.category.id}`,
+			"List all categories": "xy categories"
+		});
+	},
+	
+	async cmd_update_category() {
+		// Fetch by exact ID so nested changes preserve untouched array entries.
+		var id = this.consumeCategoryID();
+		var category = await this.fetchCategory(id);
+		
+		this.printMutationSummary({
+			title: 'Update Category',
+			rows: [
+				[ 'Category ID', gray(category.id) ],
+				[ 'Title', this.color('theme').bold(category.title) ]
+			]
+		});
+		if (!await this.confirmSyncUpdate('category', category.id, 'category')) return;
+		if (!Tools.numKeys(this.args)) return this.die("No updates specified for category.");
+		this.printUpdateData(this.args);
+		
+		var params = this.prepareCategoryParams(category, this.args, false);
+		params.id = id;
+		var data = await this.callStandardAPI('updateCategory', params, { text: 'Updating category...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data);
+		this.toast('✅', 'green', "Successfully updated category: #" + id);
+	},
+	
+	async cmd_delete_category() {
+		// The server also refuses deletion while any event uses this category.
+		var id = this.consumeCategoryID();
+		var category = await this.fetchCategory(id);
+		
+		this.printMutationSummary({
+			title: 'Delete Category',
+			rows: [
+				[ 'Category ID', gray(category.id) ],
+				[ 'Title', this.color('theme').bold(category.title) ]
+			]
+		});
+		
+		if (this.args.confirm !== true) {
+			this.toast('⚠️', 'orange', "Please confirm the category delete by adding '--confirm'.");
+			return;
+		}
+		
+		delete this.args.confirm;
+		if (Tools.numKeys(this.args)) return this.die("Unsupported category delete option: --" + Tools.firstKey(this.args));
+		var data = await this.callStandardAPI('deleteCategory', { id: id }, { text: 'Deleting category...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data);
+		this.toast('✅', 'green', "Successfully deleted category: #" + id);
+	},
+	
+	async fetchCategory(id) {
+		// Use the single-resource API for authoritative metadata and access checks.
+		cli.progress.start({ amount: 1, pct: false, text: gray('→ Loading category...') });
+		var { err, data } = await this.api.getCategory({ id: id });
+		cli.progress.end();
+		if (err) this.die(err);
+		return data.category;
+	},
+	
+	consumeCategoryID() {
+		// Updates and deletes never select by title, and cannot change the ID.
+		var id = this.args.other.shift() || this.args.id;
+		if (!id) this.die("Missing required Category ID argument.");
+		if (this.args.other.length) this.die("Unexpected argument after Category ID: " + this.args.other[0]);
+		if (this.args.id && (this.args.id !== id)) this.die("Conflicting Category ID arguments.");
+		if ((typeof(id) != 'string') || !id.match(/^[a-z0-9_]+$/)) this.die("Invalid Category ID: " + id);
+		delete this.args.other;
+		delete this.args.id;
+		return id;
+	},
+	
+	prepareCategoryParams(category, input, creating) {
+		// Only send edited top-level fields.  In particular, a notes-only update
+		// should not rewrite actions, limits, sort order, or server audit metadata.
+		var params = creating ? Tools.copyHash(category, true) : {};
+		var fields = ['title', 'enabled', 'color', 'icon', 'notes', 'actions', 'limits', 'action', 'limit'];
+		fields.push(creating ? 'id' : 'sort_order');
+		Object.keys(input).forEach( key => {
+			var root = key.split('.')[0];
+			if (!fields.includes(root)) this.die("Unsupported category option: --" + key);
+			if (key.includes('.') && !['actions', 'limits', 'action', 'limit'].includes(root)) {
+				this.die("Invalid argument path: " + key);
+			}
+			var field = (root == 'action') ? 'actions' : ((root == 'limit') ? 'limits' : root);
+			if (!creating && (field in category)) params[field] = Tools.copyHash({ value: category[field] }, true).value;
+		});
+		
+		// Apply whole values before dotted edits, regardless of CLI option 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);
+		
+		// Match event convenience syntax: plural arrays replace, singular objects
+		// append.  Repeated singular flags are also accepted for batch additions.
+		['action', 'limit'].forEach( singular => {
+			var plural = singular + 's';
+			if (singular in params) {
+				if (!(plural in params)) params[plural] = [];
+				if (!Array.isArray(params[plural])) this.die("Category " + plural + " must be a JSON array.");
+				Tools.alwaysArray(params[singular]).forEach( item => {
+					// Repeated options arrive as an array of unparsed JSON strings.
+					if (typeof(item) == 'string') {
+						try { item = JSON.parse(item); }
+						catch (err) { this.die("Category --" + singular + " must contain a JSON object."); }
+					}
+					if (!Tools.isaHash(item)) this.die("Category --" + singular + " must contain a JSON object.");
+					params[plural].push(item);
+				});
+				delete params[singular];
+			}
+			if (plural in params) {
+				if (!Array.isArray(params[plural])) this.die("Category " + plural + " must be a JSON array.");
+				params[plural].forEach( (item, idx) => {
+					if (!Tools.isaHash(item)) this.die("Category " + plural + "." + idx + " must be a JSON object.");
+					if ('enabled' in item) item.enabled = this.parseCategoryBoolean(item.enabled, plural + '.' + idx + '.enabled');
+				});
+			}
+		});
+		
+		if ('title' in params) {
+			if ((typeof(params.title) != 'string') || !params.title.trim()) this.die("Category title cannot be empty and must be a string.");
+			params.title = params.title.trim();
+		}
+		if ('enabled' in params) params.enabled = this.parseCategoryBoolean(params.enabled, 'enabled');
+		['color', 'icon', 'notes'].forEach( key => {
+			if ((key in params) && (typeof(params[key]) != 'string')) this.die("Category " + key + " must be a string.");
+		});
+		if (('id' in params) && ((typeof(params.id) != 'string') || !params.id.match(/^[a-z0-9_]+$/))) this.die("Invalid Category ID: " + params.id);
+		if (('sort_order' in params) && (!Number.isInteger(params.sort_order) || (params.sort_order < 0))) this.die("Category sort_order must be a non-negative integer.");
+		return params;
+	},
+	
+	parseCategoryBoolean(value, name) {
+		// Include numeric and friendly boolean spellings used by other resources.
+		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);
+	}
+	
+}; // module.exports

package/lib/channels.js

@@ -0,0 +1,290 @@
+// Notification Channels Layer
+
+const cli = require('pixl-cli');
+const Tools = cli.Tools;
+
+module.exports = {
+	
+	async cmd_channels() {
+		// The plural command lists channels, with optional search and filters.
+		await this.cmd_get_channels();
+	},
+	
+	async cmd_channel() {
+		// Use the same operation names as categories, buckets, and API Keys.
+		var cmd = this.args.other.shift();
+		if (!cmd) return this.dieUsage('channel');
+		switch (cmd) {
+			case 'list': await this.cmd_get_channels(); break;
+			case 'get': await this.cmd_get_channel(); break;
+			case 'create': await this.cmd_create_channel(); break;
+			case 'update': await this.cmd_update_channel(); break;
+			case 'delete': await this.cmd_delete_channel(); break;
+			default:
+				// A bare ID or title opens channel details.
+				this.args.other.unshift(cmd);
+				await this.cmd_get_channel();
+			break;
+		}
+	},
+	
+	async cmd_get_channels() {
+		// Consume pagination before turning the remaining options into filters.
+		this.prepSearchArgs();
+		await this.getMultiple();
+		var channels = this.channels.slice(0);
+		var is_filtered = !!this.args.other.length;
+		if (is_filtered) {
+			var search = this.args.other.join(' ');
+			channels = this.findObjectsFuzzy(channels, { id: search, title: search, notes: search, email: search }, 1);
+		}
+		delete this.args.other;
+		
+		if ('enabled' in this.args) {
+			var enabled = this.parseChannelBoolean(this.args.enabled);
+			channels = channels.filter( channel => !!channel.enabled === enabled );
+			delete this.args.enabled;
+			is_filtered = true;
+		}
+		if ('user' in this.args) {
+			// User filters match whole usernames, not substrings of other users.
+			var users = this.parseChannelUsers(this.args.user);
+			channels = channels.filter( channel => users.every( user => (channel.users || []).includes(user) ) );
+			delete this.args.user;
+			is_filtered = true;
+		}
+		if (Tools.numKeys(this.args)) {
+			channels = this.findObjectsFuzzy(channels, this.args);
+			is_filtered = true;
+		}
+		channels.sort( (a, b) => String(a.title).toLowerCase().localeCompare(String(b.title).toLowerCase()) );
+		if (this.format.match(/json/)) return this.jsonOutput(channels);
+		
+		this.printPaginatedBoxTable({
+			title: is_filtered ? 'Filtered Notification Channels' : 'All Notification Channels',
+			header: ['Channel ID', 'Title', 'Status', 'Users', 'Daily Cap', 'Modified'],
+			rows: channels.slice(this.offset, this.offset + this.limit),
+			list: { length: channels.length },
+			offset: this.offset,
+			limit: this.limit
+		}, channel => [
+			this.color('theme').bold(channel.id),
+			bold(this.getNiceChannel(channel)),
+			this.getNiceEnabled(channel.enabled),
+			Tools.commify((channel.users || []).length),
+			channel.max_per_day ? Tools.commify(channel.max_per_day) : gray('Unlimited'),
+			this.getRelativeDateTime(channel.modified, true)
+		]);
+		this.printSuggestedCommands({
+			"View channel details": "xy channel CHANNEL_ID_OR_TITLE",
+			"Create a channel": 'xy channel create --title "My Channel" --users admin',
+			"List disabled channels": "xy channels --enabled false",
+			"Find channels for a user": "xy channels --user admin"
+		});
+	},
+	
+	async cmd_get_channel() {
+		// Prefer an exact ID before falling back to a case-insensitive title match.
+		await this.getMultiple();
+		var selector = this.args.other.join(' ') || this.args.id || this.args.title;
+		if (!selector) return this.dieUsage('channel get');
+		var match = Tools.findObject(this.channels, { id: selector }) || this.findObjectFuzzy(this.channels, { title: selector });
+		if (!match) return this.die("Could not find channel based on your criteria: " + selector);
+		var channel = await this.fetchChannel(match.id);
+		if (this.format.match(/json/)) return this.jsonOutput(channel);
+		
+		this.printBoxList({
+			title: 'Channel Summary',
+			rows: [
+				[ 'Channel ID', gray(channel.id) ],
+				[ 'Title', this.color('theme').bold(channel.title) ],
+				[ 'Status', this.getNiceEnabled(channel.enabled) ],
+				[ 'Icon', channel.icon || gray('(None)') ],
+				[ 'Users', (channel.users || []).join(', ') || gray('(None)') ],
+				[ 'Email', channel.email || gray('(None)') ],
+				[ 'Web Hook', channel.web_hook ? this.getNiceWebHook(channel.web_hook) + gray(' (' + channel.web_hook + ')') : gray('(None)') ],
+				[ 'Run Event', channel.run_event ? this.getNiceEvent(channel.run_event) + gray(' (' + channel.run_event + ')') : gray('(None)') ],
+				[ 'Sound', channel.sound || gray('(None)') ],
+				[ 'Daily Cap', channel.max_per_day ? Tools.commify(channel.max_per_day) : 'Unlimited' ],
+				[ 'Author', channel.username || gray('(Unknown)') ],
+				[ 'Created', this.getNiceDateTime(channel.created, true, true) ],
+				[ 'Modified', this.getNiceDateTime(channel.modified, true, true) ],
+				[ 'Revision', channel.revision || 1 ]
+			]
+		});
+		
+		// User notes may contain multiple lines, so keep them out of the summary box.
+		if (channel.notes) {
+			this.printUserNotes('CHANNEL NOTES', channel.notes);
+		}
+		
+		this.printSuggestedCommands({
+			"Update channel": `xy channel update ${channel.id} --max_per_day 100`,
+			"Export channel": `xy channel ${channel.id} --export channel.json`,
+			"Append a user": `xy channel update ${channel.id} --user USERNAME`,
+			"Disable channel": `xy channel update ${channel.id} --enabled false`,
+			"Delete channel": `xy channel delete ${channel.id}`
+		});
+	},
+	
+	async cmd_create_channel() {
+		// Match the web editor defaults, including unlimited daily notifications.
+		if (this.args.other.length) return this.dieUsage('channel create');
+		delete this.args.other;
+		
+		var params = this.prepareChannelParams({
+			enabled: true,
+			icon: '',
+			users: [],
+			email: '',
+			web_hook: '',
+			run_event: '',
+			sound: '',
+			max_per_day: 0,
+			notes: ''
+		}, this.args, true);
+		
+		if (!params.title) return this.dieUsage('channel create');
+		var data = await this.callStandardAPI('createChannel', params, { text: 'Creating notification channel...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data.channel);
+		
+		this.toast('✅', 'green', "Successfully created notification channel: #" + data.channel.id);
+		
+		this.printSuggestedCommands({
+			"View channel details": `xy channel ${data.channel.id}`,
+			"Update channel": `xy channel update ${data.channel.id} --max_per_day 100`,
+			"Use in an event": `xy event update EVENT_ID --action '{ "type":"channel", "enabled":true, "condition":"error", "channel_id":"${data.channel.id}" }'`,
+			"List all channels": "xy channels"
+		});
+	},
+	
+	async cmd_update_channel() {
+		// Load the current channel for indexed edits and appending subscribed users.
+		var id = this.consumeChannelID();
+		var channel = await this.fetchChannel(id);
+		
+		this.printMutationSummary({
+			title: 'Update Channel',
+			rows: [
+				[ 'Channel ID', gray(channel.id) ],
+				[ 'Title', this.color('theme').bold(channel.title) ]
+			]
+		});
+		if (!await this.confirmSyncUpdate('channel', channel.id, 'notification channel')) return;
+		if (!Tools.numKeys(this.args)) return this.die("No updates specified for notification channel.");
+		this.printUpdateData(this.args);
+		
+		var params = this.prepareChannelParams(channel, this.args, false);
+		params.id = id;
+		var data = await this.callStandardAPI('updateChannel', params, { text: 'Updating notification channel...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data);
+		this.toast('✅', 'green', "Successfully updated notification channel: #" + id);
+	},
+	
+	async cmd_delete_channel() {
+		// Deleting the definition does not remove references from existing actions.
+		var id = this.consumeChannelID();
+		var channel = await this.fetchChannel(id);
+		
+		this.printMutationSummary({
+			title: 'Delete Channel',
+			rows: [
+				[ 'Channel ID', gray(channel.id) ],
+				[ 'Title', this.color('theme').bold(channel.title) ]
+			]
+		});
+		
+		if (this.args.confirm !== true) {
+			this.toast('⚠️', 'orange', "Please confirm the channel delete by adding '--confirm'.");
+			return;
+		}
+		delete this.args.confirm;
+		if (Tools.numKeys(this.args)) return this.die("Unsupported channel delete option: --" + Tools.firstKey(this.args));
+		var data = await this.callStandardAPI('deleteChannel', { id: id }, { text: 'Deleting channel...' });
+		if (this.dry) return;
+		if (this.format.match(/json/)) return this.jsonOutput(data);
+		this.toast('✅', 'green', "Successfully deleted channel: #" + id);
+	},
+	
+	async fetchChannel(id) {
+		// Fetch authoritative metadata through the single-channel endpoint.
+		cli.progress.start({ amount: 1, pct: false, text: gray('→ Loading channel...') });
+		var { err, data } = await this.api.getChannel({ id: id });
+		cli.progress.end();
+		if (err) this.die(err);
+		return data.channel;
+	},
+	
+	consumeChannelID() {
+		// Mutation selectors are exact IDs and cannot silently replace each other.
+		var id = this.args.other.shift() || this.args.id;
+		if (!id) this.die("Missing required Channel ID argument.");
+		if (this.args.other.length) this.die("Unexpected argument after Channel ID: " + this.args.other[0]);
+		if (this.args.id && (this.args.id !== id)) this.die("Conflicting Channel ID arguments.");
+		if ((typeof(id) != 'string') || !id.match(/^[a-z0-9_]+$/)) this.die("Invalid Channel ID: " + id);
+		delete this.args.id;
+		delete this.args.other;
+		return id;
+	},
+	
+	prepareChannelParams(channel, input, creating) {
+		// Send only the fields being edited, leaving audit fields and unrelated
+		// settings untouched.  Only the users array supports indexed updates.
+		var params = creating ? Tools.copyHash(channel, true) : {};
+		var fields = ['title', 'enabled', 'icon', 'users', 'user', 'email', 'web_hook', 'run_event', 'sound', 'max_per_day', 'notes'];
+		if (creating) fields.push('id');
+		var dotted = {};
+		Object.keys(input).forEach( key => {
+			var root = key.split('.')[0];
+			if (!fields.includes(root)) this.die("Unsupported channel option: --" + key);
+			if (key.includes('.')) {
+				if (root != 'users') this.die("Invalid argument path: " + key);
+				dotted[key] = input[key];
+			}
+			else params[key] = input[key];
+		});
+		
+		// Whole-list replacement precedes indexed edits, then --user appends.
+		// Clone the saved array so preparing a dry run cannot change shared state.
+		if (('users' in input) || ('user' in input) || Tools.numKeys(dotted)) {
+			params.users = this.parseChannelUsers(('users' in input) ? input.users : (channel.users || []));
+			this.mergeDotArgs(params, dotted);
+			if ('user' in input) params.users = params.users.concat(this.parseChannelUsers(input.user));
+			params.users = Array.from(new Set(this.parseChannelUsers(params.users)));
+		}
+		delete params.user;
+		
+		if ('title' in params) {
+			if ((typeof(params.title) != 'string') || !params.title.trim()) this.die("Channel title cannot be empty and must be a string.");
+			params.title = params.title.trim();
+		}
+		if ('enabled' in params) params.enabled = this.parseChannelBoolean(params.enabled);
+		['icon', 'email', 'web_hook', 'run_event', 'sound', 'notes'].forEach( key => {
+			if ((key in params) && (typeof(params[key]) != 'string')) this.die("Channel " + key + " must be a string.");
+		});
+		if (('id' in params) && ((typeof(params.id) != 'string') || !params.id.match(/^[a-z0-9_]+$/))) this.die("Invalid Channel ID: " + params.id);
+		if (('max_per_day' in params) && (!Number.isSafeInteger(params.max_per_day) || (params.max_per_day < 0))) this.die("Channel max_per_day must be a non-negative integer.");
+		if (params.sound && !params.sound.match(/^[\w.-]+\.mp3$/i)) this.die("Channel sound must be an .mp3 filename, or an empty string.");
+		return params;
+	},
+	
+	parseChannelUsers(value) {
+		// Support a JSON array, comma-separated usernames, and repeated --user.
+		var users = Array.isArray(value) ? value.slice(0) : ((typeof(value) == 'string') ? value.split(',') : null);
+		if (!users) this.die("Channel users must be a JSON array or comma-separated usernames.");
+		return users.map( user => {
+			if ((typeof(user) != 'string') || !user.trim() || /\s/.test(user.trim())) this.die("Channel usernames must be non-empty strings without whitespace.");
+			return user.trim();
+		});
+	},
+	
+	parseChannelBoolean(value) {
+		// Accept the usual boolean and numeric spellings without truthy strings.
+		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 'enabled': " + value);
+	}
+	
+}; // module.exports