@arkebcacy/beacon-cli-temp 0.1.1

package/src/schema/entries/lib/loadEntryLocales.ts

@@ -0,0 +1,123 @@
+import type { Entry } from '#cli/cs/entries/Types.js';
+import readYaml from '#cli/fs/readYaml.js';
+import escapeRegex from '#cli/util/escapeRegex.js';
+import { readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+
+export interface EntryWithLocale {
+	readonly entry: Entry;
+	readonly locale: string;
+}
+
+/**
+ * Loads all locale versions of an entry from the filesystem.
+ *
+ * This function supports both single-locale and multi-locale file patterns:
+ * - Single-locale: `baseFilename.yaml` (assigns locale='default' for backward compatibility)
+ * - Multi-locale: `baseFilename.{locale}.yaml` (e.g., `Entry Title.en-us.yaml`)
+ *
+ * @param directory - The directory containing entry files (e.g., 'schema/entries/event')
+ * @param entryTitle - The title of the entry (used to create synthetic uid for filesystem entries)
+ * @param baseFilename - The base filename without extension (e.g., 'Entry Title')
+ * @returns An array of entry objects with their locale codes. Returns empty array if directory doesn't exist.
+ *
+ * @example
+ * // For files: Entry.en-us.yaml, Entry.fr.yaml
+ * const locales = await loadEntryLocales('./entries/event', 'Entry', 'Entry');
+ * // Returns: [
+ * //   { entry: {...}, locale: 'en-us' },
+ * //   { entry: {...}, locale: 'fr' }
+ * // ]
+ *
+ * @example
+ * // For single file: Entry.yaml
+ * const locales = await loadEntryLocales('./entries/event', 'Entry', 'Entry');
+ * // Returns: [{ entry: {...}, locale: 'default' }]
+ */
+export default async function loadEntryLocales(
+	directory: string,
+	entryTitle: Entry['title'],
+	baseFilename: string,
+): Promise<readonly EntryWithLocale[]> {
+	const results: EntryWithLocale[] = [];
+
+	try {
+		const files = await readdir(directory);
+		const multiLocalePattern = createMultiLocalePattern(baseFilename);
+		const singleLocaleFilename = `${baseFilename}.yaml`;
+
+		for (const file of files) {
+			const localeEntry = await tryLoadLocaleFile(
+				file,
+				directory,
+				entryTitle,
+				multiLocalePattern,
+				singleLocaleFilename,
+			);
+
+			if (localeEntry) {
+				results.push(localeEntry);
+			}
+		}
+	} catch (error) {
+		if (isDirectoryNotFoundError(error)) {
+			return [];
+		}
+		throw error;
+	}
+
+	return results;
+}
+
+function createMultiLocalePattern(baseFilename: string): RegExp {
+	return new RegExp(`^${escapeRegex(baseFilename)}\\.([^.]+)\\.yaml$`, 'u');
+}
+
+async function tryLoadLocaleFile(
+	file: string,
+	directory: string,
+	entryTitle: string,
+	multiLocalePattern: RegExp,
+	singleLocaleFilename: string,
+): Promise<EntryWithLocale | null> {
+	const match = file.match(multiLocalePattern);
+	if (match) {
+		const [, locale] = match;
+		if (!locale) {
+			return null;
+		}
+
+		const entry = await loadEntryFile(directory, file, entryTitle);
+		return { entry, locale };
+	}
+
+	if (file === singleLocaleFilename) {
+		const entry = await loadEntryFile(directory, file, entryTitle);
+		return { entry, locale: 'default' };
+	}
+
+	return null;
+}
+
+async function loadEntryFile(
+	directory: string,
+	file: string,
+	entryTitle: string,
+): Promise<Entry> {
+	const filePath = resolve(directory, file);
+	const data = (await readYaml(filePath)) as Record<string, unknown>;
+
+	return {
+		...data,
+		uid: `file: ${entryTitle}`,
+	} as Entry;
+}
+
+function isDirectoryNotFoundError(error: unknown): boolean {
+	return (
+		error !== null &&
+		typeof error === 'object' &&
+		'code' in error &&
+		error.code === 'ENOENT'
+	);
+}

package/src/schema/entries/lib/normalize.ts

@@ -0,0 +1,53 @@
+import type { Entry } from '#cli/cs/entries/Types.js';
+import isRecord from '#cli/util/isRecord.js';
+
+// There are several fields on entries that we have limited control over,
+// and that are not stable across import/export operations.
+//
+// We wish to avoid considering these fields any time we compare two entries.
+//
+// This is used when determining entry equality.
+//
+// Also, we use this set to remove fields from the serialized versions of
+// entries before saving them to the file system, so we do not clutter git
+// histories with inconsequential changes.
+const topLevelBlacklist: ReadonlySet<string> = new Set<string>([
+	'_in_progress', // Don't know what this does, seems to be an internal field.
+	'_version', // Versions change with every import/export and are not stable.
+	'ACL', // Read/Import/Export APIs return different values for this field.
+	'created_at', // Reflects date of last import, not actual creation date.
+	'created_by', // Reflects user who ran import, not actual creator.
+	'uid', // Mutates if an entry is deleted and re-created.
+	'updated_at', // Reflects date of last import, not actual update date.
+	'updated_by', // Reflects user who ran import, not actual updater.
+]);
+
+const subLevelBlacklist: ReadonlySet<string> = new Set<string>(['_metadata']);
+
+export default function normalize(entry: Entry) {
+	return Object.fromEntries(
+		Object.entries(entry).filter(notIn(topLevelBlacklist)).map(normalizeKvP),
+	);
+}
+
+function normalizeKvP([key, value]: [string, unknown]): [string, unknown] {
+	return [key, normalizeValue(value)];
+}
+
+function normalizeValue(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		return value.map(normalizeValue);
+	}
+
+	if (isRecord(value)) {
+		return Object.fromEntries(
+			Object.entries(value).filter(notIn(subLevelBlacklist)).map(normalizeKvP),
+		);
+	}
+
+	return value;
+}
+
+function notIn(list: ReadonlySet<string>) {
+	return ([key]: [string, unknown]) => !list.has(key);
+}

