@arkebcacy/beacon-cli-temp 0.1.1

package/src/cfg/loadConfig.test.ts

@@ -0,0 +1,103 @@
+import TestProjectUrl from '#test/util/TestProjectUrl.js';
+import { describe, expect, it } from 'vitest';
+import ConfigMissingError from './ConfigMissingError.js';
+import ConfigurationError from './ConfigurationError.js';
+import loadConfig from './loadConfig.js';
+
+describe(loadConfig.name, () => {
+	it('can load a valid configuration file', async () => {
+		// Arrange
+		const configPath = resolveConfigUrl('valid-config');
+
+		// Act
+		const result = await loadConfig(configPath, undefined);
+
+		// Assert
+		expect(result).toEqual({
+			client: {
+				apiKey: 'api key',
+				baseUrl: new URL('https://example.com'),
+				branch: 'branch name',
+				managementToken: 'management token',
+			},
+			schema: {
+				deletionStrategy: 'delete',
+				extension: {
+					byName: new Map<string, string>([
+						['key1', 'value1'],
+						['key2', 'value2'],
+					]),
+					byUid: new Map<string, string>([
+						['value1', 'key1'],
+						['value2', 'key2'],
+					]),
+				},
+				jsonRtePlugin: {
+					byName: new Map<string, string>([
+						['key3', 'value3'],
+						['key4', 'value4'],
+					]),
+					byUid: new Map<string, string>([
+						['value3', 'key3'],
+						['value4', 'key4'],
+					]),
+				},
+				schemaPath: 'schema path',
+				taxonomies: new Map([
+					['tax_and_terms', 'taxonomy and terms'],
+					['only_tax', 'only taxonomy'],
+					['*', 'taxonomy and terms'],
+				]),
+			},
+			verbose: true,
+		});
+	});
+
+	it('throws a ConfigMissingError error for missing files', async () => {
+		// Arrange
+		const configPath = resolveConfigUrl('missing-config');
+
+		// Act
+		const attempt = async () => await loadConfig(configPath, undefined);
+
+		// Assert
+		await expect(attempt).rejects.toThrowError(ConfigMissingError);
+	});
+
+	it('throws a ConfigurationError for invalid files', async () => {
+		// Arrange
+		const configPath = resolveConfigUrl('invalid-config');
+
+		// Act
+		const attempt = async () => await loadConfig(configPath, undefined);
+
+		// Assert
+		await expect(attempt).rejects.toThrowError(ConfigurationError);
+	});
+
+	it('can load a configuration with environments', async () => {
+		// Arrange
+		const configPath = resolveConfigUrl('config-with-environments');
+
+		// Act
+		const result = await loadConfig(configPath, 'dev');
+
+		// Assert
+		expect(result).toEqual({
+			client: {
+				apiKey: 'default-key',
+				baseUrl: new URL('https://default.com'),
+				branch: 'dev-branch',
+				managementToken: 'dev-token',
+			},
+			schema: {
+				deletionStrategy: 'warn',
+				schemaPath: 'dev-path',
+			},
+		});
+	});
+});
+
+function resolveConfigUrl(name: string) {
+	return new URL(`fixtures/config/${name}.yaml`, TestProjectUrl);
+}

package/src/cfg/loadConfig.ts

@@ -0,0 +1,44 @@
+import type { PathLike } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { parse } from 'yaml';
+import type { PartialOptions } from '../ui/PartialOptions.js';
+import ConfigMissingError from './ConfigMissingError.js';
+import ConfigurationError from './ConfigurationError.js';
+import createSchemaValidationFn from './createSchemaValidationFn.js';
+import transform from './transform/transform.js';
+
+export default async function loadConfig(
+	configFile: PathLike,
+	namedEnvironment: string | undefined,
+): Promise<PartialOptions> {
+	let raw: string;
+
+	try {
+		raw = await readFile(configFile, 'utf8');
+	} catch (ex: unknown) {
+		if (!(ex instanceof Error)) {
+			throw ex;
+		}
+
+		if (!('code' in ex)) {
+			throw ex;
+		}
+
+		if (ex.code !== 'ENOENT') {
+			throw ex;
+		}
+
+		throw new ConfigMissingError(
+			'Configuration file not found: ' + String(configFile),
+		);
+	}
+
+	const cfg: unknown = parse(raw);
+	const validate = await createSchemaValidationFn();
+
+	if (!validate(cfg)) {
+		throw new ConfigurationError(configFile, validate.errors);
+	}
+
+	return transform(cfg, namedEnvironment);
+}

