@embeddables/cli 0.5.1 → 0.6.0

package/dist/cli.js

@@ -30,7 +30,7 @@ program
 });
 program
     .command('build')
-    .requiredOption('-i, --id <id>', 'Embeddable ID')
+    .option('-i, --id <id>', 'Embeddable ID (will prompt if not provided)')
     .option('-p, --pages <glob>', 'Pages glob')
     .option('-o, --out <path>', 'Output json path')
     .option('--pageKeyFrom <mode>', 'filename|export', 'filename')

package/dist/commands/branch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"branch.d.ts","sourceRoot":"","sources":["../../src/commands/branch.ts"],"names":[],"mappings":"AAKA,wBAAsB,SAAS,CAAC,IAAI,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,iBAgDpD"}
+{"version":3,"file":"branch.d.ts","sourceRoot":"","sources":["../../src/commands/branch.ts"],"names":[],"mappings":"AAKA,wBAAsB,SAAS,CAAC,IAAI,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,iBAoDpD"}

package/dist/commands/branch.js

@@ -41,6 +41,10 @@ export async function runBranch(opts) {
     else {
         console.log(pc.cyan(`Switching to branch: ${selectedBranch.name}...`));
         console.log('');
-        await runPull({ id: embeddableId, branch: selectedBranch.id });
+        await runPull({
+            id: embeddableId,
+            branch: selectedBranch.id,
+            branchName: selectedBranch.name,
+        });
     }
 }

package/dist/commands/build.d.ts

@@ -1,5 +1,5 @@
 export declare function runBuild(opts: {
-    id: string;
+    id?: string;
     pages?: string;
     out?: string;
     pageKeyFrom: 'filename' | 'export';

package/dist/commands/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAIA,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,UAAU,GAAG,QAAQ,CAAA;CACnC,iBAmBA"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/commands/build.ts"],"names":[],"mappings":"AAKA,wBAAsB,QAAQ,CAAC,IAAI,EAAE;IACnC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,UAAU,GAAG,QAAQ,CAAA;CACnC,iBA4BA"}

package/dist/commands/build.js

@@ -1,8 +1,18 @@
 import path from 'node:path';
 import { compileAllPages } from '../compiler/index.js';
 import { formatError } from '../compiler/errors.js';
