@pixlcore/xycli 1.0.0

package/lib/config.js

@@ -0,0 +1,86 @@
+// Config Layer
+
+const fs = require('fs');
+const Path = require('path');
+const cli = require('pixl-cli');
+const Tools = cli.Tools;
+const chalk = cli.chalk;
+
+module.exports = {
+	
+	loadConfig() {
+		// handle loading config at startup
+		// optional config files, sync with env, two-way
+		var config = {};
+		var config_files = this.configFiles = [
+			Path.join( '/etc', 'xyops', 'cli.json' ),
+			Path.join( process.env.HOME, '.config', 'xyops', 'cli.json' )
+		];
+		
+		config_files.forEach( function(file) {
+			if (!fs.existsSync(file)) return;
+			Tools.mergeHashInto( config, JSON.parse(fs.readFileSync(file, 'utf8')) );
+		} );
+		
+		for (var ekey in process.env) {
+			if (ekey.match(/^XYOPS_(\w+)$/)) {
+				var key = RegExp.$1.toLowerCase();
+				var value = process.env[ekey];
+				if (value === "true") value = true;
+				else if (value === "false") value = false;
+				else if (String(value).match(/^\-?\d+(\.\d+)?$/)) value = parseFloat(value);
+				else if (String(value).match(/^\-?\d+$/)) value = parseInt(value);
+				config[key] = value;
+			}
+		}
+		
+		for (var key in config) {
+			process.env['XYOPS_' + key.toUpperCase()] = '' + config[key];
+		}
+		
+		this.config = config;
+	},
+	
+	async cmd_config() {
+		// allow user to view config, and also modify it
+		delete this.args.other;
+		
+		if (!Tools.firstKey(this.args)) {
+			// just print config and exit
+			println( "\n " + this.color('theme').bold( 'CONFIGURATION SOURCES:' ) + "\n" );
+			this.configFiles.forEach( function(file) {
+				println( bold.green("    • ") + file );
+			} );
+			println( bold.green("    • ") + "(XYOPS_ prefixed env vars)" );
+			
+			println( "\n " + this.color('theme').bold( 'CURRENT CONFIGURATION:' ) );
+			var temp_config = { ...this.config };
+			if (temp_config.api_key) temp_config.api_key = this.maskValue(temp_config.api_key);
+			this.jsonOutput(temp_config);
+			return;
+		}
+		
+		// Reload only the user's settings before applying changes.  The effective
+		// configuration also contains system settings and environment overrides,
+		// which must not be copied into the user's file when saving preferences.
+		var dest_file = this.configFiles[this.configFiles.length - 1];
+		var user_config = fs.existsSync(dest_file) ? JSON.parse(fs.readFileSync(dest_file, 'utf8')) : {};
+		
+		// Apply only the supplied arguments, preserving other user settings.
+		print("\n");
+		for (var key in this.args) {
+			var value = (key == 'api_key') ? this.maskValue(this.args[key]) : this.args[key];
+			println( " " + bold.cyan("Setting key: ") + bold.green(key) + ": " + JSON.stringify(value) );
+			
+			if (!this.setPath(user_config, key, this.args[key])) {
+				this.die("Invalid configuration path: " + key);
+			}
+		}
+		
+		Tools.mkdirpSync( Path.dirname(dest_file) );
+		println( "\n " + bold.cyan("Writing to: ") + dest_file );
+		fs.writeFileSync( dest_file, JSON.stringify(user_config, null, "\t") + "\n", { mode: 0o600 } );
+		fs.chmodSync(dest_file, 0o600);
+	}
+	
+};

package/lib/dashboard.js

