@arkebcacy/beacon-cli-temp 0.1.1

package/src/schema/entries/equality.ts

@@ -0,0 +1,7 @@
+import type { Entry } from '#cli/cs/entries/Types.js';
+import { isDeepStrictEqual } from 'node:util';
+import normalize from './lib/normalize.js';
+
+export default function equality(a: Entry, b: Entry) {
+	return isDeepStrictEqual(normalize(a), normalize(b));
+}

package/src/schema/entries/indexAllFsEntries.ts

@@ -0,0 +1,149 @@
+import type { ContentType } from '#cli/cs/content-types/Types.js';
+import type { Entry } from '#cli/cs/entries/Types.js';
+import { isEntry } from '#cli/cs/entries/Types.js';
+import readYaml from '#cli/fs/readYaml.js';
+import type OmitIndex from '#cli/util/OmitIndex.js';
+import { readdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import indexContentTypes from '../content-types/indexFromFilesystem.js';
+import getUi from '../lib/SchemaUi.js';
+import schemaDirectory from './schemaDirectory.js';
+
+export default async function indexAllFsEntries(): Promise<
+	ReadonlyMap<ContentType, ReadonlySet<Entry>>
+> {
+	const contentTypes = await indexContentTypes();
+	const entries = new Map<ContentType, ReadonlySet<Entry>>();
+
+	for (const contentType of contentTypes.values()) {
+		const contentTypeEntries = await loadContentTypeEntries(contentType);
+		entries.set(contentType, contentTypeEntries);
+	}
+
+	return entries;
+}
+
+async function loadContentTypeEntries(
+	contentType: ContentType,
+): Promise<ReadonlySet<Entry>> {
+	const dir = schemaDirectory(contentType.uid);
+	const entriesSet = new Set<Entry>();
+
+	try {
+		const files = await readdir(dir);
+		const yamlFiles = files.filter((f) => f.endsWith('.yaml'));
+		const entriesByTitle = await groupEntriesByTitle(dir, yamlFiles);
+
+		// For each entry title, pick one locale version to represent it
+		for (const [entryTitle, localeMap] of entriesByTitle.entries()) {
+			const preferredEntry = selectPreferredLocale(localeMap);
+			if (preferredEntry) {
+				entriesSet.add({
+					...preferredEntry,
+					uid: `file: ${preferredEntry.title}`,
+				});
+			} else {
+				// Log warning if entry has files but no valid locale versions
+				getUi().warn(
+					`Warning: Entry "${entryTitle}" in ${contentType.uid} has files but no valid locale versions could be selected`,
+				);
+			}
+		}
+	} catch (error) {
+		if (
+			error &&
+			typeof error === 'object' &&
+			'code' in error &&
+			error.code === 'ENOENT'
+		) {
+			// Directory doesn't exist, which is fine
+			return entriesSet;
+		}
+		throw error;
+	}
+
+	return entriesSet;
+}
+
+async function groupEntriesByTitle(
+	dir: string,
+	yamlFiles: readonly string[],
+): Promise<Map<string, Map<string, FsEntry>>> {
+	const entriesByTitle = new Map<string, Map<string, FsEntry>>();
+
+	for (const file of yamlFiles) {
+		// Try to match multi-locale pattern first: title.locale.yaml
+		const multiLocaleMatch = /^(?<title>.+)\.(?<locale>[^.]+)\.yaml$/u.exec(
+			file,
+		);
+
+		let entryTitle: string;
+		let locale: string;
+
+		if (
+			multiLocaleMatch?.groups?.title &&
+			multiLocaleMatch.groups.locale &&
+			isValidLocaleCode(multiLocaleMatch.groups.locale)
+		) {
+			// Multi-locale file with valid locale code
+			const { title, locale: localeCode } = multiLocaleMatch.groups;
+			entryTitle = title;
+			locale = localeCode;
+		} else {
+			// Try single-locale pattern: title.yaml
+			const singleLocaleMatch = /^(?<title>.+)\.yaml$/u.exec(file);
+			if (!singleLocaleMatch?.groups?.title) {
+				// Skip files that don't match either pattern
+				continue;
+			}
+			entryTitle = singleLocaleMatch.groups.title;
+			locale = 'default'; // Use 'default' as locale for backward compatibility
+		}
+
+		const filePath = resolve(dir, file);
+		const data = (await readYaml(filePath)) as Record<string, unknown>;
+
+		if (!isFsEntry(data)) {
+			continue;
+		}
+
+		let localeMap = entriesByTitle.get(entryTitle);
+		if (!localeMap) {
+			localeMap = new Map();
+			entriesByTitle.set(entryTitle, localeMap);
+		}
+
+		localeMap.set(locale, data);
+	}
+
+	return entriesByTitle;
+}
+
+function selectPreferredLocale(
+	localeMap: Map<string, FsEntry>,
+): FsEntry | undefined {
+	// Prefer 'default' (single-locale file), then en-us, then the first available locale
+	return (
+		localeMap.get('default') ??
+		localeMap.get('en-us') ??
+		[...localeMap.values()][0]
+	);
+}
+
+type FsEntry = Omit<OmitIndex<Entry>, 'uid'> & Record<string, unknown>;
+
+function isFsEntry(o: Record<string, unknown>): o is FsEntry {
+	return isEntry({ ...o, uid: 'uid' });
+}
+
+/**
+ * Validates if a string is a valid locale code.
+ * Valid locale codes contain only letters (case-insensitive), hyphens, and underscores.
+ * Examples: en-us, fr, de-DE, zh_CN
+ * This prevents misidentifying filenames like "Entry.Title.yaml" as "Entry" with locale "Title"
+ */
+function isValidLocaleCode(code: string): boolean {
+	// Locale codes: 2-3 letter language code, optionally followed by separator and 2-4 letter region code
+	// Pattern matches: en, en-us, en-US, fr-CA, zh_CN, etc.
+	return /^[a-z]{2,3}(?:[_-][a-z]{2,4})?$/iu.test(code);
+}

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

@@ -0,0 +1,207 @@
+import type { Schema } from '#cli/cs/Types.js';
+import type Client from '#cli/cs/api/Client.js';
+import ContentstackError from '#cli/cs/api/ContentstackError.js';
+import type { ContentType } from '#cli/cs/content-types/Types.js';
+import type { Entry } from '#cli/cs/entries/Types.js';
+import importEntry from '#cli/cs/entries/import.js';
+import indexEntries from '#cli/cs/entries/index.js';
+import type BeaconReplacer from '#cli/dto/entry/BeaconReplacer.js';
+import type Ctx from '#cli/schema/ctx/Ctx.js';
+import getUi from '#cli/schema/lib/SchemaUi.js';
+import createStylus from '#cli/ui/createStylus.js';
+import { isDeepStrictEqual } from 'node:util';
+import schemaDirectory from '../schemaDirectory.js';
+import generateFilenames from './generateFilenames.js';
+import loadEntryLocales from './loadEntryLocales.js';
+
+export default function buildCreator(
+	ctx: Ctx,
+	transformer: BeaconReplacer,
+	contentType: ContentType,
+) {
+	return async (entry: Entry) => {
+		const fsLocaleVersions = await loadLocaleVersions(entry, contentType.uid);
+
+		const created = await createFirstLocale(
+			ctx,
+			transformer,
+			contentType,
+			fsLocaleVersions,
+		);
+
+		await importAdditionalLocales(
+			ctx,
+			transformer,
+			contentType,
+			fsLocaleVersions,
+			created,
+		);
+
+		ctx.references.recordEntryForReferences(contentType.uid, {
+			...entry,
+			uid: created.uid,
+		});
+	};
+}
+
+async function loadLocaleVersions(entry: Entry, contentTypeUid: string) {
+	const filenamesByTitle = generateFilenames(new Map([[entry.title, entry]]));
+	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);
+	const fsLocaleVersions = await loadEntryLocales(
+		directory,
+		entry.title,
+		baseFilename,
+	);
+
+	if (fsLocaleVersions.length === 0) {
+		throw new Error(`No locale versions found for entry ${entry.title}.`);
+	}
+
+	return fsLocaleVersions;
+}
+
+async function createFirstLocale(
+	ctx: Ctx,
+	transformer: BeaconReplacer,
+	contentType: ContentType,
+	fsLocaleVersions: Awaited<ReturnType<typeof loadLocaleVersions>>,
+): Promise<Entry> {
+	const [firstLocale] = fsLocaleVersions;
+
+	if (!firstLocale) {
+		throw new Error('No locale versions found');
+	}
+
+	const transformed = transformer.process(firstLocale.entry);
+
+	// Pass undefined for 'default' locale (single-locale backward compat)
+	const locale =
+		firstLocale.locale === 'default' ? undefined : firstLocale.locale;
+
+	try {
+		return await importEntry(
+			ctx.cs.client,
+			contentType.uid,
+			transformed,
+			false,
+			locale,
+		);
+	} catch (ex) {
+		return await handleDuplicateKeyError(
+			ex,
+			ctx,
+			contentType,
+			transformed,
+			locale,
+		);
+	}
+}
+
+async function handleDuplicateKeyError(
+	ex: unknown,
+	ctx: Ctx,
+	contentType: ContentType,
+	transformed: ReturnType<BeaconReplacer['process']>,
+	locale: string | undefined,
+): Promise<Entry> {
+	if (isDuplicateKeyError(ex)) {
+		const uid = await getUidByTitle(
+			ctx.cs.client,
+			ctx.cs.globalFields,
+			contentType,
+			transformed.title,
+		);
+
+		if (!uid) {
+			logInvalidState(contentType.title, transformed.title);
+			const newError = new Error(
+				`Failed to create entry ${transformed.title}: Contentstack reported a duplicate title but the entry was not found after re-indexing`,
+			);
+			// Preserve the original error as the cause
+			if (ex instanceof Error) {
+				newError.cause = ex;
+			}
+			throw newError;
+		}
+
+		return await importEntry(
+			ctx.cs.client,
+			contentType.uid,
+			{ ...transformed, uid },
+			true,
+			locale,
+		);
+	}
+
+	throw ex;
+}
+
+async function importAdditionalLocales(
+	ctx: Ctx,
+	transformer: BeaconReplacer,
+	contentType: ContentType,
+	fsLocaleVersions: Awaited<ReturnType<typeof loadLocaleVersions>>,
+	created: Entry,
+) {
+	// Import all additional locale versions in parallel for better performance
+	const importPromises = fsLocaleVersions
+		.slice(1)
+		.map(async (localeVersion) => {
+			if (localeVersion.locale === 'default') {
+				// Skip 'default' locale (already handled by first locale)
+				return;
+			}
+
+			const localeTransformed = transformer.process(localeVersion.entry);
+
+			return importEntry(
+				ctx.cs.client,
+				contentType.uid,
+				{ ...localeTransformed, uid: created.uid },
+				false,
+				localeVersion.locale,
+			);
+		});
+
+	await Promise.all(importPromises);
+}
+
+function isDuplicateKeyError(ex: unknown) {
+	if (!(ex instanceof ContentstackError)) {
+		return false;
+	}
+
+	const invalidDataCode = 119;
+	if (ex.code !== invalidDataCode) {
+		return false;
+	}
+
+	return isDeepStrictEqual(ex.details, { title: ['is not unique.'] });
+}
+
+async function getUidByTitle(
+	client: Client,
+	globalFieldsByUid: ReadonlyMap<Schema['uid'], Schema>,
+	contentType: ContentType,
+	title: string,
+) {
+	const entries = await indexEntries(client, globalFieldsByUid, contentType);
+	return entries.get(title)?.uid;
+}
+
+function logInvalidState(contentTypeTitle: string, entryTitle: string) {
+	const y = createStylus('yellowBright');
+	const ui = getUi();
+	const msg1 = y`While importing ${contentTypeTitle} entry ${entryTitle},`;
+	const msg2 = 'Contentstack reported a duplicate key error based on the';
+	const msg3 = 'title, but no entry with that title was found after';
+	const msg4 = 're-indexing.';
+	const msg = [msg1, msg2, msg3, msg4].join(' ');
+	ui.warn(msg);
+}

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