+import { promptForLocalEmbeddable } from '../prompts/index.js';
 export async function runBuild(opts) {
-    const embeddableId = opts.id;
+    let embeddableId = opts.id;
+    if (!embeddableId) {
+        const selected = await promptForLocalEmbeddable({
+            message: 'Select an embeddable to build:',
+        });
+        if (!selected) {
+            process.exit(1);
+        }
+        embeddableId = selected;
+    }
     const pagesGlob = opts.pages || `embeddables/${embeddableId}/pages/**/*.page.tsx`;
     const outPath = opts.out || path.join('embeddables', embeddableId, '.generated', 'embeddable.json');
     const stylesDir = path.join('embeddables', embeddableId, 'styles');

package/dist/commands/pull.d.ts

@@ -1,7 +1,9 @@
-export declare function runPull(opts: {
+export type RunPullOptions = {
     id?: string;
     out?: string;
     branch?: string;
+    branchName?: string;
     fix?: boolean;
-}): Promise<void>;
+};
+export declare function runPull(opts: RunPullOptions): Promise<void>;
 //# sourceMappingURL=pull.d.ts.map

package/dist/commands/pull.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../src/commands/pull.ts"],"names":[],"mappings":"AAUA,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,iBAwNhG"}
+{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../../src/commands/pull.ts"],"names":[],"mappings":"AAyEA,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,GAAG,CAAC,EAAE,OAAO,CAAA;CACd,CAAA;AAED,wBAAsB,OAAO,CAAC,IAAI,EAAE,cAAc,iBAkPjD"}

package/dist/commands/pull.js

@@ -6,6 +6,69 @@ import { reverseCompile } from '../compiler/reverse.js';
 import { getAccessToken, isLoggedIn } from '../auth/index.js';
 import { getProjectId, writeProjectConfig } from '../config/index.js';
 import { promptForProject, promptForEmbeddable, fetchEmbeddableMetadata } from '../prompts/index.js';
+/** Slug for branch name/id for use in filenames (e.g. "my branch" -> "my_branch"). */
+function slugForBranch(nameOrId) {
+    return String(nameOrId).replace(/[^a-zA-Z0-9_.-]/g, '_').replace(/_+/g, '_') || 'main';
+}
+/** Versioned embeddable filename: embeddable-{branchSlug}@{version}.json */
+function getVersionedBasename(version, branchSlug) {
+    const v = typeof version === 'number' ? version : String(version);
+    return `embeddable-${branchSlug}@${v}.json`;
+}
+/** Read current _branch_id and _branch_name from config (set when on a branch via `embeddables branch`). */
+function getCurrentBranchFromConfig(embeddableId) {
+    const configPath = path.join('embeddables', embeddableId, 'config.json');
+    if (!fs.existsSync(configPath))
+        return null;
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const branchId = config._branch_id;
+        if (typeof branchId !== 'string' || !branchId)
+            return null;
+        const branchName = config._branch_name;
+        return { branchId, branchName: typeof branchName === 'string' ? branchName : undefined };
+    }
+    catch {
+        return null;
+    }
+}
+/** Write _version, _branch_id, _branch_name to config.json. Called early and in finally so it always runs. */
+function writePullMetadataToConfig(embeddableId, version, branch, branchName) {
+    const configPath = path.join('embeddables', embeddableId, 'config.json');
+    let config = {};
+    try {
+        if (fs.existsSync(configPath)) {
+            try {
+                const content = fs.readFileSync(configPath, 'utf8');
+                config = JSON.parse(content);
+            }
+            catch {
+                /* use empty config */
+            }
+        }
+        if (version != null) {
+            const n = typeof version === 'number' ? version : parseInt(String(version), 10);
+            if (!isNaN(n))
+                config._version = n;
+        }
+        if (branch) {
+            config._branch_id = branch;
+            if (branchName)
+                config._branch_name = branchName;
+            else
+                delete config._branch_name;
+        }
+        else {
+            delete config._branch_id;
+            delete config._branch_name;
+        }
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    }
+    catch (err) {
+        console.warn(pc.yellow(`Could not write config.json: ${err instanceof Error ? err.message : err}`));
+    }
+}
 export async function runPull(opts) {
     let embeddableId = opts.id;
     // If no ID provided, try to get it interactively
@@ -34,7 +97,7 @@ export async function runPull(opts) {
                 project_id: projectId,
                 project_name: selectedProject.title || undefined,
             });
-            console.log(pc.green(`✓ Saved project to embeddables.json`));
+            console.log(pc.green(`✓ Wrote project config to embeddables.json`));
             console.log('');
         }
         console.log(pc.cyan('Fetching embeddables from project...'));
@@ -47,12 +110,23 @@ export async function runPull(opts) {
         embeddableId = selected;
         console.log('');
     }
+    // Stay on current branch when no --branch: use config's _branch_id if set
+    const currentFromConfig = opts.branch == null ? getCurrentBranchFromConfig(embeddableId) : null;
+    const effectiveBranch = opts.branch ?? currentFromConfig?.branchId;
+    const effectiveBranchName = opts.branchName ?? currentFromConfig?.branchName;
     let url = `https://engine.embeddables.com/${embeddableId}?version=latest`;