package/src/cfg/removeDefaultValues.ts

@@ -0,0 +1,87 @@
+import type { PartialOptions } from '../ui/PartialOptions.js';
+import type { CliOptions } from './CliOptions.js';
+import { defaultValues } from './defaultValues.js';
+
+// The "fromCommandEnvironment" parameter is provided by commander.js after
+// parsing command-line arguments and environment variables, and adding the
+// default values.
+//
+// This is a problem because we wish to respect this precedence:
+//
+//   1. Command line
+//   2. Environment variables
+//   3. Configuration file
+//   4. (implied) Default values
+//
+// Thus, if the "fromCommandEnvironment" parameter is provided, it will contain
+// default values as the wrong precedence, and any values provided by the
+// configuration file will be ignored.
+//
+// I have considered removing the default values from the commander.js
+// configuration, but I have decided against it because doing so would
+// also remove the default values from the help text.
+//
+// Therefore, we must remove the default values from the fromCommandEnvironment
+// parameter before using it.
+export default function removeDefaultValues(
+	fromCommandEnvironment: CliOptions,
+): Partial<CliOptions> {
+	const {
+		client: rawClient,
+		schema: rawSchema,
+		configFile,
+		...rest
+	} = fromCommandEnvironment;
+
+	const client = handleClient(rawClient);
+	const schema = handleSchema(rawSchema);
+
+	return {
+		...rest,
+		...(client ? { client } : {}),
+		...(schema ? { schema } : {}),
+		...(configFile && configFile !== defaultValues.configFile
+			? { configFile }
+			: {}),
+	};
+}
+
+function handleClient(
+	client: PartialOptions['client'],
+): PartialOptions['client'] {
+	const { branch, timeout, ...rest } = client ?? {};
+
+	const hasBranch = branch && branch !== defaultValues.client.branch;
+
+	const hasTimeout =
+		typeof timeout === 'number' && timeout !== defaultValues.client.timeout;
+
+	const result: PartialOptions['client'] = {
+		...rest,
+		...(hasBranch ? { branch } : {}),
+		...(hasTimeout ? { timeout } : {}),
+	};
+
+	return Object.keys(result).length > 0 ? result : undefined;
+}
+
+function handleSchema(
+	schema: PartialOptions['schema'],
+): PartialOptions['schema'] {
+	const { deletionStrategy, schemaPath, ...rest } = schema ?? {};
+
+	const hasDeletionStrategy =
+		deletionStrategy &&
+		deletionStrategy !== defaultValues.schema.deletionStrategy;
+
+	const hasSchemaPath =
+		schemaPath && schemaPath !== defaultValues.schema.schemaPath;
+
+	const result: PartialOptions['schema'] = {
+		...rest,
+		...(hasDeletionStrategy ? { deletionStrategy } : {}),
+		...(hasSchemaPath ? { schemaPath } : {}),
+	};
+
+	return Object.keys(result).length > 0 ? result : undefined;
+}

package/src/cfg/resolveConfig.ts

@@ -0,0 +1,46 @@
+import type Options from '../ui/Options.js';
+import type { PartialOptions } from '../ui/PartialOptions.js';
+import UiOptions from '../ui/UiOptions.js';
+import type { CliOptions } from './CliOptions.js';
+import ConfigMissingError from './ConfigMissingError.js';
+import { defaultValues } from './defaultValues.js';
+import loadConfig from './loadConfig.js';
+import removeDefaultValues from './removeDefaultValues.js';
+
+export default async function resolveConfig(
+	cliOptions: CliOptions,
+): Promise<Options> {
+	const withoutDefaults = removeDefaultValues(cliOptions);
+	const { configFile } = withoutDefaults;
+
+	if (configFile) {
+		const fromConfigFile = await loadConfig(
+			configFile,
+			cliOptions.namedEnvironment,
+		);
+
+		return new UiOptions(defaultValues, fromConfigFile, withoutDefaults);
+	}
+
+	const fromConfig = await loadDefaultConfig(cliOptions.namedEnvironment);
+
+	if (fromConfig) {
+		return new UiOptions(defaultValues, fromConfig, withoutDefaults);
+	}
+
+	return new UiOptions(cliOptions);
+}
+
+async function loadDefaultConfig(
+	namedEnvironment: string | undefined,
+): Promise<PartialOptions | undefined> {
+	try {
+		return await loadConfig(defaultValues.configFile, namedEnvironment);
+	} catch (ex: unknown) {
+		if (ex instanceof ConfigMissingError) {
+			return;
+		}
+
+		throw ex;
+	}
+}