@@ -0,0 +1,237 @@
+// Dashboard Layer
+
+const cli = require('pixl-cli');
+const Tools = cli.Tools;
+const chalk = cli.chalk;
+
+module.exports = {
+	
+	async cmd_dashboard() {
+		// show dashboard
+		await this.getMultiple();
+		
+		var stats = this.stats;
+		var day = stats.currentDay || { transactions: {} };
+		var trans = day.transactions || {};
+		
+		// calculate total CPU usage
+		var total_cpu = 0;
+		
+		// add CPU for all active jobs (avg)
+		for (var job_id in this.activeJobs) {
+			var job = this.activeJobs[job_id];
+			if (job.cpu && job.cpu.total && job.cpu.count) {
+				total_cpu += job.cpu.total / job.cpu.count;
+			}
+		}
+		
+		// calculate total memory usage
+		var total_mem = 0;
+		
+		// add mem for all jobs (avg)
+		for (var job_id in this.activeJobs) {
+			var job = this.activeJobs[job_id];
+			if (job.mem && job.mem.total && job.mem.count) {
+				total_mem += job.mem.total / job.mem.count;
+			}
+		}
+		
+		println( "\n " + this.color('theme').bold("MAIN DASHBOARD") );
+		println( "" + dashGrid([
+			[ "Conductors", Tools.numKeys(this.masters) ],
+			[ "Servers", Tools.numKeys(this.servers) ],
+			[ "Current Alerts", Tools.numKeys(this.activeAlerts) ],
+			[ "Active Jobs", Tools.numKeys(this.activeJobs) ],
+			[ "Jobs Today", Tools.commify(trans.job_complete || 0) ],
+			[ "Jobs Failed Today", Tools.commify(trans.job_error || 0) ],
+			[ "Job Success Rate", Tools.pct( (trans.job_success || 0) / (trans.job_complete || 1) ) ],
+			[ "Avg Job Elapsed", Tools.getTextFromSeconds( Math.round( (trans.job_elapsed || 0) / (trans.job_complete || 1) ), true, true ) ],
+			[ "Avg Job Output", Tools.getTextFromBytes( Math.round( (trans.job_log_file_size || 0) / (trans.job_complete || 1) ) ).replace(/bytes/, 'B') ],
+			[ "Job CPU Usage", Tools.pct( Math.round(total_cpu || 0), 100 ) ],
+			[ "Job Mem Usage", Tools.getTextFromBytes(total_mem, 1).replace(/bytes/, 'B') ],
+			[ "Uptime", Tools.getTextFromSeconds( stats.started ? (this.epoch - stats.started) : 0, true, true ) ],
+			[ "Scheduler", this.getNiceEnabled(this.state.scheduler.enabled) ],
+			[ "Server Time", this.getNiceTime(this.epoch, true) ]
+		], 
+		{
+			minCols: 3,
+			maxCols: 6,
+			gap: 1,
+			indent: 1,
+			valueStyles: ["bold", "green"]
+		}) );
+		
+		// active alerts
+		this.printActiveAlerts();
+		
+		// active jobs
+		this.printActiveJobs({
+			rows: Object.values(this.activeJobs).sort( function(a, b) {
+				// keep workflow parent jobs directly above their sub-jobs
+				if (b.workflow && (b.workflow.job == a.id)) return -1;
+				if (a.workflow && (a.workflow.job == b.id)) return 1;
+				return (a.started < b.started) ? 1 : -1;
+			} ) 
+		});
+		
+		// internal jobs
+		this.printInternalJobs();
+		
+		// queue summary
+		await this.printQueueSummary();
+		
+		// rate limit summary
+		this.printRateSummary();
+		
+		// aliases
+		switch (this.args.other[0]) {
+			case 'upcoming': this.args.upcoming = true; break;
+			// case 'completed': this.args.completed = true; break;
+		}
+		
+		// upcoming
+		if (this.args.upcoming) {
+			this.prepSearchArgs();
+			await this.printUpcomingJobs();
+		}
+		
+		// completed jobs
+		// if (this.args.completed) {
+		// 	await this.printCompletedJobs();
+		// }
+		
+		this.printSuggestedCommands({
+			"Upcoming jobs": this.args.upcoming ? "" : "xy upcoming",
+			"Completed jobs": "xy jobs",
+			"Event list": "xy events",
+			"Hide suggestions": "xy config --suggest false"
+		});
+	},
+	
+	async printQueueSummary() {
+		// Fetch all visible queued-job groups from the server.
+		cli.progress.start();
+		var { err, data } = await this.api.getQueueSummary();
+		if (err) this.die(err);
+		cli.progress.end();
+		
+		this.queues = data.queues || [];
+		// if (!this.queues.length) return;
+		
+		// Sort queues alphabetically by their effective queue or capacity ID.
+		this.queues.sort( function(a, b) {
+			return String(a.id).toLowerCase().localeCompare( String(b.id).toLowerCase() );
+		} );
+		
+		var source_types = (this.config.ui?.job_source_types) || [];
+		
+		var rows = this.queues.map( queue => {
+			var event_ids = Object.keys(queue.events || {}).sort();
+			var category_ids = Object.keys(queue.categories || {}).sort();
+			var source_ids = Object.keys(queue.sources || {}).sort();
+			var target_ids = Object.keys(queue.targets || {}).sort();
+			
+			var nice_events = event_ids.length ?
+				event_ids.map( this.getNiceEvent.bind(this) ).join(', ') :
+				gray('(None)');
+			
+			var nice_categories = category_ids.length ?
+				category_ids.map( this.getNiceCategory.bind(this) ).join(', ') :
+				gray('(None)');
+			
+			var nice_sources = source_ids.length ? source_ids.map( function(source) {
+				var source_def = Tools.findObject( source_types, { id: source } );
+				return source_def ? source_def.title : Tools.ucfirst(source);
+			} ).join(', ') : gray('(None)');
+			
+			var nice_targets = target_ids.length ? this.getNiceTargets(target_ids) : gray('(None)');
+			
+			return [
+				this.color('theme').bold(queue.id),
+				nice_events,
+				nice_categories,
+				nice_sources,
+				nice_targets,
+				bold(Tools.commify(queue.count || 0))
+			];
+		} );
+		
+		this.printBoxTable({
+			title: 'Job Queues',
+			header: [
+				'Queue ID / Cap Key',
+				'Events',
+				'Categories',
+				'Sources',
+				'Targets',
+				'# Jobs'
+			],
+			rows: rows
+		});
+	},
+	
+	printRateSummary() {
+		// Render all currently active job rate-limit windows.
+		var rates = Object.values(this.jobRateLimits || {});
+		// if (!rates.length) return;
+		
+		// Sort pools alphabetically by their queue or shared-capacity ID.
+		rates.sort( function(a, b) {
+			return String(a.id).toLowerCase().localeCompare( String(b.id).toLowerCase() );
+		} );
+		
+		var rows = rates.map( rate => {
+			var rate_id = String(rate.id || '');
+			var event_id = '';
+			var match = null;
+			
+			// Normal event pool IDs begin with the event ID.
+			match = rate_id.match(/^(e\w+)/);
+			if (match) {
+				event_id = match[1];
+			}
+			else {
+				// Workflow node pools contain the parent workflow job ID.
+				match = rate_id.match(/^n\w+\-(j\w+)/);
+				
+				if (match) {
+					var workflow_job = this.activeJobs[match[1]];
+					if (workflow_job) {
+						event_id = workflow_job.event;
+					}
+				}
+			}
+			
+			var remaining = Math.max( 0, (rate.expires || 0) - this.epoch );
+			
+			return [
+				this.color('theme').bold(rate_id),
+				event_id ? this.getNiceEvent(event_id) : gray('n/a'),
+				Tools.commify(rate.count || 0),
+				Tools.commify(rate.max || 0),
+				Tools.getTextFromSeconds( rate.window || 0, false, true ),
+				this.getTextFromSecondsRound( remaining, false )
+			];
+		} );
+		
+		this.printBoxTable({
+			title: 'Rate Limit Pools',
+			header: [
+				'Pool ID / Cap Key',
+				'Event',
+				'Current Count',
+				'Max Count',
+				'Window Size',
+				'Expires In'
+			],
+			rows: rows
+		});
+	},
+	
+	async cmd_upcoming() {
+		// alias for `xy dashboard --upcoming`
+		this.args.upcoming = true;
+		await this.cmd_dashboard();
+	}
+	
+};