-    if (opts.branch) {
-        url += `&embeddable_branch=${opts.branch}`;
+    if (effectiveBranch) {
+        url += `&embeddable_branch=${effectiveBranch}`;
     }
     const outPath = opts.out || path.join('embeddables', embeddableId, '.generated', 'embeddable.json');
+    const branchLabel = effectiveBranch
+        ? effectiveBranchName
+            ? `${effectiveBranchName} (${effectiveBranch})`
+            : effectiveBranch
+        : 'main';
+    console.log(pc.cyan(`Pulling branch: ${pc.bold(branchLabel)}`));
     console.log(`Fetching embeddable from ${url}...`);
+    let pullVersion;
     try {
         // Add authentication header if available
         const accessToken = getAccessToken();
@@ -75,24 +149,28 @@ export async function runPull(opts) {
         fs.mkdirSync(path.dirname(outPath), { recursive: true });
         const flowJson = JSON.stringify(flow, null, 2);
         fs.writeFileSync(outPath, flowJson, 'utf8');
-        console.log(pc.cyan(`✓ Saved embeddable JSON to ${outPath}`));
-        // Also save version-specific file (e.g. embeddable-v135.json) when version is present in response
-        const version = data.version ?? data.embeddable_version ?? flow.version;
+        console.log(pc.cyan(`✓ Wrote embeddable JSON to ${outPath}`));
+        // Also save version-specific file (e.g. embeddable-main@135.json or embeddable-my_branch@135.json)
+        pullVersion =
+            data.version ?? data.embeddable_version ?? flow.version;
+        const version = pullVersion;
+        const branchSlug = slugForBranch(effectiveBranchName ?? effectiveBranch ?? 'main');
         if (version != null) {
             const versionStr = typeof version === 'string' ? version : String(version);
-            const versionLabel = versionStr.startsWith('v') ? versionStr : `v${versionStr}`;
-            const versionedBasename = `embeddable-${versionLabel}.json`;
+            const versionedBasename = getVersionedBasename(versionStr, branchSlug);
             const versionedPath = path.join(path.dirname(outPath), versionedBasename);
             fs.writeFileSync(versionedPath, flowJson, 'utf8');
-            console.log(pc.cyan(`✓ Saved embeddable JSON to ${versionedPath}`));
+            console.log(pc.cyan(`✓ Wrote versioned embeddable JSON to ${versionedPath}`));
         }
+        // Persist _version and _branch_id in config.json immediately so they survive reverseCompile
+        writePullMetadataToConfig(embeddableId, version, effectiveBranch, effectiveBranchName);
         // Fetch and save flow metadata from DB (title, archived, created_at)
         const metadata = await fetchEmbeddableMetadata(embeddableId);
         if (metadata) {
             const metadataPath = path.join('embeddables', embeddableId, 'metadata.json');
             fs.mkdirSync(path.dirname(metadataPath), { recursive: true });
             fs.writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + '\n', 'utf8');
-            console.log(pc.cyan(`✓ Saved flow metadata to ${metadataPath}`));
+            console.log(pc.cyan(`✓ Wrote flow metadata to ${metadataPath}`));
         }
         // Clear existing pages, styles, computed-fields, actions, and global-components before generating new ones
         const pagesDir = path.join('embeddables', embeddableId, 'pages');
@@ -137,9 +215,16 @@ export async function runPull(opts) {
             }
             console.log(`${pc.gray(`Cleared ${existingGlobalComponents.length} existing global component(s)`)}`);
         }
-        // Run reverse compiler
+        // Run reverse compiler (pass pullMetadata so config.json gets _version and _branch_id even on fix retry)
+        const versionNum = version != null && !isNaN(Number(version)) ? Number(version) : undefined;
+        const pullMetadata = {
+            version: versionNum,
+            branchId: effectiveBranch,
+            branchName: effectiveBranchName,
+        };
+        let usedFix = opts.fix;
         try {
-            await reverseCompile(flow, embeddableId, { fix: opts.fix });
+            await reverseCompile(flow, embeddableId, { fix: opts.fix, pullMetadata });
         }
         catch (compileError) {
             // If fix mode wasn't already enabled, offer to retry with fix mode
@@ -159,10 +244,11 @@ export async function runPull(opts) {
                     },
                 });
                 if (response.fix) {
+                    usedFix = true;
                     console.log('');
                     console.log(pc.cyan('Retrying with auto-fix enabled...'));
                     console.log('');
-                    await reverseCompile(flow, embeddableId, { fix: true });
+                    await reverseCompile(flow, embeddableId, { fix: true, pullMetadata });
                 }
                 else {
                     process.exit(1);
@@ -172,22 +258,17 @@ export async function runPull(opts) {
                 throw compileError;
             }
         }