@@ -0,0 +1,77 @@
+import type { Entry } from '#cli/cs/entries/Types.js';
+import sanitize from 'sanitize-filename';
+
+// This function generates a list of unique filenames for all entries, based
+// on the outputs of the sanitizeFilenames function. It then disambiguates the
+// filenames by appending a number to the end of each filename that is not
+// already unique.
+export default function generateFilenames(
+	entriesByTitle: ReadonlyMap<Entry['title'], Entry>,
+): ReadonlyMap<Entry['uid'], string> {
+	const { byFilename, byTitle } = sanitizeFilenames(entriesByTitle);
+	const result = new Map<string, string>();
+
+	for (const title of entriesByTitle.keys()) {
+		const filename = byTitle.get(title);
+
+		if (!filename) {
+			throw new Error(`No filename for entry ${title}`);
+		}
+
+		const lc = filename.toLowerCase();
+		const siblings = byFilename.get(lc) ?? new Set<Entry['title']>();
+
+		if (siblings.size === 1) {
+			result.set(title, filename + '.yaml');
+			continue;
+		}
+
+		const sorted = [...siblings].sort();
+
+		const idx = sorted.indexOf(title);
+		if (idx === -1) {
+			throw new Error(`No index for entry ${title}`);
+		}
+
+		result.set(title, `${filename} (${(idx + 1).toLocaleString()}).yaml`);
+	}
+
+	return result;
+}
+
+// This creates a map of sanitized filenames to sets of entry titles.
+//
+// This is to deal with the possibility that two entries have titles that
+// sanitize to the same filename. We need to detect all of these cases so that
+// the filenames can be disambiguated.
+function sanitizeFilenames(
+	entriesByTitle: ReadonlyMap<Entry['title'], Entry>,
+): {
+	readonly byFilename: ReadonlyMap<string, ReadonlySet<Entry['title']>>;
+	readonly byTitle: ReadonlyMap<Entry['title'], string>;
+} {
+	const byFilename = new Map<string, Set<Entry['title']>>();
+	const byTitle = new Map<Entry['title'], string>();
+
+	for (const entry of entriesByTitle.values()) {
+		const sanitized = sanitizeFilename(entry.title);
+		const lc = sanitized.toLowerCase();
+		const existing = byFilename.get(lc);
+
+		if (existing) {
+			existing.add(entry.title);
+		} else {
+			byFilename.set(lc, new Set([entry.title]));
+		}
+
+		byTitle.set(entry.title, sanitized);
+	}
+
+	return { byFilename, byTitle };
+}
+
+function sanitizeFilename(name: string): string {
+	const raw = name.trim();
+	const sanitized = sanitize(raw, { replacement: '_' });
+	return sanitized.trim() || 'Untitled';
+}

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