package/src/schema/entries/schemaDirectory.ts

@@ -0,0 +1,12 @@
+import { resolve } from 'node:path';
+import getUi from '../lib/SchemaUi.js';
+
+export default function schemaDirectory(contentTypeUid: string) {
+	const {
+		options: {
+			schema: { schemaPath },
+		},
+	} = getUi();
+
+	return resolve(schemaPath, 'entries', contentTypeUid);
+}

package/src/schema/entries/toContentstack.ts

@@ -0,0 +1,165 @@
+import type { ContentType } from '#cli/cs/content-types/Types.js';
+import deleteEntry from '#cli/cs/entries/delete.js';
+import getEntryLocales from '#cli/cs/entries/getEntryLocales.js';
+import importEntry from '#cli/cs/entries/import.js';
+import type { Entry } from '#cli/cs/entries/Types.js';
+import BeaconReplacer from '#cli/dto/entry/BeaconReplacer.js';
+import type ProgressBar from '#cli/ui/progress/ProgressBar.js';
+import type Ctx from '../ctx/Ctx.js';
+import getUi from '../lib/SchemaUi.js';
+import planMerge from '../xfer/lib/planMerge.js';
+import processPlan from '../xfer/lib/processPlan.js';
+import equality from './equality.js';
+import buildCreator from './lib/buildCreator.js';
+import generateFilenames from './lib/generateFilenames.js';
+import loadEntryLocales from './lib/loadEntryLocales.js';
+import schemaDirectory from './schemaDirectory.js';
+
+export default async function toContentstack(
+	ctx: Ctx,
+	contentType: ContentType,
+	bar: ProgressBar,
+) {
+	const ui = getUi();
+
+	const fsEntriesByTitle = ctx.fs.entries.byTitleFor(contentType.uid);
+	const csEntriesByTitle = ctx.cs.entries.byTitleFor(contentType.uid);
+	const transformer = new BeaconReplacer(ctx, contentType);
+	const filenamesByTitle = generateFilenames(fsEntriesByTitle);
+	const create = buildCreator(ctx, transformer, contentType);
+	const update = buildUpdateFn(
+		ctx,
+		csEntriesByTitle,
+		transformer,
+		contentType,
+		filenamesByTitle,
+	);
+
+	const result = await processPlan<Entry>({
+		create,
+		deletionStrategy: ui.options.schema.deletionStrategy,
+		plan: planMerge(equality, fsEntriesByTitle, csEntriesByTitle),
+		progress: bar,
+		remove: async (entry) =>
+			deleteEntry(ctx.cs.client, contentType.uid, entry.uid),
+		update,
+	});
+
+	for (const title of result.unmodified) {
+		const cs = csEntriesByTitle.get(title);
+		const fs = fsEntriesByTitle.get(title);
+
+		if (cs && !fs && ui.options.schema.deletionStrategy !== 'delete') {
+			// The entry was deleted from the file system, but the user has chosen
+			// to ignore deletions in Contentstack. The item is invalid as a
+			// reference, but does not represent an error state.
+			continue;
+		}
+
+		if (!cs || !fs) {
+			throw new Error(`No matching entry found for ${title}.`);
+		}
+
+		const entry = { ...fs, uid: cs.uid };
+		ctx.references.recordEntryForReferences(contentType.uid, entry);
+	}
+
+	return result;
+}
+
+function buildUpdateFn(
+	ctx: Ctx,
+	csEntriesByTitle: ReadonlyMap<string, Entry>,
+	transformer: BeaconReplacer,
+	contentType: ContentType,
+	filenamesByTitle: ReadonlyMap<Entry['uid'], string>,
+) {
+	return async (entry: Entry) => {
+		const match = csEntriesByTitle.get(entry.title);
+		if (!match) {
+			throw new Error(`No matching entry found for ${entry.title}.`);
+		}
+
+		const fsLocaleVersions = await loadFsLocaleVersions(
+			entry,
+			contentType.uid,
+			filenamesByTitle,
+		);
+
+		const csLocaleSet = await getExistingLocales(ctx, contentType, match.uid);
+
+		await updateAllLocales(
+			ctx,
+			transformer,
+			contentType,
+			fsLocaleVersions,
+			match.uid,
+			csLocaleSet,
+		);
+
+		ctx.references.recordEntryForReferences(contentType.uid, {
+			...entry,
+			uid: match.uid,
+		});
+	};
+}
+
+async function loadFsLocaleVersions(
+	entry: Entry,
+	contentTypeUid: string,
+	filenamesByTitle: ReadonlyMap<Entry['uid'], string>,
+) {
+	const filename = filenamesByTitle.get(entry.title);
+	if (!filename) {
+		throw new Error(`No filename found for entry ${entry.title}.`);
+	}
+
+	const baseFilename = filename.replace(/\.yaml$/u, '');
+	const directory = schemaDirectory(contentTypeUid);
+
+	return loadEntryLocales(directory, entry.title, baseFilename);
+}
+
+async function getExistingLocales(
+	ctx: Ctx,
+	contentType: ContentType,
+	entryUid: string,
+) {
+	const csLocales = await getEntryLocales(
+		ctx.cs.client,
+		contentType.uid,
+		entryUid,
+	);
+	return new Set(csLocales.map((l) => l.code));
+}
+
+async function updateAllLocales(
+	ctx: Ctx,
+	transformer: BeaconReplacer,
+	contentType: ContentType,
+	fsLocaleVersions: Awaited<ReturnType<typeof loadFsLocaleVersions>>,
+	entryUid: string,
+	csLocaleSet: Set<string>,
+) {
+	// Import all locale versions in parallel for better performance
+	const importPromises = fsLocaleVersions.map(async (localeVersion) => {
+		const transformed = transformer.process(localeVersion.entry);
+
+		// Pass undefined for 'default' locale (single-locale backward compat)
+		const locale =
+			localeVersion.locale === 'default' ? undefined : localeVersion.locale;
+		const overwrite = locale
+			? csLocaleSet.has(localeVersion.locale)
+			: csLocaleSet.size > 0;
+
+		return importEntry(
+			ctx.cs.client,
+			contentType.uid,
+			{ ...transformed, uid: entryUid },
+			overwrite,
+			locale,
+		);
+	});
+
+	await Promise.all(importPromises);
+}