-        // Store version number in config.json so save knows the base version
-        if (version != null) {
-            const versionNumber = typeof version === 'number' ? version : parseInt(String(version), 10);
-            if (!isNaN(versionNumber)) {
-                const configPath = path.join('embeddables', embeddableId, 'config.json');
-                if (fs.existsSync(configPath)) {
-                    try {
-                        const configContent = fs.readFileSync(configPath, 'utf8');
-                        const config = JSON.parse(configContent);
-                        config._version = versionNumber;
-                        fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
-                    }
-                    catch {
-                        // Ignore errors updating config.json - versioned files are a fallback
-                    }
-                }
+        // Persist mutated flow when fixes were applied (e.g. parent_key -> parent_id)
+        if (usedFix) {
+            const flowJson = JSON.stringify(flow, null, 2);
+            fs.writeFileSync(outPath, flowJson, 'utf8');
+            console.log(pc.cyan(`✓ Wrote embeddable JSON to ${outPath} (with fixes applied)`));
+            if (version != null) {
+                const versionStr = typeof version === 'string' ? version : String(version);
+                const versionedBasename = getVersionedBasename(versionStr, branchSlug);
+                const versionedPath = path.join(path.dirname(outPath), versionedBasename);
+                fs.writeFileSync(versionedPath, flowJson, 'utf8');
+                console.log(pc.cyan(`✓ Wrote versioned embeddable JSON to ${versionedPath} (with fixes applied)`));
             }
         }
     }
@@ -195,4 +276,10 @@ export async function runPull(opts) {
         console.error('Error pulling embeddable:', error);
         process.exit(1);
     }
+    finally {
+        // Always persist _version and _branch_id once we've fetched (so config is correct even if reverseCompile failed or was retried with fix)
+        if (embeddableId != null && pullVersion !== undefined) {
+            writePullMetadataToConfig(embeddableId, pullVersion, effectiveBranch, effectiveBranchName);
+        }
+    }
 }

package/dist/commands/save.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/commands/save.ts"],"names":[],"mappings":"AAoJA,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,iBAoBA"}
+{"version":3,"file":"save.d.ts","sourceRoot":"","sources":["../../src/commands/save.ts"],"names":[],"mappings":"AA+OA,wBAAsB,OAAO,CAAC,IAAI,EAAE;IAClC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,iBAoBA"}

package/dist/commands/save.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import pc from 'picocolors';
 import prompts from 'prompts';
-import { getAccessToken, isLoggedIn } from '../auth/index.js';
+import { getAccessToken, getAuthenticatedSupabaseClient, isLoggedIn } from '../auth/index.js';
 import { getProjectId, writeProjectConfig } from '../config/index.js';
 import { compileAllPages } from '../compiler/index.js';
 import { formatError } from '../compiler/errors.js';
@@ -69,6 +69,45 @@ function getVersionFromConfig(embeddableId) {
     }
     return null;
 }
