@arkebcacy/beacon-cli-temp 0.1.1

package/src/ui/command/push.ts

@@ -0,0 +1,100 @@
+import resolveConfig from '#cli/cfg/resolveConfig.js';
+import { createClient } from '#cli/cs/api/Client.js';
+import { Store } from '#cli/schema/lib/SchemaUi.js';
+import pushJob from '#cli/schema/push.js';
+import SchemaOperationError from '#cli/schema/SchemaOperationError.js';
+import createStylus from '#cli/ui/createStylus.js';
+import HandledError from '#cli/ui/HandledError.js';
+import humanizePath from '#cli/ui/humanizePath.js';
+import logApiPerformance from '#cli/ui/logApiPerformance.js';
+import logResults from '#cli/ui/logResults.js';
+import * as Options from '#cli/ui/option/index.js';
+import { ConsoleUiContext } from '#cli/ui/UiContext.js';
+import { Command } from 'commander';
+import { resolve } from 'node:path';
+import logOptions from '../logOptions.js';
+import type { CommonOptions } from '../option/commonOptions.js';
+import { addCommonOptions } from '../option/commonOptions.js';
+
+const push = new Command('push');
+addCommonOptions(push);
+
+push
+	.addOption(Options.deletionStrategy)
+	.addOption(Options.extension)
+	.addOption(Options.jsonRtePlugin)
+	.addOption(Options.schemaPath)
+	.description('Deploy serialized data and schema into a stack.');
+
+type CommandOptions = CommonOptions &
+	Options.DeletionStrategyOption &
+	Options.ExtensionOption &
+	Options.JsonRtePluginOption &
+	Options.SchemaPathOption;
+
+push.action(async (cliOptions: CommandOptions) =>
+	HandledError.ExitIfThrown(async () => {
+		const options = await mapOptions(cliOptions);
+		using ui = new ConsoleUiContext(options);
+		ui.info(logStart(cliOptions, options));
+
+		const { histogram, results } = await Store.run(ui, async () => {
+			await using client = createClient(ui);
+			const r = await pushJob(client);
+			return { histogram: client.performance, results: r };
+		});
+
+		ui.stopAllBars();
+		logResults(ui, results);
+		logApiPerformance(ui, histogram);
+		SchemaOperationError.throwIfFailuresExist(results.values());
+	}),
+);
+
+export default push;
+
+async function mapOptions(options: CommandOptions) {
+	return resolveConfig({
+		client: {
+			apiKey: options.apiKey,
+			baseUrl: options.baseUrl,
+			branch: options.branch,
+			managementToken: options.managementToken,
+			timeout: options.apiTimeout,
+		},
+		configFile: options.configFile,
+		namedEnvironment: options.environment,
+		schema: {
+			deletionStrategy: options.deletionStrategy,
+			extension: options.extension,
+			jsonRtePlugin: options.jsonRtePlugin,
+			schemaPath: options.schemaPath,
+		},
+		verbose: options.verbose,
+	});
+}
+
+function logStart(
+	cliOptions: CommandOptions,
+	options: Awaited<ReturnType<typeof mapOptions>>,
+) {
+	const y = createStylus('yellowBright');
+
+	const parts = [
+		'\nSerializing schema from ',
+		y`${humanizePath(resolve(options.schema.schemaPath))} into`,
+	];
+
+	if (cliOptions.environment) {
+		parts.push(y` ${cliOptions.environment} (${options.client.apiKey})`);
+	} else {
+		parts.push(y` ${options.client.apiKey}`);
+	}
+
+	parts.push(
+		y` on the ${options.client.branch} branch:\n`,
+		logOptions(options),
+	);
+
+	return parts.join('');
+}

package/src/ui/createStylus.ts

