@arkebcacy/beacon-cli-temp 0.1.1

package/src/dto/schema/fromCs.ts

@@ -0,0 +1,32 @@
+import type { Schema } from '#cli/cs/Types.js';
+import traverse from './lib/traverse.js';
+
+export default function fromCs(schemaContainer: Schema): Schema {
+	const entries = new Map<string, unknown>();
+
+	for (const [key, value] of Object.entries(schemaContainer)) {
+		if (!keysToRemove.has(key)) {
+			entries.set(key, value);
+		}
+	}
+
+	return {
+		title: schemaContainer.title,
+		uid: schemaContainer.uid,
+		...Object.fromEntries(entries),
+		schema: [...traverse(schemaContainer.schema)],
+	};
+}
+
+const keysToRemove = new Set<string>([
+	'DEFAULT_ACL',
+	'SYS_ACL',
+	'_version',
+	'abilities',
+	'created_at',
+	'inbuilt_class',
+	'last_activity',
+	'maintain_revisions',
+	'updated_at',
+	'schema',
+]);

package/src/dto/schema/lib/replaceBlocks.ts

@@ -0,0 +1,37 @@
+import type { Item, SchemaField } from '#cli/cs/Types.js';
+import { isItem, isSchemaFields } from '#cli/cs/Types.js';
+import getUi from '../../../schema/lib/SchemaUi.js';
+import traverse from './traverse.js';
+
+export default function replaceBlocks(field: SchemaField): SchemaField {
+	if (!('blocks' in field)) {
+		getUi().warn('Missing blocks schema', field);
+		return field;
+	}
+
+	const { blocks: blockTypesArray } = field;
+	if (!Array.isArray(blockTypesArray) || !blockTypesArray.every(isItem)) {
+		getUi().warn('Invalid blocks schema', field);
+		return field;
+	}
+
+	return {
+		...field,
+		blocks: blockTypesArray.map((block) => replaceBlock(block)),
+	};
+}
+
+function replaceBlock(block: Item): Item {
+	const { reference_to: globalFieldUid } = block;
+	if (typeof globalFieldUid === 'string') {
+		return block;
+	}
+
+	const { schema } = block;
+	if (!isSchemaFields(schema)) {
+		getUi().warn('Invalid block schema', block);
+		return block;
+	}
+
+	return { ...block, schema: [...traverse(schema)] };
+}

package/src/dto/schema/lib/replaceField.ts

@@ -0,0 +1,49 @@
+import type { SchemaField } from '#cli/cs/Types.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+
+export default function replaceField(field: SchemaField): SchemaField {
+	if (!('extension_uid' in field) && !('plugins' in field)) {
+		return field;
+	}
+
+	const entries = new Map(Object.entries(field));
+	const extension_uid = entries.get('extension_uid');
+	const plugins = entries.get('plugins');
+	const ui = getUi();
+
+	if (typeof extension_uid === 'string') {
+		const extension = ui.options.schema.extension.byUid.get(extension_uid);
+		if (!extension) {
+			ui.warn('Unknown extension, please provide mapping for', extension_uid);
+		} else {
+			entries.set('extension_uid', { $beacon: { extension } });
+		}
+	}
+
+	if (Array.isArray(plugins)) {
+		entries.set('plugins', replacePlugins(ui, plugins));
+	}
+
+	return {
+		...Object.fromEntries(entries),
+		data_type: field.data_type,
+		uid: field.uid,
+	};
+}
+
+function replacePlugins(ui: ReturnType<typeof getUi>, plugins: unknown[]) {
+	return plugins.map((pluginUid) => {
+		if (typeof pluginUid !== 'string') {
+			ui.warn('Invalid json RTE plugin uid', pluginUid);
+			return pluginUid;
+		}
+
+		const plugin = ui.options.schema.jsonRtePlugin.byUid.get(pluginUid);
+		if (!plugin) {
+			ui.warn('Unknown json RTE plugin, please provide mapping for', pluginUid);
+			return pluginUid;
+		}
+
+		return { $beacon: { jsonRtePlugin: plugin } };
+	});
+}

package/src/dto/schema/lib/replaceGroup.ts

@@ -0,0 +1,15 @@
+import type { SchemaField } from '#cli/cs/Types.js';
+import { isSchemaFields } from '#cli/cs/Types.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import traverse from './traverse.js';
+
+export default function replaceGroup(field: SchemaField): SchemaField {
+	const { schema } = field;
+
+	if (!isSchemaFields(schema)) {
+		getUi().warn('Invalid group schema', field);
+		return field;
+	}
+
+	return { ...field, schema: [...traverse(schema)] };
+}