+/**
+ * Read `_branch_id` from config.json for the given embeddable (set when on a branch via `embeddables branch`).
+ */
+function getBranchFromConfig(embeddableId) {
+    const configPath = path.join('embeddables', embeddableId, 'config.json');
+    if (!fs.existsSync(configPath)) {
+        return null;
+    }
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (typeof config._branch_id === 'string' && config._branch_id) {
+            return config._branch_id;
+        }
+    }
+    catch {
+        // Ignore parse errors
+    }
+    return null;
+}
+/** Slug for branch name/id for versioned filenames (e.g. "my branch" -> "my_branch"). */
+function slugForBranch(nameOrId) {
+    return String(nameOrId).replace(/[^a-zA-Z0-9_.-]/g, '_').replace(/_+/g, '_') || 'main';
+}
+/** Get branch slug from config (_branch_name preferred, else _branch_id, else main). */
+function getBranchSlugFromConfig(embeddableId) {
+    const configPath = path.join('embeddables', embeddableId, 'config.json');
+    if (!fs.existsSync(configPath))
+        return 'main';
+    try {
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        const name = config._branch_name ?? config._branch_id;
+        if (typeof name === 'string' && name)
+            return slugForBranch(name);
+    }
+    catch {
+        /* ignore */
+    }
+    return 'main';
+}
 /**
  * Update `_version` in config.json for the given embeddable.
  */