package/src/cfg/transform/compileFilters.ts

@@ -0,0 +1,27 @@
+import type { MinimatchOptions } from 'minimatch';
+import { filter } from 'minimatch';
+import type { Config } from '../Config.schema.yaml';
+
+type SchemaConfig = NonNullable<Config['schema']>;
+type Filters = NonNullable<SchemaConfig['assets']>;
+
+export default function compileFilters(filters: Filters) {
+	const cfg: MinimatchOptions = { dot: true, nocomment: true };
+	const compile = (pattern: string) => filter(pattern, cfg);
+
+	const include = [...new Set(filters.include)].map(compile);
+	const exclude = [...new Set(filters.exclude)].map(compile);
+	type Fn = (typeof include)[number];
+
+	function isIncluded(path: string) {
+		const predicate = (x: Fn) => x(path);
+
+		if (exclude.some(predicate)) {
+			return false;
+		}
+
+		return include.some(predicate);
+	}
+
+	return isIncluded;
+}

package/src/cfg/transform/transform.ts

@@ -0,0 +1,36 @@
+import { styleText } from 'node:util';
+import type { PartialOptions } from '../../ui/PartialOptions.js';
+import type { Config } from '../Config.schema.yaml';
+import transformClientConfig from './transformClientConfig.js';
+import transformSchemaConfig from './transformSchemaConfig.js';
+
+export default function transform(
+	configData: Config,
+	environmentName: string | undefined,
+): PartialOptions {
+	const base = {
+		...(typeof configData.verbose === 'boolean'
+			? { verbose: configData.verbose }
+			: {}),
+	};
+
+	const environment =
+		typeof environmentName === 'string'
+			? configData.environments?.[environmentName]
+			: null;
+
+	if (environmentName && !environment) {
+		const human = `"${styleText('yellowBright', environmentName)}"`;
+		const msg = `The environment ${human} does not exist in the configuration.`;
+		throw new Error(msg);
+	}
+
+	const client = transformClientConfig(configData.client, environment?.client);
+	const schema = transformSchemaConfig(configData.schema, environment?.schema);
+
+	return {
+		...(client ? { client } : {}),
+		...(schema ? { schema } : {}),
+		...base,
+	};
+}

package/src/cfg/transform/transformClientConfig.ts

@@ -0,0 +1,26 @@
+import type { Config } from '../Config.schema.yaml';
+
+export default function transformClientConfig(
+	baseClient: Config['client'],
+	envClient: Config['client'],
+) {
+	const resolved = { ...baseClient, ...envClient };
+
+	const {
+		'api-key': apiKey,
+		'base-url': baseUrl,
+		branch,
+		'management-token': managementToken,
+		timeout,
+	} = resolved;
+
+	const result = {
+		...(apiKey ? { apiKey } : {}),
+		...(baseUrl ? { baseUrl: new URL(baseUrl) } : {}),
+		...(branch ? { branch } : {}),
+		...(managementToken ? { managementToken } : {}),
+		...(typeof timeout === 'number' ? { timeout } : {}),
+	};
+
+	return Object.keys(result).length > 0 ? result : undefined;
+}