package/src/dto/schema/lib/replaceReference.ts

@@ -0,0 +1,14 @@
+import type { SchemaField } from '#cli/cs/Types.js';
+
+export default function replaceReference(field: SchemaField): SchemaField {
+	const { reference_to } = field;
+
+	if (!Array.isArray(reference_to)) {
+		return field;
+	}
+
+	return {
+		...field,
+		reference_to: [...new Set(reference_to)].sort(),
+	};
+}

package/src/dto/schema/lib/traverse.ts

@@ -0,0 +1,26 @@
+import type { SchemaField, SchemaFields } from '#cli/cs/Types.js';
+import replaceBlocks from './replaceBlocks.js';
+import replaceField from './replaceField.js';
+import replaceGroup from './replaceGroup.js';
+import replaceReference from './replaceReference.js';
+
+export default function* traverse(
+	schemaFields: SchemaFields,
+): Generator<SchemaField> {
+	for (const field of schemaFields) {
+		switch (field.data_type) {
+			case 'blocks':
+				yield replaceBlocks(field);
+				continue;
+			case 'group':
+				yield replaceGroup(field);
+				continue;
+			case 'reference':
+				yield replaceReference(field);
+				continue;
+			default:
+				yield replaceField(field);
+				continue;
+		}
+	}
+}

package/src/dto/schema/toCs.ts

@@ -0,0 +1,59 @@
+import type { Schema } from '#cli/cs/Types.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import isRecord from '#cli/util/isRecord.js';
+import { inspect } from 'node:util';
+
+export default function toCs(schema: Schema): Schema {
+	return processObject(schema) as unknown as Schema;
+}
+
+function processObject(o: Record<string, unknown>): Record<string, unknown> {
+	return Object.fromEntries(
+		Object.entries(o).map(([key, value]) => [key, processValue(value)]),
+	);
+}
+
+function processValue(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map(processValue);
+	}
+
+	if (isRecord(value)) {
+		const { $beacon } = value;
+		if (!isRecord($beacon)) {
+			return processObject(value);
+		}
+
+		const uid =
+			resolveUid($beacon, 'extension') ?? resolveUid($beacon, 'jsonRtePlugin');
+
+		if (typeof uid !== 'string') {
+			throw new Error('Invalid $beacon in ' + inspect(value, { depth: 2 }));
+		}
+
+		return uid;
+	}
+
+	return value;
+}
+
+function resolveUid(
+	$beacon: Record<string, unknown>,
+	property: 'extension' | 'jsonRtePlugin',
+) {
+	const name = $beacon[property];
+
+	if (typeof name !== 'string') {
+		return;
+	}
+
+	const { options } = getUi();
+
+	const uid = options.schema[property].byName.get(name);
+
+	if (typeof uid !== 'string') {
+		throw new Error(`Could not find UID for extension ${name}.`);
+	}
+
+	return uid;
+}

package/src/dto/taxonomy/NormalizedTaxonomy.ts

@@ -0,0 +1,64 @@
+import type Taxonomy from '#cli/cs/taxonomies/Taxonomy.js';
+import type Term from '#cli/cs/terms/Term.js';
+import { isItem } from '#cli/cs/Types.js';
+import isRecord from '#cli/util/isRecord.js';
+
+export default interface NormalizedTaxonomy {
+	readonly taxonomy: {
+		readonly description?: Taxonomy['description'];
+		readonly name: Taxonomy['name'];
+		readonly uid: Taxonomy['uid'];
+	};
+	readonly terms?: readonly TermTreeNode[];
+}
+
+export interface TermTreeNode {
+	readonly uid: Term['uid'];
+	readonly name: Term['name'];
+	readonly children?: readonly TermTreeNode[];
+}
+
+export function key(o: NormalizedTaxonomy) {
+	return o.taxonomy.uid;
+}
+
+export function isNormalizedTaxonomy(
+	value: unknown,
+): value is NormalizedTaxonomy & Record<string, unknown> {
+	if (!isRecord(value)) {
+		return false;
+	}
+
+	return (
+		isTaxonomy(value.taxonomy) &&
+		(value.terms === undefined ||
+			(Array.isArray(value.terms) && value.terms.every(isTermTreeNode)))
+	);
+}
+
+function isTaxonomy(x: unknown): x is NormalizedTaxonomy['taxonomy'] {
+	return (
+		isRecord(x) &&
+		typeof x.name === 'string' &&
+		typeof x.uid === 'string' &&
+		(!('description' in x) || typeof x.description === 'string')
+	);
+}
+
+function isTermTreeNode(value: unknown): value is TermTreeNode {
+	if (!isItem(value)) {
+		return false;
+	}
+
+	if (typeof value.name !== 'string') {
+		return false;
+	}
+
+	if (!('children' in value)) {
+		return true;
+	}
+
+	const { children } = value;
+
+	return Array.isArray(children) && children.every(isTermTreeNode);
+}

