@embeddables/cli 0.5.1 → 0.6.1

package/dist/compiler/index.js

@@ -6,6 +6,7 @@ import { CompileError } from './errors.js';
 import CSSJSON from 'cssjson';
 import { sanitizeFileName } from './reverse.js';
 import { generateRandomIdByType } from './helpers/duplicateIds.js';
+import { normalizeKeyIfStartsWithDigit, keyOrIdStartsWithDigit, } from './helpers/numericLeadingKeys.js';
 import { parse } from '@babel/parser';
 import traverseImport from '@babel/traverse';
 import * as generator from '@babel/generator';
@@ -103,16 +104,13 @@ export async function compileAllPages(opts) {
     if (files.length === 0) {
         throw new CompileError(`No pages found for glob: ${opts.pagesGlob}`);
     }
-    // First pass: collect all IDs from pages and detect duplicates
-    // Note: We check pages first, then global components are checked separately in loadGlobalComponents
+    // First pass: parse and collect lint issues (duplicate IDs, keys/IDs starting with a digit)
     const idOccurrences = new Map();
     const filePages = [];
-    // Parse all page files first to collect IDs
     for (const file of files) {
         const code = fs.readFileSync(file, 'utf8');
         const pageKey = derivePageKey(file, opts.pageKeyFrom);
         const page = parsePageFromFile({ code, filePath: file, pageKey });
-        // Collect component and button IDs with their locations
         for (let compIndex = 0; compIndex < page.components.length; compIndex++) {
             const component = page.components[compIndex];
             const compId = component.id;
@@ -126,7 +124,6 @@ export async function compileAllPages(opts) {
                 componentIndex: compIndex,
                 id: compId,
             });
-            // Collect button IDs from OptionSelector components
             if (component.type === 'OptionSelector' && Array.isArray(component.buttons)) {
                 for (let btnIndex = 0; btnIndex < component.buttons.length; btnIndex++) {
                     const button = component.buttons[btnIndex];
@@ -149,20 +146,16 @@ export async function compileAllPages(opts) {
         }
         filePages.push({ file, pageKey, page });
     }
-    // Detect duplicates and generate fixes
-    const idFixes = new Map(); // Maps "file:componentIndex" or "file:componentIndex:buttonIndex" -> newId
+    // Collect duplicate ID fixes (do not apply yet)
+    const idFixes = new Map();
     const allIds = new Set();
-    // Collect all existing IDs
     for (const occurrences of idOccurrences.values()) {
         for (const occ of occurrences) {
             allIds.add(occ.id);
         }
     }
-    // Find duplicates and generate unique replacements
     for (const [id, occurrences] of idOccurrences.entries()) {
         if (occurrences.length > 1) {
-            console.warn(`Found duplicate ID "${id}" used ${occurrences.length} times. Fixing...`);
-            // Keep first occurrence, fix the rest (type-based: plaintext_xxx, button_xxx, option_xxx)
             for (let i = 1; i < occurrences.length; i++) {
                 const occ = occurrences[i];
                 const fixKey = occ.buttonIndex !== undefined
@@ -172,65 +165,154 @@ export async function compileAllPages(opts) {
                 const newId = generateRandomIdByType(occ.componentType, isOptionButton, allIds, idFixes.values());
                 allIds.add(newId);
                 idFixes.set(fixKey, newId);
-                console.warn(`  → Fixing duplicate ID "${id}" to "${newId}" in ${occ.file} (component ${occ.componentIndex}${occ.buttonIndex !== undefined ? `, button ${occ.buttonIndex}` : ''})`);
             }
         }
     }
-    // Apply fixes to source files if any duplicates were found
-    if (idFixes.size > 0) {
-        // Fix page files
+    // Collect numeric-leading key/id fixes (component key, component id, button key, button id)
+    const numericLeadingFixes = [];
+    for (const { file, pageKey, page } of filePages) {
+        for (let compIndex = 0; compIndex < page.components.length; compIndex++) {
+            const comp = page.components[compIndex];
+            if (keyOrIdStartsWithDigit(comp.key)) {
+                const newKey = normalizeKeyIfStartsWithDigit(comp.key, pageKey);
+                if (newKey)
+                    numericLeadingFixes.push({
+                        file,
+                        componentIndex: compIndex,
+                        kind: 'componentKey',
+                        oldValue: comp.key,
+                        newValue: newKey,
+                    });
+            }
+            if (keyOrIdStartsWithDigit(comp.id)) {
+                const newId = normalizeKeyIfStartsWithDigit(comp.id, 'comp');
+                if (newId)
+                    numericLeadingFixes.push({
+                        file,
+                        componentIndex: compIndex,
+                        kind: 'componentId',
+                        oldValue: comp.id,
+                        newValue: newId,
+                    });
+            }
+            if (comp.type === 'OptionSelector' && Array.isArray(comp.buttons)) {
+                const prefix = comp.key ?? 'option';
+                for (let btnIndex = 0; btnIndex < comp.buttons.length; btnIndex++) {
+                    const btn = comp.buttons[btnIndex];
+                    if (btn && keyOrIdStartsWithDigit(btn.key)) {
+                        const newKey = normalizeKeyIfStartsWithDigit(btn.key, prefix);
+                        if (newKey)
+                            numericLeadingFixes.push({
+                                file,
+                                componentIndex: compIndex,
+                                buttonIndex: btnIndex,
+                                kind: 'buttonKey',
+                                oldValue: btn.key,
+                                newValue: newKey,
+                            });
+                    }
+                    if (btn && keyOrIdStartsWithDigit(btn.id)) {
+                        const safeKey = normalizeKeyIfStartsWithDigit(btn.key, prefix);
+                        const newId = btn.key != null && btn.id === `option_${btn.key}`
+                            ? safeKey != null
+                                ? `option_${safeKey}`
+                                : normalizeKeyIfStartsWithDigit(btn.id, 'option')
+                            : normalizeKeyIfStartsWithDigit(btn.id, 'option');
+                        if (newId)
+                            numericLeadingFixes.push({
+                                file,
+                                componentIndex: compIndex,
+                                buttonIndex: btnIndex,
+                                kind: 'buttonId',
+                                oldValue: btn.id,
+                                newValue: newId,
+                            });
+                    }
+                }
+            }
+        }
+    }
+    const totalLintIssues = idFixes.size + numericLeadingFixes.length;
+    let shouldApplyFixes = false;
+    if (totalLintIssues > 0) {
+        // Report all issues
+        if (idFixes.size > 0) {
+            console.warn(`Found ${idFixes.size} duplicate ID(s). Keys and IDs must be unique across the embeddable.`);
+            for (const [fixKey, newId] of idFixes) {
+                const parts = fixKey.split(':');
+                const file = parts[0];
+                const compIdx = parts[1];
+                const btnIdx = parts[2];
+                const loc = btnIdx !== undefined ? `component ${compIdx}, button ${btnIdx}` : `component ${compIdx}`;
+                console.warn(`  → ${file}: ${loc} → "${newId}"`);
+            }
+        }
+        if (numericLeadingFixes.length > 0) {
+            console.warn(`Found ${numericLeadingFixes.length} key(s)/ID(s) that start with a number. Use a prefix (e.g. range_1_to_2_weeks).`);
+            for (const f of numericLeadingFixes) {
+                const loc = f.buttonIndex !== undefined
+                    ? `component ${f.componentIndex}, button ${f.buttonIndex} (${f.kind})`
+                    : `component ${f.componentIndex} (${f.kind})`;
+                console.warn(`  → ${f.file}: "${f.oldValue}" → "${f.newValue}" (${loc})`);
+            }
+        }
+        if (opts.fixLint === true) {
+            shouldApplyFixes = true;
+        }
+        else if (opts.fixLint === 'prompt') {
+            const { default: prompts } = await import('prompts');
+            const res = await prompts({
+                type: 'confirm',
+                name: 'apply',
+                message: `Apply ${totalLintIssues} fix(es) to source files?`,
+                initial: true,
+            });
+            shouldApplyFixes = res.apply === true;
+        }
+        if (!shouldApplyFixes) {
+            throw new CompileError(`Build failed: ${totalLintIssues} lint issue(s) (duplicate IDs and/or keys/IDs starting with a number). Run with --fix or answer 'y' when prompted to fix.`, { file: files[0] });
+        }
+        // Apply fixes
         for (const { file } of filePages) {
-            const fixesForFile = Array.from(idFixes.entries()).filter(([key]) => key.startsWith(file + ':'));
-            if (fixesForFile.length > 0) {
-                const code = fs.readFileSync(file, 'utf8');
-                const updatedCode = fixIdsInSourceFile(code, file, fixesForFile);
-                fs.writeFileSync(file, updatedCode, 'utf8');
-                console.log(`  ✓ Updated ${file} with fixed IDs`);
+            const idFixesForFile = Array.from(idFixes.entries()).filter(([key]) => key.startsWith(file + ':'));
+            const numericForFile = numericLeadingFixes.filter((f) => f.file === file);
+            if (idFixesForFile.length > 0 || numericForFile.length > 0) {
+                let code = fs.readFileSync(file, 'utf8');
+                if (idFixesForFile.length > 0) {
+                    code = fixIdsInSourceFile(code, file, idFixesForFile);
+                }
+                if (numericForFile.length > 0) {
+                    code = fixNumericLeadingInSourceFile(code, file, numericForFile);
+                }
+                fs.writeFileSync(file, code, 'utf8');
+                console.log(`  ✓ Updated ${file}`);
             }
         }
+        // Re-parse after fixes
+        filePages.length = 0;
+        for (const file of files) {
+            const code = fs.readFileSync(file, 'utf8');
+            const pageKey = derivePageKey(file, opts.pageKeyFrom);
+            const page = parsePageFromFile({ code, filePath: file, pageKey });
+            filePages.push({ file, pageKey, page });
+        }
     }
-    // Second pass: re-parse all files (now with fixed IDs) and compile
-    // If no duplicates were found, reuse the already-parsed pages
     const pages = [];
     const seenIds = new Map();
-    // Map of pageKey -> PageJson for applying metadata later
     const pageMap = new Map();
-    if (idFixes.size > 0) {
-        // Re-parse files if we fixed any duplicates
-        for (const { file, pageKey } of filePages) {
-            const code = fs.readFileSync(file, 'utf8');
-            const page = parsePageFromFile({ code, filePath: file, pageKey });
-            // Global ID uniqueness: components + option ids
-            for (const c of page.components) {
-                checkUniqueId(seenIds, c.id, { file, pageKey });
-                if (c.type === 'OptionSelector' && Array.isArray(c.buttons)) {
-                    for (const b of c.buttons) {
-                        if (b?.id)
-                            checkUniqueId(seenIds, b.id, { file, pageKey });
-                    }
-                }
-            }
-            pages.push(page);
-            pageMap.set(pageKey, page);
-        }
-    }
-    else {
-        // No duplicates found, reuse already-parsed pages
-        for (const filePage of filePages) {
-            const { page, pageKey, file } = filePage;
-            // Global ID uniqueness: components + option ids
-            for (const c of page.components) {
-                checkUniqueId(seenIds, c.id, { file, pageKey });
-                if (c.type === 'OptionSelector' && Array.isArray(c.buttons)) {
-                    for (const b of c.buttons) {
-                        if (b?.id)
-                            checkUniqueId(seenIds, b.id, { file, pageKey });
-                    }
+    for (const filePage of filePages) {
+        const { page, pageKey, file } = filePage;
+        for (const c of page.components) {
+            checkUniqueId(seenIds, c.id, { file, pageKey });
+            if (c.type === 'OptionSelector' && Array.isArray(c.buttons)) {
+                for (const b of c.buttons) {
+                    if (b?.id)
+                        checkUniqueId(seenIds, b.id, { file, pageKey });
                 }
             }
-            pages.push(page);
-            pageMap.set(pageKey, page);
         }
+        pages.push(page);
+        pageMap.set(pageKey, page);
     }
     // Read config.json if it exists
     let config = null;
@@ -333,6 +415,10 @@ export async function compileAllPages(opts) {
                 // Skip _version - this is CLI metadata (tracked version number), not part of the embeddable
                 continue;
             }
+            else if (key === '_branch_id' || key === '_branch_name') {
+                // Skip _branch_id / _branch_name - CLI metadata (current branch), not part of the embeddable
+                continue;
+            }
             else if (key === 'computedFields') {
                 // Replace computedFields with loaded computedFields (which include code)
                 if (computedFields.length > 0) {
@@ -555,6 +641,172 @@ function fixIdsInSourceFile(code, filePath, fixes) {
     const result = generate(ast, {}, code);
     return result.code;
 }
+function fixNumericLeadingInSourceFile(code, filePath, fixes) {
+    let ast;
+    try {
+        ast = parse(code, {
+            sourceType: 'module',
+            plugins: ['typescript', 'jsx'],
+            sourceFilename: filePath,
+        });
+    }
+    catch (error) {
+        throw new CompileError(`Failed to parse file for key/id fixing: ${error.message}`, {
+            file: filePath,
+        });
+    }
+    const componentKeyMap = new Map();
+    const componentIdMap = new Map();
+    const buttonKeyMap = new Map();
+    const buttonIdMap = new Map();
+    for (const f of fixes) {
+        if (f.buttonIndex !== undefined) {
+            const k = `${f.componentIndex}:${f.buttonIndex}`;
+            if (f.kind === 'buttonKey')
+                buttonKeyMap.set(k, f.newValue);
+            else if (f.kind === 'buttonId')
+                buttonIdMap.set(k, f.newValue);
+        }
+        else {
+            if (f.kind === 'componentKey')
+                componentKeyMap.set(f.componentIndex, f.newValue);
+            else if (f.kind === 'componentId')
+                componentIdMap.set(f.componentIndex, f.newValue);
+        }
+    }
+    // Map from buttons variable name (e.g. "genderButtons") -> OptionSelector key (e.g. "gender") for fixing const arrays
+    const buttonsConstNameToPrefix = new Map();
+    // Collect (start, end, newText) replacements so we can patch the source without reformatting (preserves line breaks, etc.)
+    const replacements = [];
+    const pushReplacement = (node, newValue) => {
+        if (node.start == null || node.end == null)
+            return;
+        replacements.push({ start: node.start, end: node.end, newText: JSON.stringify(newValue) });
+    };
+    let componentIndex = -1;
+    traverse(ast, {
+        JSXElement(path) {
+            const opening = path.node.openingElement;
+            const tagName = opening.name.type === 'JSXIdentifier' ? opening.name.name : null;
+            if (!tagName || !ALLOWED_PRIMITIVES.has(tagName))
+                return;
+            const hasIdAttr = opening.attributes.some((a) => a.type === 'JSXAttribute' && a.name.type === 'JSXIdentifier' && a.name.name === 'id');
+            const hasKeyAttr = opening.attributes.some((a) => a.type === 'JSXAttribute' && a.name.type === 'JSXIdentifier' && a.name.name === 'key');
+            if (hasIdAttr || hasKeyAttr) {
+                componentIndex++;
+            }
+            const recordAttrReplacement = (name, newValue) => {
+                for (const attr of opening.attributes) {
+                    if (attr.type === 'JSXAttribute' &&
+                        attr.name.type === 'JSXIdentifier' &&
+                        attr.name.name === name) {
+                        const valueNode = attr.value?.type === 'JSXExpressionContainer'
+                            ? attr.value.expression
+                            : attr.value;
+                        if (valueNode?.type === 'StringLiteral') {
+                            pushReplacement(valueNode, newValue);
+                        }
+                        break;
+                    }
+                }
+            };
+            if (componentKeyMap.has(componentIndex)) {
+                recordAttrReplacement('key', componentKeyMap.get(componentIndex));
+            }
+            if (componentIdMap.has(componentIndex)) {
+                recordAttrReplacement('id', componentIdMap.get(componentIndex));
+            }
+            if (tagName === 'OptionSelector') {
+                let componentKey;
+                for (const attr of opening.attributes) {
+                    if (attr.type === 'JSXAttribute' &&
+                        attr.name.type === 'JSXIdentifier' &&
+                        attr.name.name === 'key' &&
+                        attr.value?.type === 'StringLiteral') {
+                        componentKey = attr.value.value;
+                        break;
+                    }
+                }
+                const prefix = componentKey ?? 'option';
+                for (const attr of opening.attributes) {
+                    if (attr.type === 'JSXAttribute' &&
+                        attr.name.type === 'JSXIdentifier' &&
+                        attr.name.name === 'buttons' &&
+                        attr.value?.type === 'JSXExpressionContainer') {
+                        const expr = attr.value.expression;
+                        if (expr.type === 'ArrayExpression') {
+                            let buttonIndex = 0;
+                            for (const element of expr.elements) {
+                                if (element && element.type === 'ObjectExpression') {
+                                    const key = `${componentIndex}:${buttonIndex}`;
+                                    for (const prop of element.properties) {
+                                        if (prop.type === 'ObjectProperty' && prop.key.type === 'Identifier') {
+                                            if (prop.key.name === 'key' && buttonKeyMap.has(key)) {
+                                                pushReplacement(prop.value, buttonKeyMap.get(key));
+                                            }
+                                            else if (prop.key.name === 'id' && buttonIdMap.has(key)) {
+                                                pushReplacement(prop.value, buttonIdMap.get(key));
+                                            }
+                                        }
+                                    }
+                                }
+                                buttonIndex++;
+                            }
+                        }
+                        else if (expr.type === 'Identifier') {
+                            if (!buttonsConstNameToPrefix.has(expr.name)) {
+                                buttonsConstNameToPrefix.set(expr.name, prefix);
+                            }
+                        }
+                        break;
+                    }
+                }
+            }
+        },
+    });
+    // Fix button key/id in const arrays (e.g. const genderButtons = [{ id: "1_...", key: "..." }])
+    traverse(ast, {
+        VariableDeclarator(path) {
+            const id = path.node.id;
+            const init = path.node.init;
+            if (id.type !== 'Identifier' || init?.type !== 'ArrayExpression')
+                return;
+            const constName = id.name;
+            const prefix = buttonsConstNameToPrefix.get(constName) ?? 'option';
+            for (const element of init.elements) {
+                if (!element || element.type !== 'ObjectExpression')
+                    continue;
+                for (const prop of element.properties) {
+                    if (prop.type !== 'ObjectProperty' || prop.key.type !== 'Identifier')
+                        continue;
+                    if (prop.key.name !== 'key' && prop.key.name !== 'id')
+                        continue;
+                    const val = prop.value;
+                    let current = null;
+                    if (val.type === 'StringLiteral') {
+                        current = val.value;
+                    }
+                    else if (val.type === 'TemplateLiteral' && val.quasis.length === 1 && !val.quasis[0].value.raw.includes('$')) {
+                        current = val.quasis[0].value.raw;
+                    }
+                    if (current === null || !keyOrIdStartsWithDigit(current))
+                        continue;
+                    const newValue = normalizeKeyIfStartsWithDigit(current, prefix);
+                    if (newValue === null)
+                        continue;
+                    pushReplacement(val, newValue);
+                }
+            }
+        },
+    });
+    // Apply replacements from end to start so indices stay valid; preserves all other formatting
+    replacements.sort((a, b) => b.start - a.start);
+    let result = code;
+    for (const { start, end, newText } of replacements) {
+        result = result.slice(0, start) + newText + result.slice(end);
+    }
+    return result;
+}
 function checkUniqueId(seen, id, loc) {
     const prev = seen.get(id);
     if (prev) {

package/dist/compiler/reverse.d.ts

@@ -9,6 +9,11 @@ export declare function reverseCompile(embeddable: {
     [key: string]: any;
 }, embeddableId: string, opts?: {
     fix?: boolean;
+    pullMetadata?: {
+        version?: number;
+        branchId?: string;
+        branchName?: string;
+    };
 }): Promise<void>;
 /**
  * Sanitizes a string to be safe for use as a filename.

package/dist/compiler/reverse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reverse.d.ts","sourceRoot":"","sources":["../../src/compiler/reverse.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,YAAY,CAAA;AAihBzD,wBAAsB,cAAc,CAClC,UAAU,EAAE;IACV,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,cAAc,CAAC,EAAE,GAAG,EAAE,CAAA;IACtB,WAAW,CAAC,EAAE,GAAG,EAAE,CAAA;IACnB,UAAU,CAAC,EAAE,GAAG,EAAE,CAAA;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB,EACD,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,iBAmDzB;AA2yCD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKpD"}
+{"version":3,"file":"reverse.d.ts","sourceRoot":"","sources":["../../src/compiler/reverse.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,QAAQ,EAAiB,MAAM,YAAY,CAAA;AAqlBzD,wBAAsB,cAAc,CAClC,UAAU,EAAE;IACV,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,QAAQ,EAAE,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IAC5B,cAAc,CAAC,EAAE,GAAG,EAAE,CAAA;IACtB,WAAW,CAAC,EAAE,GAAG,EAAE,CAAA;IACnB,UAAU,CAAC,EAAE,GAAG,EAAE,CAAA;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CACnB,EACD,YAAY,EAAE,MAAM,EACpB,IAAI,CAAC,EAAE;IACL,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,YAAY,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5E,iBAmFF;AA+0CD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAKpD"}

package/dist/compiler/reverse.js

@@ -284,6 +284,7 @@ function validateComponentProps(component, validProps) {
         'tags',
         'type',
         'parent_id',
+        'parent_key',
         'buttons',
         ...IGNORED_COMPONENT_PROPERTIES,
     ]);
@@ -424,6 +425,61 @@ function checkAndFixDuplicateIds(pages, fix) {
     }
     return idMapping;
 }
+/**
+ * Fixes deprecated parent_key: resolves to parent_id using first component with matching key,
+ * removes parent_key, and removes components that still have no parent_id after resolution.
+ * Only runs when fix is enabled.
+ */
+function fixParentKeyDeprecation(components, fix) {
+    if (!fix || components.length === 0)
+        return;
+    // Build key -> id map (first occurrence wins, exclude ignored types)
+    const keyToId = new Map();
+    for (const comp of components) {
+        if (comp.key &&
+            comp.id &&
+            !keyToId.has(comp.key) &&
+            comp.type &&
+            !IGNORED_COMPONENT_TYPES.has(comp.type)) {
+            keyToId.set(comp.key, comp.id);
+        }
+    }
+    // Resolve parent_key -> parent_id, remove parent_key, track components to remove
+    const toRemove = new Map(); // id -> parent_key for warning
+    for (const comp of components) {
+        const parentKey = comp.parent_key;
+        if (!parentKey)
+            continue;
+        if (!comp.parent_id) {
+            const resolvedId = keyToId.get(parentKey);
+            if (resolvedId) {
+                comp.parent_id = resolvedId;
+                console.warn(`Fixed parent_key on component (id: ${comp.id}, key: ${comp.key}) – resolved parent_key "${parentKey}" to parent_id.`);
+            }
+            else {
+                toRemove.set(comp.id, parentKey);
+            }
+        }
+        else {
+            console.warn(`Fixed parent_key on component (id: ${comp.id}, key: ${comp.key}) – removed deprecated parent_key (already has parent_id).`);
+        }
+        delete comp.parent_key;
+    }
+    // Remove components that couldn't resolve parent
+    if (toRemove.size > 0) {
+        let i = 0;
+        while (i < components.length) {
+            const comp = components[i];
+            if (toRemove.has(comp.id)) {
+                console.warn(`Removed component (id: ${comp.id}, key: ${comp.key}) – parent_key "${toRemove.get(comp.id)}" not found, no parent_id.`);
+                components.splice(i, 1);
+            }
+            else {
+                i++;
+            }
+        }
+    }
+}
 /**
  * Applies the ID mapping to all pages, updating component IDs and button IDs.
  * The mapping uses occurrence keys (pageKey:componentIndex or pageKey:componentIndex:buttonIndex).
@@ -461,14 +517,43 @@ function applyIdMapping(pages, idMapping) {
         }
     }
 }
+function hasDeprecatedParentKey(components) {
+    return components.some((comp) => comp.parent_key != null);
+}
 export async function reverseCompile(embeddable, embeddableId, opts) {
     const fix = opts?.fix ?? false;
+    const pullMetadata = opts?.pullMetadata;
+    // When fix is disabled, throw on deprecated parent_key so user gets interactive retry prompt
+    if (!fix) {
+        for (const page of embeddable.pages) {
+            if (hasDeprecatedParentKey(page.components)) {
+                const count = page.components.filter((c) => c.parent_key != null).length;
+                throw new Error(`Found deprecated parent_key on ${count} component(s) in page "${page.key}". Run with --fix to resolve.`);
+            }
+        }
+        if (embeddable.components && Array.isArray(embeddable.components)) {
+            if (hasDeprecatedParentKey(embeddable.components)) {
+                const count = embeddable.components.filter((c) => c.parent_key != null).length;
+                throw new Error(`Found deprecated parent_key on ${count} global component(s). Run with --fix to resolve.`);
+            }
+        }
+    }
     // Check for duplicate IDs across all pages and create a mapping
     const idMapping = checkAndFixDuplicateIds(embeddable.pages, fix);
     // Apply ID mapping to all pages
     if (idMapping.size > 0) {
         applyIdMapping(embeddable.pages, idMapping);
     }
+    // Fix deprecated parent_key (resolve to parent_id, remove parent_key, drop orphans).
+    // Must run before extractGlobalComponents so resolved parent_id avoids "must have _location since it has no parent_id" errors.
+    if (fix) {
+        for (const page of embeddable.pages) {
+            fixParentKeyDeprecation(page.components, fix);
+        }
+        if (embeddable.components && Array.isArray(embeddable.components)) {
+            fixParentKeyDeprecation(embeddable.components, fix);
+        }
+    }
     // Generate TSX pages
     for (const page of embeddable.pages) {
         await generatePageFile(page, embeddableId, fix);
@@ -478,7 +563,7 @@ export async function reverseCompile(embeddable, embeddableId, opts) {
         await generateStylesFile(embeddable.styles, embeddableId);
     }
     // Generate config.json
-    await generateConfigFile(embeddable, embeddableId);
+    await generateConfigFile(embeddable, embeddableId, pullMetadata);
     // Extract computedFields to JS files
     if (embeddable.computedFields && embeddable.computedFields.length > 0) {
         await extractComputedFields(embeddable.computedFields, embeddableId);
@@ -758,6 +843,7 @@ function generateJSX(node, indent = 4, pageKey, componentId, nameMap) {
         'tags',
         'type',
         'parent_id',
+        'parent_key',
         'buttons',
         '_location',
         ...IGNORED_COMPONENT_PROPERTIES,
@@ -1347,9 +1433,27 @@ function escapeStringForJS(str) {
  * This file controls page ordering and stores embeddable-level metadata.
  * Preserves the order of top-level properties from embeddable.json.
  */
-async function generateConfigFile(embeddable, embeddableId) {
+async function generateConfigFile(embeddable, embeddableId, pullMetadata) {
     try {
         const configPath = path.join('embeddables', embeddableId, 'config.json');
+        // CLI-only fields: from pull (when branching/saving) or from existing config file.
+        let preservedVersion;
+        let preservedBranchId;
+        let preservedBranchName;
+        if (fs.existsSync(configPath)) {
+            try {
+                const existing = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+                if (typeof existing._version === 'number')
+                    preservedVersion = existing._version;
+                if (typeof existing._branch_id === 'string' && existing._branch_id)
+                    preservedBranchId = existing._branch_id;
+                if (typeof existing._branch_name === 'string' && existing._branch_name)
+                    preservedBranchName = existing._branch_name;
+            }
+            catch {
+                /* ignore */
+            }
+        }
         // Preserve the order of top-level properties from embeddable
         const embeddableKeys = Object.keys(embeddable);
         // Extract page metadata and order (excluding components which are in TSX files)
@@ -1432,6 +1536,29 @@ async function generateConfigFile(embeddable, embeddableId) {
         if (!config.id) {
             config.id = embeddableId;
         }
+        // Restore CLI-only fields: prefer pullMetadata (passed by pull/branch) so branch is never lost.
+        const versionToWrite = pullMetadata?.version ?? preservedVersion;
+        if (versionToWrite !== undefined)
+            config._version = versionToWrite;
+        if (pullMetadata !== undefined) {
+            if (pullMetadata.branchId !== undefined) {
+                config._branch_id = pullMetadata.branchId;
+                if (pullMetadata.branchName !== undefined)
+                    config._branch_name = pullMetadata.branchName;
+                else
+                    delete config._branch_name;
+            }
+            else {
+                delete config._branch_id;
+                delete config._branch_name;
+            }
+        }
+        else {
+            if (preservedBranchId !== undefined)
+                config._branch_id = preservedBranchId;
+            if (preservedBranchName !== undefined)
+                config._branch_name = preservedBranchName;
+        }
         fs.mkdirSync(path.dirname(configPath), { recursive: true });
         fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
         console.log(`${pc.gray(`Generated ${configPath}`)}`);

package/dist/types-builder.d.ts

@@ -551,7 +551,7 @@ export interface OptionSelectorButton {
 }
 type OptionSelectorButtonTriggerEvent = 'no-action' | 'next-page' | 'open-url';
 export interface ProgressBar extends Base {
-    progress_type?: 'circle' | 'simple' | 'custom';
+    progress_type: 'circle' | 'simple' | 'custom';
     allow_nav?: boolean;
     fill_connectors?: boolean;
     node_icon?: string;