package/src/schema/entries/toFilesystem.ts

@@ -0,0 +1,171 @@
+import type { ContentType } from '#cli/cs/content-types/Types.js';
+import exportEntryLocale from '#cli/cs/entries/exportEntryLocale.js';
+import getEntryLocales from '#cli/cs/entries/getEntryLocales.js';
+import type { Entry } from '#cli/cs/entries/Types.js';
+import transformEntry from '#cli/dto/entry/fromCs.js';
+import writeYaml from '#cli/fs/writeYaml.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import escapeRegex from '#cli/util/escapeRegex.js';
+import type ProgressBar from '#cli/ui/progress/ProgressBar.js';
+import { readdir, rm } from 'node:fs/promises';
+import { basename, resolve } from 'node:path';
+import type Ctx from '../ctx/Ctx.js';
+import Filename from '../xfer/Filename.js';
+import planMerge from '../xfer/lib/planMerge.js';
+import processPlan from '../xfer/lib/processPlan.js';
+import equality from './equality.js';
+import generateFilenames from './lib/generateFilenames.js';
+import schemaDirectory from './schemaDirectory.js';
+
+export default async function toFilesystem(
+	ctx: Ctx,
+	contentType: ContentType,
+	bar: ProgressBar,
+) {
+	const directory = schemaDirectory(contentType.uid);
+	const fsEntries = ctx.fs.entries.byTitleFor(contentType.uid);
+	const csEntries = ctx.cs.entries.byTitleFor(contentType.uid);
+	const filenamesByTitle = generateFilenames(csEntries);
+
+	const getBasePath = (entry: Entry) =>
+		resolve(directory, resolveFilename(filenamesByTitle, entry));
+
+	const write = createWriteFn(ctx, contentType, directory, getBasePath);
+	const remove = createRemoveFn(directory, getBasePath);
+
+	return processPlan<Entry>({
+		create: write,
+		deletionStrategy: 'delete',
+		plan: planMerge(equality, csEntries, fsEntries),
+		progress: bar,
+		remove,
+		update: write,
+	});
+}
+
+function createWriteFn(
+	ctx: Ctx,
+	contentType: ContentType,
+	directory: string,
+	getBasePath: (entry: Entry) => string,
+) {
+	return async (entry: Entry) => {
+		let locales: readonly { code: string }[];
+		try {
+			locales = await getEntryLocales(
+				ctx.cs.client,
+				contentType.uid,
+				entry.uid,
+			);
+		} catch {
+			// If the locales endpoint fails (e.g., not supported by Contentstack instance),
+			// fall back to single-locale behavior using entry's locale property
+			if (!entry.locale || typeof entry.locale !== 'string') {
+				// Skip entries without a valid locale
+				getUi().warn(
+					`Warning: Skipping entry "${entry.title}" (${entry.uid}) in ${contentType.uid} - no valid locale information available`,
+				);
+				return;
+			}
+			locales = [{ code: entry.locale }];
+		}
+
+		if (locales.length === 0) {
+			// If no locales available, skip this entry
+			getUi().warn(
+				`Warning: Skipping entry "${entry.title}" (${entry.uid}) in ${contentType.uid} - no locales returned`,
+			);
+			return;
+		}
+
+		// If only one locale, save without locale suffix for backward compatibility
+		const useLocaleSuffix = locales.length > 1;
+
+		// Write all locale versions in parallel for better performance
+		const writePromises = locales.map(async (locale) =>
+			writeLocaleVersion(
+				ctx,
+				contentType,
+				entry,
+				locale.code,
+				getBasePath,
+				useLocaleSuffix,
+			),
+		);
+
+		await Promise.all(writePromises);
+	};
+}
+
+async function writeLocaleVersion(
+	ctx: Ctx,
+	contentType: ContentType,
+	entry: Entry,
+	localeCode: string,
+	getBasePath: (entry: Entry) => string,
+	useLocaleSuffix: boolean,
+) {
+	const exported = await exportEntryLocale(
+		contentType.uid,
+		ctx.cs.client,
+		entry.uid,
+		localeCode,
+	);
+
+	const { uid, ...transformed } = transformEntry(ctx, contentType, exported);
+
+	const basePath = getBasePath(entry);
+	const filePath = useLocaleSuffix
+		? basePath.replace(/\.yaml$/u, `.${localeCode}.yaml`)
+		: basePath;
+	await writeYaml(filePath, transformed);
+}
+
+function createRemoveFn(
+	directory: string,
+	getBasePath: (entry: Entry) => string,
+) {
+	return async (entry: Entry) => {
+		const basePath = getBasePath(entry);
+		const baseFilename = basename(basePath, '.yaml');
+
+		try {
+			const files = await readdir(directory);
+			const pattern = new RegExp(
+				`^${escapeRegex(baseFilename)}\\..*\\.yaml$`,
+				'u',
+			);
+
+			for (const file of files) {
+				// Remove both locale-suffixed files (entry.en-us.yaml) and base file (entry.yaml)
+				if (pattern.test(file) || file === `${baseFilename}.yaml`) {
+					await rm(resolve(directory, file), { force: true });
+				}
+			}
+		} catch {
+			// Directory might not exist, which is fine
+		}
+	};
+}
+
+function resolveFilename(
+	filenamesByTitle: ReadonlyMap<Entry['title'], string>,
+	entry: Entry,
+) {
+	if (Filename in entry) {
+		const embedded = entry[Filename];
+		if (typeof embedded === 'string') {
+			return embedded;
+		}
+
+		throw new Error(`Invalid embedded filename for entry ${entry.uid}`);
+	}
+
+	const generated = filenamesByTitle.get(entry.title);
+	if (!generated) {
+		const msg = `No filename found for entry [${entry.uid}]: ${entry.title}`;
+		throw new Error(msg);
+	}
+
+	return generated;
+}