package/src/cfg/transform/transformSchemaConfig.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import type { Config } from '../Config.schema.yaml';
+import transformSchemaConfig from './transformSchemaConfig';
+
+describe(transformSchemaConfig.name, () => {
+	it('should merge baseSchema and envSchema correctly', () => {
+		const baseSchema: Config['schema'] = {
+			assets: { exclude: ['asset2'], include: ['asset1'] },
+			extension: { ext1: 'value1' },
+			taxonomies: { tax1: 'only taxonomy' },
+		};
+
+		const envSchema: Config['schema'] = {
+			assets: { exclude: ['asset4'], include: ['asset3'] },
+			extension: { ext2: 'value2' },
+			taxonomies: { tax2: 'taxonomy and terms' },
+		};
+
+		const result = transformSchemaConfig(baseSchema, envSchema);
+
+		if (!result) throw new Error('Result is undefined');
+
+		expect(result.extension?.byName?.get('ext1')).toBe('value1');
+		expect(result.extension?.byName?.get('ext2')).toBe('value2');
+		expect(result.taxonomies?.get('tax1')).toBe('only taxonomy');
+		expect(result.taxonomies?.get('tax2')).toBe('taxonomy and terms');
+		expect(result.assets?.isIncluded?.('asset1')).toBe(true);
+		expect(result.assets?.isIncluded?.('asset3')).toBe(true);
+		expect(result.assets?.isIncluded?.('asset2')).toBe(false);
+		expect(result.assets?.isIncluded?.('asset4')).toBe(false);
+	});
+
+	it('should handle empty schemas gracefully', () => {
+		const baseSchema: Config['schema'] = {};
+		const envSchema: Config['schema'] = {};
+
+		const result = transformSchemaConfig(baseSchema, envSchema);
+
+		expect(result).toBeUndefined();
+	});
+
+	it('should prioritize envSchema over baseSchema for overlapping keys', () => {
+		const baseSchema: Config['schema'] = {
+			extension: { key: 'baseValue' },
+		};
+
+		const envSchema: Config['schema'] = {
+			extension: { key: 'envValue' },
+		};
+
+		const result = transformSchemaConfig(baseSchema, envSchema);
+
+		if (!result) throw new Error('Result is undefined');
+
+		expect(result.extension?.byName).toBeDefined();
+		expect(result.extension?.byName?.get('key')).toBe('envValue');
+	});
+});

package/src/cfg/transform/transformSchemaConfig.ts

@@ -0,0 +1,86 @@
+import type { PartialOptions } from '../../ui/PartialOptions.js';
+import type { Config } from '../Config.schema.yaml';
+import compileFilters from './compileFilters.js';
+
+export default function transformSchemaConfig(
+	baseSchema: Config['schema'],
+	envSchema: Config['schema'],
+): PartialOptions['schema'] {
+	const schema = {
+		...baseSchema,
+		...envSchema,
+		...collapseMap(baseSchema?.extension, envSchema?.extension, 'extension'),
+		...collapseMap(baseSchema?.taxonomies, envSchema?.taxonomies, 'taxonomies'),
+		...collapseAssets(baseSchema?.assets, envSchema?.assets),
+
+		...collapseMap(
+			baseSchema?.['json-rte-plugin'],
+			envSchema?.['json-rte-plugin'],
+			'json-rte-plugin',
+		),
+	};
+
+	const {
+		assets,
+		'deletion-strategy': strategy,
+		extension,
+		'json-rte-plugin': jsonRtePlugin,
+		'schema-path': schemaPath,
+		taxonomies,
+	} = schema;
+
+	const result = {
+		...(assets ? { assets: { isIncluded: compileFilters(assets) } } : {}),
+		...(strategy ? { deletionStrategy: strategy } : {}),
+		...(extension ? { extension: transformMap(extension) } : {}),
+		...(jsonRtePlugin ? { jsonRtePlugin: transformMap(jsonRtePlugin) } : {}),
+		...(schemaPath ? { schemaPath } : {}),
+		...(taxonomies ? { taxonomies: new Map(Object.entries(taxonomies)) } : {}),
+	};
+
+	return Object.keys(result).length ? result : undefined;
+}
+
+function transformMap(mapping: Record<string, string>) {
+	return {
+		byName: new Map(Object.entries(mapping)),
+		byUid: new Map(Object.entries(mapping).map(([name, uid]) => [uid, name])),
+	};
+}
+
+function collapseMap(
+	baseMap: Readonly<Record<string, string>> | undefined,
+	envMap: Readonly<Record<string, string>> | undefined,
+	propName: keyof NonNullable<Config['schema']>,
+) {
+	const result = { ...baseMap, ...envMap };
+
+	if (Object.keys(result).length === 0) {
+		return undefined;
+	}
+
+	return { [propName]: result };
+}
+
+function collapseAssets(
+	baseAssets: NonNullable<Config['schema']>['assets'],
+	envAssets: NonNullable<Config['schema']>['assets'],
+) {
+	const include = collapseList(baseAssets?.include, envAssets?.include);
+	const exclude = collapseList(baseAssets?.exclude, envAssets?.exclude);
+
+	const assets = {
+		...(include ? { include } : {}),
+		...(exclude ? { exclude } : {}),
+	};
+
+	return Object.keys(assets).length ? { assets } : undefined;
+}
+
+function collapseList(
+	baseList: readonly string[] | undefined,
+	envList: readonly string[] | undefined,
+) {
+	const result = [...(baseList ?? []), ...(envList ?? [])];
+	return result.length ? result : undefined;
+}