@@ -87,7 +126,7 @@ function setVersionInConfig(embeddableId, version) {
     }
 }
 /**
- * Scan the .generated/ directory for versioned files (embeddable-v*.json)
+ * Scan the .generated/ directory for versioned files (embeddable-v*.json or embeddable-*@*.json)
  * and return the highest version number found.
  */
 function getLatestVersionFromFiles(generatedDir) {
@@ -95,10 +134,11 @@ function getLatestVersionFromFiles(generatedDir) {
         return null;
     }
     const files = fs.readdirSync(generatedDir);
-    const versionPattern = /^embeddable-v(\d+)\.json$/;
+    const legacyPattern = /^embeddable-v(\d+)\.json$/;
+    const branchPattern = /^embeddable-[^@]+@(\d+)\.json$/;
     let maxVersion = null;
     for (const file of files) {
-        const match = file.match(versionPattern);
+        const match = file.match(legacyPattern) ?? file.match(branchPattern);
         if (match) {
             const version = parseInt(match[1], 10);
             if (maxVersion === null || version > maxVersion) {
@@ -108,6 +148,41 @@ function getLatestVersionFromFiles(generatedDir) {
     }
     return maxVersion;
 }
+/**
+ * Fetch active drafts from other users on the same version (status=DRAFT, not saved/discarded).
+ * Used to warn before saving that others may have unsaved edits.
+ */
+async function fetchOtherUsersDrafts(supabase, flowId, versionNumber, branchId, currentUserId) {
+    try {
+        let query = supabase
+            .from('flow_versions')
+            .select('id, author_id, author_name')
+            .eq('flow_id', flowId)
+            .eq('status', 'DRAFT')
+            .eq('version_number', versionNumber)
+            .not('draft_saved', 'is', true)
+            .not('draft_discarded', 'is', true)
+            .neq('author_id', currentUserId);
+        if (branchId === null) {
+            query = query.is('branch_id', null);
+        }
+        else {
+            query = query.eq('branch_id', branchId);
+        }
+        const { data, error } = await query;
+        if (error) {
+            return [];
+        }
+        return (data || []).map((row) => ({
+            id: row.id,
+            author_id: row.author_id,
+            author_name: row.author_name ?? null,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
 export async function runSave(opts) {
     try {
         await runSaveInner(opts);
@@ -158,6 +233,8 @@ async function runSaveInner(opts) {
         embeddableId = selected;
         console.log('');
     }
+    // Resolve branch: explicit -b flag wins, otherwise use current branch from config (set by `embeddables branch`)
+    const effectiveBranch = opts.branch ?? getBranchFromConfig(embeddableId) ?? undefined;
     // 4. Get project ID (from config or interactive prompt)
     let projectId = getProjectId();
     if (!projectId) {
@@ -242,6 +319,39 @@ async function runSaveInner(opts) {
         }
         fromVersionNumber = detectedVersion;
     }
+    // 7b. Check for other users' drafts on this version; warn and optionally abort
+    const supabase = await getAuthenticatedSupabaseClient();
+    if (supabase) {
+        const { data: { user }, } = await supabase.auth.getUser();
+        const currentUserId = user?.id;
+        if (currentUserId) {
+            const branchIdForDrafts = effectiveBranch ?? null;
+            const otherDrafts = await fetchOtherUsersDrafts(supabase, embeddableId, fromVersionNumber, branchIdForDrafts, currentUserId);
+            if (otherDrafts.length > 0) {
+                const names = otherDrafts
+                    .map((d) => d.author_name?.trim() || d.author_id || 'Someone')
+                    .filter((n, i, a) => a.indexOf(n) === i);
+                const namesText = names.length === 1 ? names[0] : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+                console.log('');
+                console.warn(pc.yellow(`⚠ ${namesText} ${names.length === 1 ? 'has' : 'have'} unsaved edits on version ${fromVersionNumber}. Saving may cause conflicts.`));
+                const { proceed } = await prompts({
+                    type: 'confirm',
+                    name: 'proceed',
+                    message: 'Save anyway?',
+                    initial: false,
+                }, {
+                    onCancel: () => {
+                        process.exit(1);
+                    },
+                });
+                if (!proceed) {
+                    console.log(pc.gray('Save cancelled.'));
+                    process.exit(0);
+                }
+                console.log('');
+            }
+        }
+    }
     // 8. POST to save-version API
     console.log(pc.cyan(`Saving embeddable (based on v${fromVersionNumber})...`));
     const body = {
@@ -253,8 +363,8 @@ async function runSaveInner(opts) {
     if (opts.label) {
         body.label = opts.label;
     }
-    if (opts.branch) {
-        body.branchId = opts.branch;
+    if (effectiveBranch) {
+        body.branchId = effectiveBranch;
     }
     const url = `${WEB_APP_BASE_URL}/api/embeddables/save-version`;
     const headers = {
@@ -340,7 +450,8 @@ async function runSaveInner(opts) {
         const { newVersionNumber } = forceResult.data;
         console.log(pc.green(`✓ Saved as version ${newVersionNumber}`));
         setVersionInConfig(embeddableId, newVersionNumber);
-        const versionedPath = path.join(generatedDir, `embeddable-v${newVersionNumber}.json`);
+        const branchSlug = getBranchSlugFromConfig(embeddableId);
+        const versionedPath = path.join(generatedDir, `embeddable-${branchSlug}@${newVersionNumber}.json`);
         fs.mkdirSync(generatedDir, { recursive: true });
         fs.writeFileSync(versionedPath, jsonContent, 'utf8');
         console.log(pc.cyan(`✓ Saved version file to ${versionedPath}`));
@@ -358,8 +469,9 @@ async function runSaveInner(opts) {
     console.log(pc.green(`✓ Saved as version ${newVersionNumber}`));
     // Update _version in config.json so future saves know the base version
     setVersionInConfig(embeddableId, newVersionNumber);
-    // Also save the versioned file to .generated/ as a snapshot
-    const versionedPath = path.join(generatedDir, `embeddable-v${newVersionNumber}.json`);
+    // Also save the versioned file to .generated/ as a snapshot (embeddable-{branch}@{version}.json)
+    const branchSlug = getBranchSlugFromConfig(embeddableId);
+    const versionedPath = path.join(generatedDir, `embeddable-${branchSlug}@${newVersionNumber}.json`);
     fs.mkdirSync(generatedDir, { recursive: true });
     fs.writeFileSync(versionedPath, jsonContent, 'utf8');
     console.log(pc.cyan(`✓ Saved version file to ${versionedPath}`));

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compiler/index.ts"],"names":[],"mappings":"AA+CA;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CA2DlF;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,UAAU,GAAG,QAAQ,CAAA;IAClC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,iBAiXA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compiler/index.ts"],"names":[],"mappings":"AA+CA;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,OAAO,CA2DlF;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,UAAU,GAAG,QAAQ,CAAA;IAClC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,iBAoXA"}

package/dist/compiler/index.js

@@ -333,6 +333,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) {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@embeddables/cli",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "bin": {
     "embeddables": "./bin/embeddables.mjs"