@arkebcacy/beacon-cli-temp 0.1.6 → 0.1.8

package/package.json

@@ -50,5 +50,5 @@
     "prepack": "node ./build/prepack.js"
   },
   "type": "module",
-  "version": "0.1.6"
+  "version": "0.1.8"
 }

package/src/cs/labels/Label.ts

@@ -4,13 +4,9 @@ import { isItem } from '../Types.js';
 
 export default interface Label extends OmitIndex<Item> {
 	readonly name: string;
-	readonly parent_uid: string | null;
+	readonly parent: readonly string[];
 }
 
 export function isLabel(o: unknown): o is Label {
-	return (
-		isItem(o) &&
-		typeof o.name === 'string' &&
-		(o.parent_uid === null || typeof o.parent_uid === 'string')
-	);
+	return isItem(o) && typeof o.name === 'string' && Array.isArray(o.parent);
 }

package/src/cs/labels/getAllLabels.ts

@@ -30,7 +30,7 @@ export default async function getAllLabels(client: Client): Promise<Label[]> {
 			const label: Label = {
 				...raw,
 				name: raw.name,
-				parent_uid: typeof raw.parent_uid === 'string' ? raw.parent_uid : null,
+				parent: Array.isArray(raw.parent) ? raw.parent : [],
 				uid: raw.uid,
 			};
 			if (isLabel(label)) {

package/src/cs/locales/addLocale.ts

@@ -0,0 +1,59 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import isRecord from '#cli/util/isRecord.js';
+import type { Locale } from './getLocales.js';
+
+interface AddLocaleRequest {
+	readonly locale: {
+		readonly code: string;
+		readonly fallback_locale?: string;
+		readonly name?: string;
+	};
+}
+
+/**
+ * Adds a new locale to the stack.
+ * @param client - Contentstack API client
+ * @param code - Locale code (e.g., 'zh-cn', 'zh-chs')
+ * @param name - Display name for the locale (e.g., 'Chinese - China')
+ * @param fallbackLocale - Optional fallback locale code
+ */
+export async function addLocale(
+	client: Client,
+	code: string,
+	name?: string,
+	fallbackLocale?: string,
+): Promise<Locale> {
+	const requestBody: AddLocaleRequest = {
+		locale: {
+			code,
+			...(fallbackLocale !== undefined && { fallback_locale: fallbackLocale }),
+			...(name !== undefined && { name }),
+		},
+	};
+
+	const response = await client.POST('/v3/locales', {
+		body: requestBody as never,
+	});
+
+	const msg = `Failed to add locale '${code}'`;
+	ContentstackError.throwIfError(response.error, msg);
+
+	if (!response.response.ok) {
+		throw new Error(msg);
+	}
+
+	const { data } = response;
+
+	if (!isRecord(data)) {
+		throw new TypeError(msg);
+	}
+
+	const { locale } = data;
+
+	if (!isRecord(locale)) {
+		throw new TypeError(msg);
+	}
+
+	return locale as Locale;
+}

package/src/cs/locales/ensureLocaleExists.ts

@@ -0,0 +1,51 @@
+import type Client from '../api/Client.js';
+import { addLocale } from './addLocale.js';
+import { getLocales } from './getLocales.js';
+import type { Locale } from './getLocales.js';
+
+/**
+ * Ensures a locale exists in the target stack. If it doesn't exist, creates it.
+ * @param client - Contentstack API client
+ * @param localeCode - Locale code to ensure exists (e.g., 'zh-cn')
+ * @param fallbackLocale - Optional fallback locale code (defaults to 'en-us')
+ * @returns The locale object (either existing or newly created)
+ */
+export async function ensureLocaleExists(
+	client: Client,
+	localeCode: string,
+	fallbackLocale = 'en-us',
+): Promise<Locale> {
+	const existingLocales = await getLocales(client);
+	const existing = existingLocales.find((loc) => loc.code === localeCode);
+
+	if (existing !== undefined) {
+		return existing;
+	}
+
+	// Locale doesn't exist - create it
+
+	// Derive a reasonable display name from the locale code
+	const name = deriveLocaleName(localeCode);
+
+	const newLocale = await addLocale(client, localeCode, name, fallbackLocale);
+
+	return newLocale;
+}
+
+/**
+ * Derives a human-readable name from a locale code.
+ * This is a basic implementation that can be expanded as needed.
+ */
+function deriveLocaleName(code: string): string {
+	const nameMap: Record<string, string> = {
+		'en-us': 'English - United States',
+		'zh-chs': 'Chinese (simplified)',
+		'zh-cht': 'Chinese (traditional)',
+		'zh-cn': 'Chinese - China',
+		'zh-hans': 'Chinese (simplified)',
+		'zh-hant': 'Chinese (traditional)',
+		'zh-tw': 'Chinese - Taiwan',
+	};
+
+	return nameMap[code.toLowerCase()] ?? code.toUpperCase();
+}

package/src/cs/locales/getLocales.ts

@@ -0,0 +1,38 @@
+import type Client from '../api/Client.js';
+import ContentstackError from '../api/ContentstackError.js';
+import isRecord from '#cli/util/isRecord.js';
+
+export interface Locale {
+	readonly code: string;
+	readonly fallback_locale?: string;
+	readonly name: string;
+	readonly uid: string;
+}
+
+/**
+ * Fetches all locales configured for a stack.
+ */
+export async function getLocales(client: Client): Promise<readonly Locale[]> {
+	const response = await client.GET('/v3/locales', {});
+
+	const msg = 'Failed to fetch locales';
+	ContentstackError.throwIfError(response.error, msg);
+
+	if (!response.response.ok) {
+		throw new Error(msg);
+	}
+
+	const { data } = response;
+
+	if (!isRecord(data)) {
+		throw new TypeError(msg);
+	}
+
+	const { locales } = data;
+
+	if (!Array.isArray(locales)) {
+		throw new TypeError(msg);
+	}
+
+	return locales as Locale[];
+}

package/src/dto/labels/flatten.test.ts

@@ -18,9 +18,9 @@ describe('flatten', () => {
 		const result = flatten(tree);
 
 		expect(result).toEqual([
-			{ name: 'Parent', parent_uid: null, uid: 'parent' },
-			{ name: 'Child 1', parent_uid: 'parent', uid: 'child1' },
-			{ name: 'Child 2', parent_uid: 'parent', uid: 'child2' },
+			{ name: 'Parent', parent: [], uid: 'parent' },
+			{ name: 'Child 1', parent: ['parent'], uid: 'child1' },
+			{ name: 'Child 2', parent: ['parent'], uid: 'child2' },
 		]);
 	});
 
@@ -40,10 +40,10 @@ describe('flatten', () => {
 		const result = flatten(tree);
 
 		expect(result).toEqual([
-			{ name: 'Component', parent_uid: null, uid: 'component' },
-			{ name: 'Calculator', parent_uid: 'component', uid: 'calculator' },
-			{ name: 'Data', parent_uid: 'component', uid: 'data' },
-			{ name: 'Page', parent_uid: 'component', uid: 'page' },
+			{ name: 'Component', parent: [], uid: 'component' },
+			{ name: 'Calculator', parent: ['component'], uid: 'calculator' },
+			{ name: 'Data', parent: ['component'], uid: 'data' },
+			{ name: 'Page', parent: ['component'], uid: 'page' },
 		]);
 	});
 
@@ -71,10 +71,10 @@ describe('flatten', () => {
 		const result = flatten(tree);
 
 		expect(result).toEqual([
-			{ name: 'Root', parent_uid: null, uid: 'root' },
-			{ name: 'Level 1', parent_uid: 'root', uid: 'level1' },
-			{ name: 'Level 2', parent_uid: 'level1', uid: 'level2' },
-			{ name: 'Level 3', parent_uid: 'level2', uid: 'level3' },
+			{ name: 'Root', parent: [], uid: 'root' },
+			{ name: 'Level 1', parent: ['root'], uid: 'level1' },
+			{ name: 'Level 2', parent: ['level1'], uid: 'level2' },
+			{ name: 'Level 3', parent: ['level2'], uid: 'level3' },
 		]);
 	});
 
@@ -91,9 +91,9 @@ describe('flatten', () => {
 		const result = flatten(tree);
 
 		expect(result).toEqual([
-			{ name: 'Label 1', parent_uid: null, uid: 'label1' },
-			{ name: 'Label 2', parent_uid: null, uid: 'label2' },
-			{ name: 'Child', parent_uid: 'label2', uid: 'child' },
+			{ name: 'Label 1', parent: [], uid: 'label1' },
+			{ name: 'Label 2', parent: [], uid: 'label2' },
+			{ name: 'Child', parent: ['label2'], uid: 'child' },
 		]);
 	});
 
@@ -111,8 +111,8 @@ describe('flatten', () => {
 		const result = flatten(tree);
 
 		expect(result).toEqual([
-			{ name: 'Label 1', parent_uid: null, uid: 'label1' },
-			{ name: 'Label 2', parent_uid: null, uid: 'label2' },
+			{ name: 'Label 1', parent: [], uid: 'label1' },
+			{ name: 'Label 2', parent: [], uid: 'label2' },
 		]);
 	});
 });