package/src/dto/taxonomy/flatten.ts

@@ -0,0 +1,27 @@
+import type Term from '#cli/cs/terms/Term.js';
+import type { TermTreeNode } from './NormalizedTaxonomy.js';
+
+export default function flatten(
+	terms: readonly TermTreeNode[],
+): readonly Term[] {
+	const result: Term[] = [];
+
+	function traverse(nodes: readonly TermTreeNode[], parentUid: string | null) {
+		for (const node of nodes) {
+			const { children, ...term } = node;
+
+			result.push({
+				...term,
+				parent_uid: parentUid,
+			});
+
+			if (children) {
+				traverse(children, node.uid);
+			}
+		}
+	}
+
+	traverse(terms, null);
+
+	return result;
+}

package/src/dto/taxonomy/fromCs.ts

@@ -0,0 +1,29 @@
+import type Taxonomy from '../../cs/taxonomies/Taxonomy.js';
+import type Term from '../../cs/terms/Term.js';
+import type NormalizedTaxonomy from './NormalizedTaxonomy.js';
+import organize from './organize.js';
+
+// Justification: The keys of these objects are ordered carefully to produce
+// a readable and stable serialization.
+/* eslint-disable sort-keys */
+
+export default function fromCs(
+	taxonomy: Taxonomy,
+	terms?: readonly Term[],
+): NormalizedTaxonomy {
+	return (terms?.length ?? 0) > 0
+		? { taxonomy: transformTaxonomy(taxonomy), terms: organize(terms ?? []) }
+		: { taxonomy: transformTaxonomy(taxonomy) };
+}
+
+function transformTaxonomy({
+	description,
+	name,
+	uid,
+}: Taxonomy): NormalizedTaxonomy['taxonomy'] {
+	return {
+		uid,
+		name,
+		...(description ? { description } : {}),
+	};
+}

package/src/dto/taxonomy/organize.ts

@@ -0,0 +1,59 @@
+import type TaxonomyDetail from '#cli/cs/taxonomies/TaxonomyDetail.js';
+import type { TermTreeNode } from './NormalizedTaxonomy.js';
+
+// Taxonomy terms have a tree structure defined by uid/parent_uid.
+//
+// However, the API returns a flat array that includes uid/parent_uid, but
+// leaves it up to the client to reconstruct the tree.
+//
+// Amongst the siblings of a single branch, the sort order is relevant and
+// must be maintained, equal to the order as it appears in the array.
+//
+// However, Contentstack is returning an inconsistent order for nodes on
+// the same level but on different branches. That is, the branches are
+// intertwined with each other. This means we cannot blindly trust the sort
+// order of the array as a whole, only within the siblings of a single branch.
+// Last observed on 2024-08-14.
+//
+// To prove equality, we need to parse the tree structure and compare for
+// deep equality only after sorting the siblings of each branch.
+
+type MutableNode = Omit<TermTreeNode, 'children'> & {
+	children?: MutableNode[];
+};
+
+export default function organize(
+	terms: TaxonomyDetail['terms'],
+): readonly TermTreeNode[] {
+	const byUid = new Map<string, MutableNode>();
+	const topLevel: MutableNode[] = [];
+
+	for (const { uid, name } of terms) {
+		// Justification: Keys are placed in this order for readability in
+		// the serialization of the object.
+		// eslint-disable-next-line sort-keys
+		byUid.set(uid, { uid, name });
+	}
+
+	for (const { uid, parent_uid } of terms) {
+		const term = byUid.get(uid);
+		if (!term) {
+			throw new Error(`Term ${uid} not found`);
+		}
+
+		if (!parent_uid) {
+			topLevel.push(term);
+			continue;
+		}
+
+		const parent = byUid.get(parent_uid);
+		if (!parent) {
+			const msg = `Orphaned term ${uid} with parent ${parent_uid}`;
+			throw new Error(msg);
+		}
+
+		(parent.children ??= []).push(term);
+	}
+
+	return topLevel;
+}

package/src/dto/taxonomy/taxonomyStrategy.ts