@@ -0,0 +1,15 @@
+import { styleText } from 'node:util';
+
+export default function createStylus(format: Parameters<typeof styleText>[0]) {
+	return (strings: readonly string[], ...highlights: readonly string[]) =>
+		strings.reduce((acc, str, i) => {
+			acc += str;
+
+			const highlight = highlights[i];
+			if (typeof highlight === 'string' && highlight.length > 0) {
+				acc += styleText(format, highlight);
+			}
+
+			return acc;
+		}, '');
+}

package/src/ui/humanizeList.ts

@@ -0,0 +1,80 @@
+import createStylus from './createStylus.js';
+
+type Stylus = ReturnType<typeof createStylus>;
+
+export default function humanizeList(
+	items: readonly string[],
+	opts?: {
+		maxWidth?: number;
+		stylus?: ReturnType<typeof createStylus>;
+	},
+): string {
+	const sorted = [...items].sort();
+	const bufferWidth = ', and 1,234 more...'.length;
+	const maxWidth = opts?.maxWidth ?? (process.stdout.columns || Infinity);
+	const limit = maxWidth - bufferWidth;
+	const stylus = opts?.stylus ?? createStylus('yellowBright');
+
+	return (
+		none(sorted) ??
+		one(sorted, limit, stylus) ??
+		two(sorted, limit, stylus) ??
+		many(sorted, limit, stylus)
+	);
+}
+
+function none(sorted: readonly string[]) {
+	if (sorted.length === 0) {
+		return '';
+	}
+}
+
+function one(sorted: readonly string[], limit: number, stylus: Stylus) {
+	if (sorted.length !== 1) {
+		return;
+	}
+
+	return stylus`${String(sorted[0])}`;
+}
+
+function two(sorted: readonly string[], limit: number, stylus: Stylus) {
+	// Justification: Use an alternate grammar when there are only two items.
+	// eslint-disable-next-line @typescript-eslint/no-magic-numbers
+	if (sorted.length !== 2) {
+		return;
+	}
+
+	const first = String(sorted[0]);
+	const second = String(sorted[1]);
+	const visualWidth = first.length + ' and '.length + second.length;
+
+	if (visualWidth > limit) {
+		return stylus`${first} and ${'1'} more`;
+	}
+
+	return stylus`${first} and ${second}`;
+}
+
+function many(sorted: readonly string[], limit: number, stylus: Stylus) {
+	const sepWidth = ', '.length;
+	const listed = [];
+	let visualWidth = 0;
+
+	for (const item of sorted) {
+		visualWidth += item.length + sepWidth;
+
+		if (visualWidth > limit) {
+			break;
+		}
+
+		listed.push(stylus`${item}`);
+	}
+
+	if (listed.length === sorted.length) {
+		return `${listed.slice(0, -1).join(', ')}, and ${listed.slice(-1)[0]}`;
+	}
+
+	const remaining = sorted.length - listed.length;
+	const final = stylus`, and ${remaining.toLocaleString()} more`;
+	return listed.join(', ') + final;
+}

package/src/ui/humanizePath.ts

@@ -0,0 +1,15 @@
+import { relative } from 'node:path';
+
+export default function humanizePath(absolutePath: string) {
+	const relativePath = relative(process.cwd(), absolutePath);
+
+	if (relativePath.startsWith('../')) {
+		return absolutePath;
+	}
+
+	if (relativePath === '') {
+		return '.';
+	}
+
+	return relativePath;
+}

package/src/ui/logApiPerformance.ts