package/src/schema/entries/updateMissedReferences.ts

@@ -0,0 +1,49 @@
+import importEntry from '#cli/cs/entries/import.js';
+import type { ReferencePath } from '#cli/cs/entries/Types.js';
+import transformEntry from '#cli/dto/entry/toCs.js';
+import ProgressReporter from '#cli/ui/progress/ProgressReporter.js';
+import type Ctx from '../ctx/Ctx.js';
+import getUi from '../lib/SchemaUi.js';
+import type TransferResults from '../xfer/TransferResults.js';
+import { MutableTransferResults } from '../xfer/TransferResults.js';
+
+export default async function updateMissedReferences(
+	ctx: Ctx,
+): Promise<TransferResults> {
+	const { references } = ctx;
+	const { missed } = references;
+	const results = new MutableTransferResults();
+
+	if (missed === 0) {
+		return results;
+	}
+
+	using bar = getUi().createProgressBar('References', missed);
+	const minimalCtx = { cs: ctx.cs, references: references.seal() };
+
+	for (const [
+		contentTypeUid,
+		entry,
+	] of references.entriesWithMissedReferences()) {
+		const contentType = ctx.fs.contentTypes.get(contentTypeUid);
+		if (!contentType) {
+			throw new Error(`Content type not found: ${contentTypeUid}`);
+		}
+
+		const refPath: ReferencePath = `${contentType.uid}/${entry.title}`;
+		using reporter = new ProgressReporter(bar, 'updating', refPath);
+
+		try {
+			const transformed = transformEntry(minimalCtx, contentType, entry);
+			await importEntry(ctx.cs.client, contentTypeUid, transformed, true);
+			results.updated.add(refPath);
+		} catch (ex: unknown) {
+			results.errored.set(refPath, ex);
+		} finally {
+			bar.increment();
+			reporter.finish('updated');
+		}
+	}
+
+	return results;
+}