package/src/dto/labels/flatten.ts

@@ -12,7 +12,7 @@ export default function flatten(
 
 			result.push({
 				...label,
-				parent_uid: parentUid,
+				parent: parentUid ? [parentUid] : [],
 			} as Label);
 
 			if (children) {

package/src/dto/labels/organize.test.ts

@@ -5,9 +5,9 @@ import type Label from '#cli/cs/labels/Label.js';
 describe('organize', () => {
 	it('organizes flat labels into hierarchy', () => {
 		const labels: Label[] = [
-			{ name: 'Parent', parent_uid: null, uid: 'parent' },
-			{ name: 'Child 1', parent_uid: 'parent', uid: 'child1' },
-			{ name: 'Child 2', parent_uid: 'parent', uid: 'child2' },
+			{ name: 'Parent', parent: [], uid: 'parent' },
+			{ name: 'Child 1', parent: ['parent'], uid: 'child1' },
+			{ name: 'Child 2', parent: ['parent'], uid: 'child2' },
 		];
 
 		const result = organize(labels);
@@ -26,10 +26,10 @@ describe('organize', () => {
 
 	it('organizes component label structure from screenshot', () => {
 		const labels: Label[] = [
-			{ name: 'Component', parent_uid: null, uid: 'component' },
-			{ name: 'Calculator', parent_uid: 'component', uid: 'calculator' },
-			{ name: 'Data', parent_uid: 'component', uid: 'data' },
-			{ name: 'Page', parent_uid: 'component', uid: 'page' },
+			{ name: 'Component', parent: [], uid: 'component' },
+			{ name: 'Calculator', parent: ['component'], uid: 'calculator' },
+			{ name: 'Data', parent: ['component'], uid: 'data' },
+			{ name: 'Page', parent: ['component'], uid: 'page' },
 		];
 
 		const result = organize(labels);
@@ -49,10 +49,10 @@ describe('organize', () => {
 
 	it('handles deeply nested labels', () => {
 		const labels: Label[] = [
-			{ name: 'Root', parent_uid: null, uid: 'root' },
-			{ name: 'Level 1', parent_uid: 'root', uid: 'level1' },
-			{ name: 'Level 2', parent_uid: 'level1', uid: 'level2' },
-			{ name: 'Level 3', parent_uid: 'level2', uid: 'level3' },
+			{ name: 'Root', parent: [], uid: 'root' },
+			{ name: 'Level 1', parent: ['root'], uid: 'level1' },
+			{ name: 'Level 2', parent: ['level1'], uid: 'level2' },
+			{ name: 'Level 3', parent: ['level2'], uid: 'level3' },
 		];
 
 		const result = organize(labels);
@@ -80,9 +80,9 @@ describe('organize', () => {
 
 	it('handles multiple top-level labels', () => {
 		const labels: Label[] = [
-			{ name: 'Label 1', parent_uid: null, uid: 'label1' },
-			{ name: 'Label 2', parent_uid: null, uid: 'label2' },
-			{ name: 'Child', parent_uid: 'label2', uid: 'child' },
+			{ name: 'Label 1', parent: [], uid: 'label1' },
+			{ name: 'Label 2', parent: [], uid: 'label2' },
+			{ name: 'Child', parent: ['label2'], uid: 'child' },
 		];
 
 		const result = organize(labels);
@@ -104,7 +104,7 @@ describe('organize', () => {
 
 	it('throws error for orphaned label', () => {
 		const labels: Label[] = [
-			{ name: 'Child', parent_uid: 'nonexistent', uid: 'child' },
+			{ name: 'Child', parent: ['nonexistent'], uid: 'child' },
 		];
 
 		expect(() => organize(labels)).toThrow(
@@ -114,10 +114,10 @@ describe('organize', () => {
 
 	it('preserves order of siblings', () => {
 		const labels: Label[] = [
-			{ name: 'Parent', parent_uid: null, uid: 'parent' },
-			{ name: 'Child 3', parent_uid: 'parent', uid: 'child3' },
-			{ name: 'Child 1', parent_uid: 'parent', uid: 'child1' },
-			{ name: 'Child 2', parent_uid: 'parent', uid: 'child2' },
+			{ name: 'Parent', parent: [], uid: 'parent' },
+			{ name: 'Child 3', parent: ['parent'], uid: 'child3' },
+			{ name: 'Child 1', parent: ['parent'], uid: 'child1' },
+			{ name: 'Child 2', parent: ['parent'], uid: 'child2' },
 		];
 
 		const result = organize(labels);

package/src/dto/labels/organize.ts

@@ -1,10 +1,10 @@
 import type Label from '#cli/cs/labels/Label.js';
 import type { LabelTreeNode } from './NormalizedLabels.js';
 
-// Labels have a tree structure defined by uid/parent_uid.
+// Labels have a tree structure defined by uid/parent array.
 //
-// The API returns a flat array that includes uid/parent_uid, but
-// leaves it up to the client to reconstruct the tree.
+// The API returns a flat array that includes uid/parent, where parent is an array
+// containing the parent UID (or empty array for top-level labels).
 //
 // We organize labels into a tree structure for serialization.
 //
@@ -17,8 +17,8 @@ export default function organize(
 	const topLevel: MutableNode[] = [];
 
 	for (const label of labels) {
-		const { parent_uid, ...labelWithoutParent } = label;
-		// Preserve all fields except parent_uid (which is represented by the tree structure)
+		const { parent, ...labelWithoutParent } = label;
+		// Preserve all fields except parent (which is represented by the tree structure)
 		byUid.set(label.uid, {
 			...labelWithoutParent,
 			name: label.name,
@@ -26,24 +26,25 @@ export default function organize(
 		});
 	}
 
-	for (const { uid, parent_uid } of labels) {
-		const label = byUid.get(uid);
-		if (!label) {
-			throw new Error(`Label ${uid} not found`);
+	for (const label of labels) {
+		const node = byUid.get(label.uid);
+		if (!node) {
+			throw new Error(`Label ${label.uid} not found`);
 		}
 
-		if (!parent_uid) {
-			topLevel.push(label);
+		const parentUid = label.parent.length > 0 ? label.parent[0] : null;
+		if (!parentUid) {
+			topLevel.push(node);
 			continue;
 		}
 
-		const parent = byUid.get(parent_uid);
+		const parent = byUid.get(parentUid);
 		if (!parent) {
-			const msg = `Orphaned label ${uid} with parent ${parent_uid}`;
+			const msg = `Orphaned label ${label.uid} with parent ${parentUid}`;
 			throw new Error(msg);
 		}
 
-		(parent.children ??= []).push(label);
+		(parent.children ??= []).push(node);
 	}
 
 	return topLevel;

package/src/schema/entries/toContentstack.ts

@@ -3,6 +3,7 @@ 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 { ensureLocaleExists } from '#cli/cs/locales/ensureLocaleExists.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';
@@ -45,7 +46,45 @@ export default async function toContentstack(
 		update,
 	});
 
-	for (const title of result.unmodified) {
+	// Process unmodified entries to ensure all locale versions are synced
+	await processUnmodifiedEntries(
+		result.unmodified,
+		ctx,
+		contentType,
+		csEntriesByTitle,
+		fsEntriesByTitle,
+		transformer,
+		filenamesByTitle,
+	);
+
+	return result;
+}
+
+function shouldSyncLocales(
+	fsLocaleVersions: Awaited<ReturnType<typeof loadFsLocaleVersions>>,
+	csLocaleSet: Set<string>,
+): boolean {
+	// Check if we have new locale versions that don't exist in Contentstack
+	const fsLocaleSet = new Set(
+		fsLocaleVersions.map((lv) => (lv.locale === 'default' ? null : lv.locale)),
+	);
+	return Array.from(fsLocaleSet).some(
+		(locale) => locale !== null && !csLocaleSet.has(locale),
+	);
+}
+
+async function processUnmodifiedEntries(
+	unmodified: Iterable<string>,
+	ctx: Ctx,
+	contentType: ContentType,
+	csEntriesByTitle: ReadonlyMap<string, Entry>,
+	fsEntriesByTitle: ReadonlyMap<string, Entry>,
+	transformer: BeaconReplacer,
+	filenamesByTitle: ReadonlyMap<Entry['uid'], string>,
+) {
+	const ui = getUi();
+
+	for (const title of unmodified) {
 		const cs = csEntriesByTitle.get(title);
 		const fs = fsEntriesByTitle.get(title);
 
@@ -60,11 +99,33 @@ export default async function toContentstack(
 			throw new Error(`No matching entry found for ${title}.`);
 		}
 
+		// Load all locale versions from filesystem
+		const fsLocaleVersions = await loadFsLocaleVersions(
+			fs,
+			contentType.uid,
+			filenamesByTitle,
+		);
+
+		const csLocaleSet = await getExistingLocales(ctx, contentType, cs.uid);
+
+		// Only push if there are new locale versions to sync
+		if (!shouldSyncLocales(fsLocaleVersions, csLocaleSet)) {
+			continue;
+		}
+
+		// Push all locale versions (including new locales like zh-cn)
+		await updateAllLocales(
+			ctx,
+			transformer,
+			contentType,
+			fsLocaleVersions,
+			cs.uid,
+			csLocaleSet,
+		);
+
 		const entry = { ...fs, uid: cs.uid };
 		ctx.references.recordEntryForReferences(contentType.uid, entry);
 	}
-
-	return result;
 }
 
 function buildUpdateFn(
@@ -141,6 +202,13 @@ async function updateAllLocales(
 	entryUid: string,
 	csLocaleSet: Set<string>,
 ) {
+	// Ensure all required locales exist in the target stack before pushing entries
+	const localeEnsurePromises = fsLocaleVersions
+		.filter((lv) => lv.locale !== 'default')
+		.map(async (lv) => ensureLocaleExists(ctx.cs.client, lv.locale));
+
+	await Promise.all(localeEnsurePromises);
+
 	// Import all locale versions in parallel for better performance
 	const importPromises = fsLocaleVersions.map(async (localeVersion) => {
 		const transformed = transformer.process(localeVersion.entry);
@@ -148,9 +216,10 @@ async function updateAllLocales(
 		// 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;
+
+		// Always use overwrite=true for locale-specific versions since the entry exists.
+		// For 'default' locale (single-locale backward compat), only overwrite if entry has locales.
+		const overwrite = locale ? true : csLocaleSet.size > 0;
 
 		return importEntry(
 			ctx.cs.client,

package/src/schema/entries/toFilesystem.ts

@@ -80,28 +80,24 @@ function createWriteFn(
 		}
 
 		// If only one locale, save without locale suffix for backward compatibility.
-		// When multiple locales exist prefer writing a single base file when an
-		// English locale is present (fixtures expect base filenames like
-		// `Autumn Feast and Social.yaml`). Only use locale suffix when no
-		// English locale is available.
-		const hasEnglish = locales.some((l) => /^en(?:[-_]|$)/iu.test(l.code));
-		const useLocaleSuffix = locales.length > 1 && !hasEnglish;
-
-		// Log locale details for debugging why specific locales (e.g. Chinese)
-		// may not be written to the filesystem.
-		// Debug logging removed to avoid unsafe-call lint errors.
+		// When multiple locales exist, write English as base file and other locales
+		// with locale suffixes (e.g., Entry.yaml for English, Entry.zh-chs.yaml for Chinese)
 
 		// Write all locale versions in parallel for better performance
-		const writePromises = locales.map(async (locale) =>
-			writeLocaleVersion(
+		const writePromises = locales.map(async (locale) => {
+			const isEnglish = /^en(?:[-_]|$)/iu.test(locale.code);
+			// Use locale suffix for non-English locales when multiple locales exist
+			const useLocaleSuffix = locales.length > 1 && !isEnglish;
+
+			return writeLocaleVersion(
 				ctx,
 				contentType,
 				entry,
 				locale.code,
 				getBasePath,
 				useLocaleSuffix,
-			),
-		);
+			);
+		});
 
 		await Promise.all(writePromises);
 	};
@@ -122,8 +118,27 @@ async function writeLocaleVersion(
 		localeCode,
 	);
 
+	// Skip writing this locale version if it's a fallback (locale doesn't match requested)
+	// This happens when Contentstack returns the default locale content because
+	// no localized version exists for the requested locale
+	if (
+		useLocaleSuffix &&
+		exported.locale &&
+		typeof exported.locale === 'string' &&
+		exported.locale !== localeCode
+	) {
+		// This is a fallback locale, skip writing it
+		return;
+	}
+
 	const { uid, ...transformed } = transformEntry(ctx, contentType, exported);
 
+	// Preserve the actual locale code from the source stack
+	// This ensures we maintain the exact language-region configuration
+	if ('locale' in transformed) {
+		transformed.locale = localeCode;
+	}
+
 	const basePath = getBasePath(entry);
 	const filePath = useLocaleSuffix
 		? basePath.replace(/\.yaml$/u, `.${localeCode}.yaml`)

package/src/schema/labels/lib/labelHelpers.ts

@@ -0,0 +1,36 @@
+import isRecord from '#cli/util/isRecord.js';
+
+export function canonicalize(value: unknown): unknown {
+	if (Array.isArray(value)) {
+		const result: unknown[] = [];
+		for (const item of value) {
+			result.push(canonicalize(item));
+		}
+		return result;
+	}
+	if (isRecord(value)) {
+		const obj: Record<string, unknown> = value;
+		const out: Record<string, unknown> = {};
+		const objKeys: string[] = Object.keys(obj);
+		objKeys.sort();
+		for (const key of objKeys) {
+			if (key === 'uid' || key === 'created_at' || key === 'updated_at')
+				continue;
+			// Normalize parent: skip if empty array
+			const val: unknown = obj[key];
+			if (key === 'parent' && Array.isArray(val) && val.length === 0) continue;
+			const canonicalizedVal: unknown = canonicalize(val);
+			out[key] = canonicalizedVal;
+		}
+		return out;
+	}
+	return value;
+}
+
+export function prepareLabel(
+	label: Record<string, unknown>,
+): Record<string, unknown> {
+	// Labels are sent to the API with all fields intact
+	// The API expects the parent field as an array
+	return label;
+}