@@ -0,0 +1,118 @@
+import asciichart from 'asciichart';
+import type { Histogram } from 'node:perf_hooks';
+import { styleText } from 'node:util';
+import process from 'process';
+import type UiContext from './UiContext.js';
+import createStylus from './createStylus.js';
+
+const percent = 100;
+
+export default function logApiPerformance(
+	ui: UiContext,
+	histogram: Histogram | undefined,
+) {
+	if (!histogram) {
+		return;
+	}
+
+	const [lowerBound, upperBound] = graphBoundaries(histogram);
+	const numOfBuckets = bucketCount();
+	const bucketSize = Math.ceil((upperBound - lowerBound) / numOfBuckets);
+	const buckets = new Array(numOfBuckets).fill(0) as number[];
+
+	for (let i = 1; i <= histogram.count; i++) {
+		const value = histogram.percentile((i / histogram.count) * percent);
+
+		if (value >= lowerBound && value <= upperBound) {
+			const bucketIndex = Math.min(
+				Math.floor((value - lowerBound) / bucketSize),
+				numOfBuckets - 1,
+			);
+
+			buckets[bucketIndex] = (buckets[bucketIndex] ?? 0) + 1;
+		}
+	}
+
+	const f = new Intl.NumberFormat('en-US', {
+		maximumFractionDigits: 1,
+		minimumFractionDigits: 1,
+		style: 'decimal',
+	});
+
+	const maxBucketSize = Math.max(...buckets);
+	const maxLabelLength = f.format(maxBucketSize).length;
+
+	ui.info(
+		'\n',
+		styleText(['bold', 'underline'], 'API Performance'),
+		'(Y-Axis: Requests; X-Axis: Duration)',
+	);
+
+	ui.info(
+		asciichart.plot(buckets, {
+			format: (yLabel) => ` ${f.format(yLabel).padStart(maxLabelLength)} `,
+			height: 10,
+		}),
+	);
+
+	logSummary(ui, histogram);
+}
+
+function graphBoundaries(histogram: Histogram) {
+	const stdDeviationsToCapture = 2;
+	const stdDeviations = stdDeviationsToCapture * histogram.stddev;
+	const upperBound = Math.min(histogram.max, histogram.mean + stdDeviations);
+	return [histogram.min, upperBound] as const;
+}
+
+function bucketCount() {
+	const defaultColumns = 80;
+	const yAxisSpace = 20;
+	const columns = process.stdout.columns || defaultColumns;
+	const available = columns - yAxisSpace;
+	return Math.max(available, 1);
+}
+
+function logSummary(ui: UiContext, histogram: Histogram) {
+	const y = createStylus('yellowBright');
+
+	const minMax = new Intl.NumberFormat('en-US', {
+		maximumFractionDigits: 0,
+		minimumFractionDigits: 0,
+		style: 'unit',
+		unit: 'millisecond',
+	});
+
+	const avg = new Intl.NumberFormat('en-US', {
+		maximumFractionDigits: 2,
+		minimumFractionDigits: 2,
+		style: 'unit',
+		unit: 'millisecond',
+	});
+
+	const align = (...items: { label: string; value: string }[]) => {
+		const maxLabelLen = Math.max(...items.map(({ label }) => label.length));
+		const maxValueLen = Math.max(...items.map(({ value }) => value.length));
+
+		return items.map(({ label, value }) => {
+			const paddedLabel = label.padEnd(maxLabelLen);
+			const paddedValue = value.padStart(maxValueLen);
+			const styled = styleText('yellowBright', paddedValue);
+			return `${paddedLabel} ${styled}`;
+		});
+	};
+
+	const [max, min] = align(
+		{ label: 'Max:', value: minMax.format(histogram.max) },
+		{ label: 'Min:', value: minMax.format(histogram.min) },
+	);
+
+	const [mean, stdDev] = align(
+		{ label: 'Mean:', value: avg.format(histogram.mean) },
+		{ label: 'StdDev:', value: avg.format(histogram.stddev) },
+	);
+
+	ui.info(y`${histogram.count.toLocaleString()} requests\n`);
+	ui.info(min, '     ', mean);
+	ui.info(max, '     ', stdDev);
+}

package/src/ui/logOptions.ts