package/src/schema/global-fields/schemaDirectory.ts

@@ -0,0 +1,12 @@
+import { resolve } from 'node:path';
+import getUi from '../lib/SchemaUi.js';
+
+export default function schemaDirectory() {
+	const {
+		options: {
+			schema: { schemaPath },
+		},
+	} = getUi();
+
+	return resolve(schemaPath, 'global-fields');
+}

package/src/schema/global-fields/toContentstack.ts

@@ -0,0 +1,31 @@
+import deleteGlobalField from '#cli/cs/global-fields/delete.js';
+import importGlobalField from '#cli/cs/global-fields/import.js';
+import type { Schema } from '#cli/cs/Types.js';
+import { isSchema, itemKey } from '#cli/cs/Types.js';
+import transform from '#cli/dto/schema/toCs.js';
+import type Ctx from '../ctx/Ctx.js';
+import equality from '../isEquivalentSchema.js';
+import createProgressBar from '../lib/createProgressBar.js';
+import getUi from '../lib/SchemaUi.js';
+import indexFromFilesystem from '../xfer/indexFromFilesystem.js';
+import planMerge from '../xfer/lib/planMerge.js';
+import processPlan from '../xfer/lib/processPlan.js';
+import schemaDirectory from './schemaDirectory.js';
+
+export default async function toContentstack(ctx: Ctx) {
+	const ui = getUi();
+	const directory = schemaDirectory();
+	const fsFields = await indexFromFilesystem(directory, isSchema, itemKey);
+	using bar = createProgressBar('Global Fields', ctx.cs.globalFields, fsFields);
+
+	return await processPlan<Schema>({
+		create: async (schema) =>
+			importGlobalField(ctx.cs.client, false, transform(schema)),
+		deletionStrategy: ui.options.schema.deletionStrategy,
+		plan: planMerge(equality, fsFields, ctx.cs.globalFields),
+		progress: bar,
+		remove: async (schema) => deleteGlobalField(ctx.cs.client, schema.uid),
+		update: async (schema) =>
+			importGlobalField(ctx.cs.client, true, transform(schema)),
+	});
+}