@@ -0,0 +1,18 @@
+import { minimatch } from 'minimatch';
+import type Taxonomy from '../../cs/taxonomies/Taxonomy.js';
+import getUi from '../../schema/lib/SchemaUi.js';
+import type { TaxonomyStrategy } from '../../ui/Options.js';
+
+export default function taxonomyStrategy(
+	taxonomyUid: Taxonomy['uid'],
+): TaxonomyStrategy {
+	const ui = getUi();
+
+	for (const [pattern, strategy] of ui.options.schema.taxonomies) {
+		if (minimatch(taxonomyUid, pattern)) {
+			return strategy;
+		}
+	}
+
+	return 'taxonomy and terms';
+}

package/src/dto/taxonomy/toCs.ts

@@ -0,0 +1,32 @@
+import type TaxonomyDetail from '#cli/cs/taxonomies/TaxonomyDetail.js';
+import flatten from './flatten.js';
+import type NormalizedTaxonomy from './NormalizedTaxonomy.js';
+import taxonomyStrategy from './taxonomyStrategy.js';
+
+export default function toCs(normalized: NormalizedTaxonomy): TaxonomyDetail {
+	const strategy = taxonomyStrategy(normalized.taxonomy.uid);
+
+	if (strategy === 'only taxonomy') {
+		return {
+			taxonomy: transformTaxonomy(normalized.taxonomy),
+			terms: [],
+		};
+	}
+
+	return {
+		taxonomy: transformTaxonomy(normalized.taxonomy),
+		terms: flatten(normalized.terms ?? []),
+	};
+}
+
+function transformTaxonomy({
+	description,
+	name,
+	uid,
+}: NormalizedTaxonomy['taxonomy']): TaxonomyDetail['taxonomy'] {
+	return {
+		description: description ?? '',
+		name,
+		uid,
+	};
+}

package/src/fs/assets/Assets.ts

@@ -0,0 +1,49 @@
+import { resolve } from 'node:path';
+import type FolderMeta from '../../schema/assetFolders/lib/FolderMeta.js';
+import type AssetMeta from '../../schema/assets/AssetMeta.js';
+import { load } from '../../schema/assets/lib/MetaSerialization.js';
+import {
+	assetPaths,
+	formatItemPath,
+} from '../../schema/assets/lib/NamingConvention.js';
+import schemaDirectory from '../../schema/assets/schemaDirectory.js';
+import tryReadDir from '../tryReadDir.js';
+
+export default class Assets {
+	private constructor(
+		private readonly _assetsByPath: Map<string, AssetMeta>,
+		private readonly _foldersByPath: Map<string, FolderMeta>,
+	) {}
+
+	public get assetsByPath(): ReadonlyMap<string, AssetMeta> {
+		return this._assetsByPath;
+	}
+
+	public get foldersByPath(): ReadonlyMap<string, FolderMeta> {
+		return this._foldersByPath;
+	}
+
+	public static async create() {
+		const assetsPath = schemaDirectory();
+		const assetsByPath = new Map<string, AssetMeta>();
+		const foldersByPath = new Map<string, FolderMeta>();
+		const entries = await tryReadDir(assetsPath, true);
+
+		for (const paths of assetPaths(assetsPath, entries)) {
+			const meta = await load(paths);
+			assetsByPath.set(meta.itemPath, meta);
+		}
+
+		for (const entry of entries) {
+			if (!entry.isDirectory()) {
+				continue;
+			}
+
+			const absPath = resolve(entry.parentPath, entry.name);
+			const itemPath = formatItemPath(assetsPath, absPath);
+			foldersByPath.set(itemPath, { itemPath, name: entry.name });
+		}
+
+		return new Assets(assetsByPath, foldersByPath);
+	}
+}

package/src/fs/readYaml.ts

@@ -0,0 +1,8 @@
+import type { PathLike } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { parse } from 'yaml';
+
+export default async function readYaml(pathLike: PathLike): Promise<unknown> {
+	const raw = await readFile(pathLike, 'utf-8');
+	return parse(raw);
+}

package/src/fs/tryReadDir.test.ts

@@ -0,0 +1,15 @@
+import { randomUUID } from 'node:crypto';
+import { resolve } from 'node:path';
+import { expect, it } from 'vitest';
+import tryReadDir from './tryReadDir.js';
+
+it('returns an empty array if the directory does not exist', async () => {
+	// Arrange
+	const testPath = resolve(randomUUID(), 'does', 'not', 'exist');
+
+	// Act
+	const result = await tryReadDir(testPath);
+
+	// Assert
+	expect(result).toEqual([]);
+});

package/src/fs/tryReadDir.ts