@@ -0,0 +1,37 @@
+import createStylus from './createStylus.js';
+import type Options from './Options.js';
+
+export default function logOptions(options: Options) {
+	const b = createStylus('bold');
+	const y = createStylus('yellowBright');
+	const d = createStylus('dim');
+
+	const parts = [
+		b`  - ${'API Url'}: `,
+		y`${options.client.baseUrl.toString()}\n`,
+	];
+
+	parts.push(b`  - ${'Extensions'}:`);
+	if (options.schema.extension.byName.size) {
+		parts.push('\n');
+		for (const [name, uid] of options.schema.extension.byName) {
+			parts.push(y`    - ${name}: ${uid}\n`);
+		}
+	} else {
+		parts.push(d` ${'None'}\n`);
+	}
+
+	parts.push(b`  - ${'JSON RTE Plugins'}:`);
+	if (options.schema.jsonRtePlugin.byName.size) {
+		parts.push('\n');
+		for (const [name, uid] of options.schema.jsonRtePlugin.byName) {
+			parts.push(y`    - ${name}: ${uid}\n`);
+		}
+	} else {
+		parts.push(d` ${'None'}\n`);
+	}
+
+	parts.push(b`  - ${'Verbose'}: `, y`${String(options.verbose)}\n`);
+
+	return parts.join('');
+}

package/src/ui/logResults.ts

@@ -0,0 +1,116 @@
+import type TransferResults from '#cli/schema/xfer/TransferResults.js';
+import { styleText } from 'node:util';
+import createStylus from './createStylus.js';
+import HandledError from './HandledError.js';
+import humanizeList from './humanizeList.js';
+import type UiContext from './UiContext.js';
+
+const terminalWidth = process.stdout.columns || Infinity;
+type OptResults =
+	| ReadonlyMap<string, PromiseSettledResult<TransferResults>>
+	| undefined;
+
+export default function logResults(ui: UiContext, results: OptResults) {
+	const noData = new Set<string>();
+
+	results?.forEach((result, name) => {
+		if (result.status === 'rejected') {
+			const reason =
+				result.reason instanceof Error
+					? result.reason.message
+					: String(result.reason);
+
+			const icon = styleText('redBright', '⚠');
+			const humanName = styleText('yellowBright', name);
+			const humanMsg = styleText('redBright', reason);
+			ui.error(`${icon} Failed to transfer ${humanName}: ${humanMsg}\n`);
+		} else if (!logSectionResults(ui, name, result.value)) {
+			noData.add(name);
+		}
+	});
+
+	logNoData(ui, noData);
+
+	logCollectedErrors(ui, results);
+}
+
+function logSectionResults(
+	ui: UiContext,
+	header: string,
+	results: TransferResults,
+) {
+	const indent = '  ';
+	const sep = ': ';
+	const stylus = createStylus('yellowBright');
+
+	const logSet = (
+		set: ReadonlySet<string> | undefined,
+		action: string,
+		actionStyle: Parameters<typeof styleText>[0] = 'greenBright',
+	) => {
+		if (!set || set.size === 0) {
+			return;
+		}
+
+		const consumedWidth = action.length + sep.length + indent.length;
+		const maxWidth = terminalWidth - consumedWidth;
+		const human = humanizeList([...set], { maxWidth, stylus });
+		return `${indent}${styleText(actionStyle, action)}${sep}${human}.`;
+	};
+
+	const lines = [
+		logSet(results.created, 'Created'),
+		logSet(results.updated, 'Updated'),
+		logSet(results.deleted, 'Deleted'),
+		ui.options.verbose ? logSet(results.unmodified, 'Unmodified') : null,
+		logSet(new Set(results.errored.keys()), 'Errored', 'redBright'),
+	].filter(Boolean);
+
+	const headerLine = `${styleText(['bold', 'underline'], header)}:`;
+
+	if (lines.length === 0) {
+		return false;
+	}
+
+	ui.info([headerLine, ...lines, ''].join('\n'));
+	return true;
+}
+
+function logNoData(ui: UiContext, noData: ReadonlySet<string>) {
+	const stylus = createStylus('dim');
+	const consumedWidth = 'No Data: '.length;
+	const maxWidth = terminalWidth - consumedWidth;
+
+	ui.info(
+		`${styleText(['bold', 'underline'], 'No Data')}:`,
+		humanizeList([...noData], { maxWidth, stylus }),
+	);
+}
+
+function logCollectedErrors(ui: UiContext, results: OptResults) {
+	if (!results) {
+		return;
+	}
+
+	for (const [sectionName, result] of results) {
+		if (result.status === 'rejected') {
+			ui.info(
+				`\nFatal Error in ${sectionName}:`,
+				`[${typeof result.reason}]`,
+				result.reason instanceof HandledError
+					? result.reason.humanized.trimEnd()
+					: result.reason,
+			);
+		} else {
+			for (const [key, error] of result.value.errored) {
+				ui.info(
+					'\nError in',
+					styleText('yellowBright', sectionName),
+					'for',
+					`${styleText('yellowBright', key)}:`,
+					error instanceof HandledError ? error.humanized.trimEnd() : error,
+				);
+			}
+		}
+	}
+}