@@ -0,0 +1,152 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import type { PathLike } from 'node:fs';
+import loadEntryLocales from './loadEntryLocales.js';
+
+// Mock the file system modules
+vi.mock('node:fs/promises', () => ({
+	readdir: vi.fn(),
+}));
+
+vi.mock('#cli/fs/readYaml.js', () => ({
+	default: vi.fn(),
+}));
+
+describe(loadEntryLocales.name, () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it('should return empty array when directory does not exist', async () => {
+		const { readdir } = await import('node:fs/promises');
+		vi.mocked(readdir).mockRejectedValue({ code: 'ENOENT' });
+
+		const result = await loadEntryLocales(
+			'/nonexistent/directory',
+			'Test Entry',
+			'test_entry',
+		);
+
+		expect(result).toEqual([]);
+	});
+
+	it('should load single locale file without suffix', async () => {
+		const { readdir } = await import('node:fs/promises');
+		const readYaml = (await import('#cli/fs/readYaml.js')).default;
+
+		vi.mocked(readdir).mockResolvedValue([
+			'test_entry.yaml',
+			'other_entry.yaml',
+		] as unknown as Awaited<ReturnType<typeof readdir>>);
+
+		vi.mocked(readYaml).mockResolvedValue({
+			title: 'Test Entry',
+		});
+
+		const result = await loadEntryLocales(
+			'/test/directory',
+			'Test Entry',
+			'test_entry',
+		);
+
+		expect(result).toHaveLength(1);
+		expect(result[0]?.locale).toBe('default');
+		expect(result[0]?.entry.title).toBe('Test Entry');
+	});
+
+	it('should load multiple locale files for an entry', async () => {
+		const { readdir } = await import('node:fs/promises');
+		const readYaml = (await import('#cli/fs/readYaml.js')).default;
+
+		// Justification: Test has exactly 3 locale files
+
+		const expectedLocaleCount = 3;
+
+		vi.mocked(readdir).mockResolvedValue([
+			'test_entry.en-us.yaml',
+			'test_entry.fr.yaml',
+			'test_entry.de.yaml',
+			'other_entry.yaml',
+		] as unknown as Awaited<ReturnType<typeof readdir>>);
+
+		vi.mocked(readYaml).mockImplementation(async (path: PathLike) => {
+			const pathStr = String(path);
+			if (pathStr.includes('en-us')) {
+				return Promise.resolve({ locale: 'en-us', title: 'Test Entry' });
+			}
+			if (pathStr.includes('fr')) {
+				return Promise.resolve({ locale: 'fr', title: 'Test Entry' });
+			}
+			if (pathStr.includes('de')) {
+				return Promise.resolve({ locale: 'de', title: 'Test Entry' });
+			}
+			return Promise.resolve({});
+		});
+
+		const result = await loadEntryLocales(
+			'/test/directory',
+			'Test Entry',
+			'test_entry',
+		);
+
+		expect(result).toHaveLength(expectedLocaleCount);
+		expect(result.map((r) => r.locale)).toEqual(['en-us', 'fr', 'de']);
+	});
+
+	it('should handle entries with dots in filename', async () => {
+		const { readdir } = await import('node:fs/promises');
+		const readYaml = (await import('#cli/fs/readYaml.js')).default;
+
+		// Justification: Test has exactly 2 locale files
+
+		const expectedLocaleCount = 2;
+
+		vi.mocked(readdir).mockResolvedValue([
+			'Entry.With.Dots.en-us.yaml',
+			'Entry.With.Dots.fr-ca.yaml',
+		] as unknown as Awaited<ReturnType<typeof readdir>>);
+
+		vi.mocked(readYaml).mockImplementation(async (path: PathLike) => {
+			const pathStr = String(path);
+			if (pathStr.includes('en-us')) {
+				return Promise.resolve({
+					locale: 'en-us',
+					title: 'Entry.With.Dots',
+				});
+			}
+			if (pathStr.includes('fr-ca')) {
+				return Promise.resolve({
+					locale: 'fr-ca',
+					title: 'Entry.With.Dots',
+				});
+			}
+			return Promise.resolve({});
+		});
+
+		const result = await loadEntryLocales(
+			'/test/directory',
+			'Entry.With.Dots',
+			'Entry.With.Dots',
+		);
+
+		expect(result).toHaveLength(expectedLocaleCount);
+		expect(result.map((r) => r.locale)).toEqual(['en-us', 'fr-ca']);
+	});
+
+	it('should set synthetic uid for filesystem entries', async () => {
+		const { readdir } = await import('node:fs/promises');
+		const readYaml = (await import('#cli/fs/readYaml.js')).default;
+
+		vi.mocked(readdir).mockResolvedValue([
+			'test_entry.yaml',
+		] as unknown as Awaited<ReturnType<typeof readdir>>);
+		vi.mocked(readYaml).mockResolvedValue({ title: 'Test Entry' });
+
+		const result = await loadEntryLocales(
+			'/test/directory',
+			'Test Entry',
+			'test_entry',
+		);
+
+		expect(result[0]?.entry.uid).toBe('file: Test Entry');
+	});
+});