package/src/cs/Types.ts

@@ -0,0 +1,35 @@
+import isRecord from '#cli/util/isRecord.js';
+
+export type Item = Record<string, unknown> & { readonly uid: string };
+
+export function isItem(o: unknown): o is Item {
+	return isRecord(o) && typeof o.uid === 'string';
+}
+
+export function itemKey(o: Item) {
+	return o.uid;
+}
+
+// A Contentstack Schema (either a content type or a global field)
+export interface Schema extends Item {
+	readonly title: string;
+	readonly schema: SchemaFields;
+}
+
+export function isSchema(o: unknown): o is Schema {
+	return isItem(o) && typeof o.title === 'string' && isSchemaFields(o.schema);
+}
+
+export interface SchemaField extends Item {
+	readonly data_type: string;
+}
+
+export function isSchemaField(o: unknown): o is SchemaField {
+	return isItem(o) && typeof o.data_type === 'string';
+}
+
+export type SchemaFields = readonly SchemaField[];
+
+export function isSchemaFields(o: unknown): o is SchemaFields {
+	return Array.isArray(o) && o.every(isSchemaField);
+}

package/src/cs/api/Client.ts

@@ -0,0 +1,50 @@
+import createStylus from '#cli/ui/createStylus.js';
+import type UiContext from '#cli/ui/UiContext.js';
+import { styleText } from 'node:util';
+import createOpenApiClient from 'openapi-fetch';
+import attachMetricCollector from './attachMetricCollector.js';
+import attachRateLimiter from './attachRateLimiter.js';
+import type { paths } from './cma-openapi-3.js';
+import TimeoutAndRetryBehavior from './stall/TimeoutAndRetryBehavior.js';
+
+type Client = ReturnType<typeof createClient>;
+export default Client;
+
+export function createClient(ui: UiContext) {
+	const baseClient = createBaseClient(ui);
+	const withMetrics = attachMetricCollector(baseClient);
+	return attachRateLimiter(ui, withMetrics);
+}
+
+function createBaseClient(ui: UiContext) {
+	const stallCatcher = new TimeoutAndRetryBehavior(ui.options.client.timeout);
+
+	stallCatcher.on('stall-encountered', (request, attempts, maxAttempts) => {
+		const y = createStylus('yellowBright');
+		const msg1 = y`${'⚠'} API stall-out on ${request.url}. Attempt `;
+		const msg2 = y`${attempts.toLocaleString()} of `;
+		const msg3 = y`${maxAttempts.toLocaleString()}.`;
+		const msg = `${msg1}${msg2}${msg3}`;
+		ui.warn(msg);
+	});
+
+	stallCatcher.on('stall-failed', (request) => {
+		const icon = styleText('redBright', '⚠');
+		const url = styleText('yellowBright', request.url);
+		const notice = styleText('redBright', 'Giving up');
+		const msg = `${icon} API stall-out on ${url}. ${notice}.`;
+		ui.error(msg);
+	});
+
+	const opts = ui.options.client;
+
+	return createOpenApiClient<paths>({
+		baseUrl: opts.baseUrl.toString(),
+		fetch: stallCatcher.fetch.bind(stallCatcher),
+		headers: {
+			api_key: opts.apiKey,
+			authorization: opts.managementToken,
+			branch: opts.branch,
+		},
+	});
+}

package/src/cs/api/ContentstackError.test.ts

@@ -0,0 +1,18 @@
+import readFixture from '#test/fixtures/readFixture';
+import { expect, test, vi } from 'vitest';
+import { parse } from 'yaml';
+import ContentstackError from './ContentstackError.js';
+
+vi.mock(import('../../ui/HandledError.js'));
+
+test('Correctly understands a Contentstack error response', async () => {
+	// Arrange
+	const errorYaml = await readFixture('error-response.yaml');
+	const errorResponse: unknown = parse(errorYaml);
+
+	// Act
+	const fn = () => ContentstackError.throwIfError(errorResponse, 'unit test');
+
+	// Assert
+	expect(fn).toThrowError(ContentstackError);
+});