package/src/ui/option/apiKey.ts

@@ -0,0 +1,13 @@
+import { Option } from 'commander';
+import type Options from '../Options.js';
+import noEmptyStringsFor from '../parser/noEmptyStringsFor.js';
+
+const apiKey = new Option('--api-key [key]', 'Contentstack API key');
+
+apiKey.env('Contentstack_Api_Key').argParser(noEmptyStringsFor('API key'));
+
+export interface ApiKeyOption {
+	readonly apiKey: Options['client']['apiKey'];
+}
+
+export default apiKey;

package/src/ui/option/apiTimeout.ts

@@ -0,0 +1,24 @@
+import { InvalidArgumentError, Option } from 'commander';
+import type Options from '../Options.js';
+
+const apiTimeout = new Option('--api-timeout [ms]', 'Contentstack API timeout');
+
+export const defaultValue = 10000;
+apiTimeout.argParser(timeoutParser).default(defaultValue);
+
+export interface ApiTimeoutOption {
+	readonly apiTimeout: Options['client']['timeout'];
+}
+
+export default apiTimeout;
+
+function timeoutParser(value: string): number {
+	const parsedValue = parseInt(value, 10);
+
+	if (isNaN(parsedValue) || parsedValue <= 0) {
+		const msg = 'Invalid timeout value. Must be a positive number.';
+		throw new InvalidArgumentError(msg);
+	}
+
+	return parsedValue;
+}

package/src/ui/option/baseUrl.ts

@@ -0,0 +1,25 @@
+import { Option } from 'commander';
+import type Options from '../Options.js';
+import noEmptyStringsFor from '../parser/noEmptyStringsFor.js';
+
+const baseUrl = new Option('--base-url [url]', 'Base URL');
+
+// From https://www.contentstack.com/docs/developers/apis/content-management-api
+baseUrl.choices([
+	'https://api.contentstack.io/',
+	'https://eu-api.contentstack.com/',
+	'https://azure-na-api.contentstack.com/',
+	'https://azure-eu-api.contentstack.com/',
+]);
+
+baseUrl
+	.env('Contentstack_Management_API')
+	.argParser(
+		(val: string) => new URL(noEmptyStringsFor('Management API')(val)),
+	);
+
+export interface BaseUrlOption {
+	readonly baseUrl: Options['client']['baseUrl'];
+}
+
+export default baseUrl;

package/src/ui/option/branch.ts

@@ -0,0 +1,17 @@
+import { Option } from 'commander';
+import type Options from '../Options.js';
+
+const branch = new Option('--branch [name]', 'Contentstack Branch');
+
+export const defaultValue = 'main';
+
+branch
+	.env('Contentstack_Branch')
+	.default(defaultValue)
+	.argParser((value) => (value ? value : defaultValue));
+
+export interface BranchOption {
+	readonly branch: Options['client']['branch'];
+}
+
+export default branch;

package/src/ui/option/commonOptions.ts