@@ -0,0 +1,14 @@
+import type { PathLike } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+
+export default async function tryReadDir(path: PathLike, recursive?: boolean) {
+	try {
+		return await readdir(path, { recursive, withFileTypes: true });
+	} catch (ex: unknown) {
+		if (ex instanceof Error && 'code' in ex && ex.code === 'ENOENT') {
+			return []; // Missing directory === empty directory
+		}
+
+		throw ex;
+	}
+}

package/src/fs/writeYaml.test.ts

@@ -0,0 +1,34 @@
+import readFixture from '#test/fixtures/readFixture.js';
+import getSnapshotPath from '#test/snapshots/getSnapshotPath.js';
+import TempFolder from '#test/util/TempFolder.js';
+import TestProjectUrl from '#test/util/TestProjectUrl.js';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import writeYaml from './writeYaml.js';
+
+describe(writeYaml.name, () => {
+	it('can serialize troublesome unicode characters', async () => {
+		// Arrange
+		const tempPath = fileURLToPath(new URL('.tmp', TestProjectUrl));
+		await using tempFolder = await TempFolder.create(tempPath);
+		const outputName = 'output.yaml';
+		const absolutePath = resolve(tempFolder.absPath, outputName);
+		const content = await readJsonC('serialization/leading-unicode.jsonc');
+
+		// Act
+		await writeYaml(absolutePath, content);
+		const actual = await readFile(absolutePath, 'utf-8');
+
+		// Assert
+		const snapPath = getSnapshotPath('leading-unicode.yaml');
+		await expect(actual).toMatchFileSnapshot(snapPath);
+	});
+});
+
+async function readJsonC(fixturePath: string): Promise<unknown> {
+	const raw = await readFixture(fixturePath);
+	const withoutComments = raw.replace(/\/\/.*|\/\*[\s\S]*?\*\//gu, '').trim();
+	return JSON.parse(withoutComments);
+}

package/src/fs/writeYaml.ts

@@ -0,0 +1,14 @@
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname } from 'node:path';
+import type { SchemaOptions } from 'yaml';
+import { stringify } from 'yaml';
+
+export default async function writeYaml(
+	absolutePath: string,
+	content: unknown,
+	opts: SchemaOptions = { sortMapEntries: true },
+) {
+	const output = stringify(content, opts);
+	await mkdir(dirname(absolutePath), { recursive: true });
+	await writeFile(absolutePath, output, 'utf-8');
+}

package/src/schema/SchemaOperationError.ts

@@ -0,0 +1,19 @@
+import HandledError from '../ui/HandledError.js';
+import type TransferResults from './xfer/TransferResults.js';
+
+export default class SchemaOperationError extends HandledError {
+	public constructor() {
+		super('Schema push/pull operation failed.');
+		this.name = 'SchemaOperationError';
+	}
+
+	public static throwIfFailuresExist(
+		results: IterableIterator<PromiseSettledResult<TransferResults>>,
+	) {
+		for (const result of results) {
+			if (result.status === 'rejected' || result.value.errored.size > 0) {
+				throw new SchemaOperationError();
+			}
+		}
+	}
+}

package/src/schema/assetFolders/lib/FolderMeta.ts

@@ -0,0 +1,4 @@
+export default interface FolderMeta {
+	readonly name: string;
+	readonly itemPath: string;
+}

package/src/schema/assetFolders/lib/indexContentstack.ts

@@ -0,0 +1,34 @@
+import type { ReadonlyAssets } from '#cli/cs/assets/Assets.js';
+import { isRawFolder, type RawFolder } from '#cli/cs/assets/Types.js';
+import type FolderMeta from './FolderMeta.js';
+
+export default function indexContentstack(assets: ReadonlyAssets) {
+	const result = new Map<string, FolderMeta>();
+
+	for (const folder of readFolders(assets, null, '')) {
+		result.set(folder.itemPath, folder);
+	}
+
+	return result;
+}
+
+function* readFolders(
+	assets: ReadonlyAssets,
+	parentUid: RawFolder['parent_uid'],
+	contextPath: string,
+): Generator<FolderMeta> {
+	const contents = assets.byParentUid.get(parentUid);
+	if (!contents) {
+		return;
+	}
+
+	for (const entry of contents) {
+		if (!isRawFolder(entry)) {
+			continue;
+		}
+
+		const itemPath = contextPath ? `${contextPath}/${entry.name}` : entry.name;
+		yield { itemPath, name: entry.name };
+		yield* readFolders(assets, entry.uid, itemPath);
+	}
+}