package/lib/doc.js

@@ -0,0 +1,131 @@
+// Documentation Commands
+
+const cli = require('pixl-cli');
+const Tools = cli.Tools;
+const chalk = cli.chalk;
+const gray = chalk.gray;
+
+module.exports = {
+	
+	async cmd_doc() {
+		// Fetch one Markdown document, optionally narrowing it to one complete
+		// chapter before handing it to the shared terminal renderer.
+		var selection = this.consumeDocSelection();
+		
+		cli.progress.start({ amount: 1, pct: false, text: gray('→ Loading documentation...') });
+		var { err, data } = await this.api.getDoc({ doc: selection.doc });
+		cli.progress.end();
+		if (err) this.die(err);
+		if (!data || (typeof(data.text) != 'string')) this.die('Documentation response did not include Markdown text.');
+		
+		var text = data.text;
+		if (selection.chapter) text = this.extractDocChapter(text, selection.doc, selection.chapter);
+		text = this.prepareDocMarkdown(text, selection.doc);
+		println('\n' + this.markdown(text.trim()).trimEnd());
+	},
+	
+	consumeDocSelection() {
+		// Accept either doc/chapter or two positional words.  Keep both portions
+		// deliberately strict because the document name maps to a server-side file.
+		var values = this.args.other.slice(0);
+		delete this.args.other;
+		if (Tools.numKeys(this.args)) this.die('Unsupported documentation option: --' + Tools.firstKey(this.args));
+		if (values.length > 2) return this.dieUsage('doc');
+		
+		var doc = values.length ? String(values.shift()) : 'index';
+		var chapter = values.length ? String(values.shift()) : '';
+		
+		if (doc.includes('/')) {
+			if (chapter) return this.dieUsage('doc');
+			var parts = doc.split('/');
+			if ((parts.length != 2) || !parts[0] || !parts[1]) return this.dieUsage('doc');
+			doc = parts[0];
+			chapter = parts[1];
+		}
+		
+		if (!doc.match(/^\w+$/)) this.die('Invalid documentation name: ' + doc);
+		if (doc.toLowerCase() == 'search') this.die('Documentation search is not supported by this command.');
+		if (chapter && !chapter.match(/^[a-z0-9_-]+$/i)) this.die('Invalid documentation chapter slug: ' + chapter);
+		
+		return { doc: doc.toLowerCase(), chapter: chapter.toLowerCase() };
+	},
+	
+	extractDocChapter(text, doc, chapter) {
+		// Include the selected heading and all of its descendants, stopping only
+		// when the next heading is at the same or a higher document level.
+		var lines = String(text).split(/\r?\n/);
+		var start = -1;
+		var end = lines.length;
+		var level = 0;
+		var fence = '';
+		var slugs = [];
+		
+		for (var idx = 0; idx < lines.length; idx++) {
+			var fence_match = lines[idx].match(/^\s*(`{3,}|~{3,})/);
+			if (fence_match) {
+				var marker = fence_match[1][0];
+				if (!fence) fence = marker;
+				else if (fence == marker) fence = '';
+				continue;
+			}
+			if (fence) continue;
+			
+			var heading = lines[idx].match(/^(#{1,6})[ \t]+(.+?)\s*$/);
+			if (!heading) continue;
+			var title = heading[2].replace(/\s+#+\s*$/, '').trim();
+			var slug = this.getDocHeadingSlug(title);
+			slugs.push(slug);
+			
+			if (start < 0) {
+				if (slug != chapter) continue;
+				start = idx;
+				level = heading[1].length;
+			}
+			else if (heading[1].length <= level) {
+				end = idx;
+				break;
+			}
+		}
+		
+		if (start < 0) {
+			var suggestion = this.findClosestString(chapter, slugs);
+			var message = 'Could not find documentation chapter: ' + doc + '/' + chapter + '.';
+			if (suggestion) message += ' Did you mean "' + doc + '/' + suggestion + '"?';
+			this.die(message);
+		}
+		
+		return lines.slice(start, end).join('\n').trim();
+	},
+	
+	prepareDocMarkdown(text, doc) {
+		// Relative documentation links have no useful destination in a terminal.
+		// Present them as equivalent CLI commands while preserving web links and
+		// leaving example source code completely untouched.
+		var fence = '';
+		return String(text).split(/\r?\n/).map( function(line) {
+			var fence_match = line.match(/^\s*(`{3,}|~{3,})/);
+			if (fence_match) {
+				var marker = fence_match[1][0];
+				if (!fence) fence = marker;
+				else if (fence == marker) fence = '';
+				return line;
+			}
+			if (fence) return line;
+			
+			return line.replace(/\[([^\]\n]+)\]\(([^)\s]+)\)/g, function(all, label, target, offset, source) {
+				if (source[offset - 1] == '!') return all;
+				var match = target.match(/^(?:(\w+)\.md)?(?:#([a-z0-9_-]+))?$/i);
+				if (!match || (!match[1] && !match[2])) return all;
+				var target_doc = (match[1] || doc).toLowerCase();
+				var command = 'xy doc ' + target_doc + (match[2] ? '/' + match[2].toLowerCase() : '');
+				return label + ' (`' + command + '`)';
+			});
+		}).join('\n');
+	},
+	
+	getDocHeadingSlug(title) {
+		// Match the anchor IDs generated by the xyOps documentation page.
+		return String(title).trim().replace(/\W+/g, '-').toLowerCase();
+	}
+	
+}; // module.exports