@@ -0,0 +1,23 @@
+import type { Command } from 'commander';
+import * as Options from './index.js';
+
+export function addCommonOptions(cmd: Command) {
+	cmd
+		.addOption(Options.apiKey)
+		.addOption(Options.apiTimeout)
+		.addOption(Options.baseUrl)
+		.addOption(Options.branch)
+		.addOption(Options.configFile)
+		.addOption(Options.environment)
+		.addOption(Options.managementToken)
+		.addOption(Options.verbose);
+}
+
+export type CommonOptions = Options.ApiKeyOption &
+	Options.ApiTimeoutOption &
+	Options.BaseUrlOption &
+	Options.BranchOption &
+	Options.ConfigFileOption &
+	Options.EnvironmentOption &
+	Options.ManagementTokenOption &
+	Options.VerboseOption;

package/src/ui/option/configFile.ts

@@ -0,0 +1,19 @@
+import { Option } from 'commander';
+import { resolve } from 'node:path';
+
+const configFile = new Option(
+	'--config-file [path]',
+	'Configuration file path',
+);
+
+export const defaultValue = './beacon.yaml';
+
+configFile
+	.default(defaultValue)
+	.argParser((path) => resolve(path ? path : defaultValue));
+
+export interface ConfigFileOption {
+	readonly configFile: string;
+}
+
+export default configFile;

package/src/ui/option/deletionStrategy.ts

@@ -0,0 +1,20 @@
+import { Option } from 'commander';
+import type Options from '../Options.js';
+
+const deletionStrategy = new Option(
+	'--deletion-strategy [name]',
+	'How to handle deletions in the target stack',
+);
+
+export const defaultValue = 'warn';
+
+deletionStrategy
+	.choices(['delete', 'ignore', 'warn'])
+	.default(defaultValue)
+	.argParser((value) => (value ? value : defaultValue));
+
+export interface DeletionStrategyOption {
+	readonly deletionStrategy: Options['schema']['deletionStrategy'];
+}
+
+export default deletionStrategy;

package/src/ui/option/environment.ts

@@ -0,0 +1,9 @@
+import { Option } from 'commander';
+
+const environment = new Option('--environment [name]', 'Named environment');
+
+export interface EnvironmentOption {
+	readonly environment?: string;
+}
+
+export default environment;

package/src/ui/option/extension.ts

@@ -0,0 +1,16 @@
+import { Option } from 'commander';
+import type Options from '../Options.js';
+import mapParser from '../parser/mapParser.js';
+
+const extension = new Option(
+	'--extension [name:uid...]',
+	'Map a named extension to a stack-specific UID.',
+);
+
+extension.env('Beacon_Extension').argParser(mapParser);
+
+export interface ExtensionOption {
+	readonly extension?: Options['schema']['extension'] | undefined;
+}
+
+export default extension;

package/src/ui/option/index.ts

@@ -0,0 +1,24 @@
+export { default as apiKey } from './apiKey.js';
+export type { ApiKeyOption } from './apiKey.js';
+export { default as apiTimeout } from './apiTimeout.js';
+export type { ApiTimeoutOption } from './apiTimeout.js';
+export { default as baseUrl } from './baseUrl.js';
+export type { BaseUrlOption } from './baseUrl.js';
+export { default as branch } from './branch.js';
+export type { BranchOption } from './branch.js';
+export { default as configFile } from './configFile.js';
+export type { ConfigFileOption } from './configFile.js';
+export { default as deletionStrategy } from './deletionStrategy.js';
+export type { DeletionStrategyOption } from './deletionStrategy.js';
+export { default as environment } from './environment.js';
+export type { EnvironmentOption } from './environment.js';
+export { default as extension } from './extension.js';
+export type { ExtensionOption } from './extension.js';
+export { default as jsonRtePlugin } from './jsonRtePlugin.js';
+export type { JsonRtePluginOption } from './jsonRtePlugin.js';
+export { default as managementToken } from './managementToken.js';
+export type { ManagementTokenOption } from './managementToken.js';
+export { default as schemaPath } from './schemaPath.js';
+export type { SchemaPathOption } from './schemaPath.js';
+export { default as verbose } from './verbose.js';
+export type { VerboseOption } from './verbose.js';