package/src/schema/global-fields/toFilesystem.ts

@@ -0,0 +1,38 @@
+import exportGlobalField from '#cli/cs/global-fields/export.js';
+import type { Schema } from '#cli/cs/Types.js';
+import { isSchema, itemKey } from '#cli/cs/Types.js';
+import writeYaml from '#cli/fs/writeYaml.js';
+import { rm } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import fromCs from '../../dto/schema/fromCs.js';
+import type Ctx from '../ctx/Ctx.js';
+import isEquivalentSchema from '../isEquivalentSchema.js';
+import createProgressBar from '../lib/createProgressBar.js';
+import indexFromFilesystem from '../xfer/indexFromFilesystem.js';
+import planMerge from '../xfer/lib/planMerge.js';
+import processPlan from '../xfer/lib/processPlan.js';
+import schemaDirectory from './schemaDirectory.js';
+
+export default async function toFilesystem(ctx: Ctx) {
+	const directory = schemaDirectory();
+	const getPath = (uid: string) => resolve(directory, `${uid}.yaml`);
+
+	const write = async (schema: Schema) => {
+		const exported = await exportGlobalField(ctx.cs.client, schema.uid);
+		const transformed = fromCs(exported);
+		await writeYaml(getPath(schema.uid), transformed);
+	};
+
+	const fs = await indexFromFilesystem(directory, isSchema, itemKey);
+
+	using bar = createProgressBar('Global Fields', fs, ctx.cs.globalFields);
+
+	return await processPlan<Schema>({
+		create: write,
+		deletionStrategy: 'delete',
+		plan: planMerge(isEquivalentSchema, ctx.cs.globalFields, fs),
+		progress: bar,
+		remove: async (schema) => rm(getPath(schema.uid), { force: true }),
+		update: write,
+	});
+}

package/src/schema/isEquivalentSchema.test.ts

@@ -0,0 +1,24 @@
+import type { Schema } from '#cli/cs/Types.js';
+import readFixture from '#test/fixtures/readFixture';
+import { expect, test } from 'vitest';
+import { parse } from 'yaml';
+import isEquivalentSchema from './isEquivalentSchema.js';
+
+test('Equal schemas are equal', () => {
+	const simpleSchema = { schema: [], title: 'title', uid: 'uid' };
+	expect(isEquivalentSchema(simpleSchema, simpleSchema)).toBe(true);
+});
+
+['navigation'].forEach((fixtureName) =>
+	test(`Fixtures are equivalent: ${fixtureName}`, async () => {
+		const [x, y] = await Promise.all([
+			readFixture(`${fixtureName}-read.yaml`),
+			readFixture(`${fixtureName}-export.yaml`),
+		]);
+
+		const read = parse(x) as Schema;
+		const exportFixture = parse(y) as Schema;
+
+		expect(isEquivalentSchema(read, exportFixture)).toBe(true);
+	}),
+);