@embeddables/cli 0.5.1 → 0.6.1

package/.prompts/embeddables-cli.md

@@ -77,7 +77,7 @@ All component types are derived from `src/types-builder.ts`. The relevant typing
 **Key Base Properties** (all components have these):
 
 - `id: string` - Unique identifier - this must be unique across the entire Embeddable JSON. Always snake_case.
-- `key: string` - Unique identifier, used in React as key prop - unique in general but duplicate keys can be used in certain cases (e.g. two `email` fields, each hidden by conditions). Always snake_case.
+- `key: string` - Unique identifier, used in React as key prop - unique in general but duplicate keys can be used in certain cases (e.g. two `email` fields, each hidden by conditions). Always snake_case. **Keys must not start with a digit** (invalid in JS/JSON). When deriving a key from text that would start with a number (e.g. "1 to 2 weeks" → "1_to_2_weeks"), use a semantic prefix instead: e.g. `range_1_to_2_weeks`, `option_1_to_2_weeks`, or the component key like `delivery_time_1_to_2_weeks`.
 - `type: ComponentType` - Component type
 - `tags?: string[]` - Used for CSS styling
 - `parent_id?: string` - For nested components
@@ -98,7 +98,7 @@ All component types are derived from `src/types-builder.ts`. The relevant typing
   - `outputs_onchange`
   - etc.
 - `OptionSelector`
-  - `buttons`
+  - `buttons` - each button has a `key` (and optional `text`, `description`, etc.). **Button keys must not start with a digit.** If the option label would slug to a key starting with a number (e.g. "1 to 2 weeks" → "1_to_2_weeks"), use a prefix such as the component key (e.g. `delivery_range_1_to_2_weeks`) or a short semantic prefix (e.g. `range_1_to_2_weeks`, `option_1_to_2_weeks`).
   - `multiple` - whether to allow multi-select
   - `dropdown`
   - `checkbox` - whether to add a (square/round) visual checkbox in each button (the checkbox will be added for you, no need to add it manually)

package/dist/cli.js

@@ -30,9 +30,10 @@ 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('--fix', 'Apply lint fixes (duplicate IDs, keys/IDs starting with a number)')
     .option('--pageKeyFrom <mode>', 'filename|export', 'filename')
     .action(async (opts) => {
     await runBuild(opts);
@@ -42,6 +43,7 @@ program
     .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('--fix', 'Apply lint fixes (duplicate IDs, keys/IDs starting with a number)')
     .option('-L, --local', 'Use local engine (http://localhost:8787)')
     .option('-e, --engine <url>', 'Engine origin', 'https://engine.embeddables.com')
     .option('--port <n>', 'Dev proxy port', '3000')

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,7 +1,8 @@
 export declare function runBuild(opts: {
-    id: string;
+    id?: string;
     pages?: string;
     out?: string;
+    fix?: boolean;
     pageKeyFrom: 'filename' | 'export';
 }): Promise<void>;
 //# sourceMappingURL=build.d.ts.map

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,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,WAAW,EAAE,UAAU,GAAG,QAAQ,CAAA;CACnC,iBA6BA"}

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');
@@ -13,6 +23,7 @@ export async function runBuild(opts) {
             pageKeyFrom: opts.pageKeyFrom,
             stylesDir,
             embeddableId,
+            fixLint: opts.fix ? true : 'prompt',
         });
     }
     catch (e) {

package/dist/commands/dev.d.ts

@@ -2,6 +2,7 @@ export declare function runDev(opts: {
     id?: string;
     pages?: string;
     out?: string;
+    fix?: boolean;
     local?: boolean;
     engine: string;
     port: string;

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

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAmHA,wBAAsB,MAAM,CAAC,IAAI,EAAE;IACjC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,UAAU,GAAG,QAAQ,CAAA;CACnC,iBA4GA"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/commands/dev.ts"],"names":[],"mappings":"AAmHA,wBAAsB,MAAM,CAAC,IAAI,EAAE;IACjC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,UAAU,GAAG,QAAQ,CAAA;CACnC,iBA+GA"}

package/dist/commands/dev.js

@@ -108,6 +108,7 @@ export async function runDev(opts) {
     const globalComponentsGlob = `embeddables/${embeddableId}/global-components/**/*.location.tsx`;
     const computedFieldsGlob = `embeddables/${embeddableId}/computed-fields/**/*.js`;
     const actionsGlob = `embeddables/${embeddableId}/actions/**/*.js`;
+    const fixLint = opts.fix ? true : 'prompt';
     // Initial build
     try {
         await compileAllPages({
@@ -117,6 +118,7 @@ export async function runDev(opts) {
             stylesDir,
             embeddableId,
             configPath,
+            fixLint,
         });
     }
     catch (e) {
@@ -158,6 +160,7 @@ export async function runDev(opts) {
                 stylesDir,
                 embeddableId,
                 configPath,
+                fixLint,
             });
             proxy.broadcastReload();
         }

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/helpers/numericLeadingKeys.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Keys and IDs must not start with a digit (invalid in JS/JSON).
+ * This helper produces a safe key by prefixing when needed.
+ */
+/** Returns a key safe for use (prefix applied if key starts with a digit). */
+export declare function normalizeKeyIfStartsWithDigit(key: string | null, prefix: string): string | null;
+export declare function keyOrIdStartsWithDigit(value: string | null | undefined): boolean;
+//# sourceMappingURL=numericLeadingKeys.d.ts.map

package/dist/compiler/helpers/numericLeadingKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numericLeadingKeys.d.ts","sourceRoot":"","sources":["../../../src/compiler/helpers/numericLeadingKeys.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8EAA8E;AAC9E,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI/F;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAIhF"}

package/dist/compiler/helpers/numericLeadingKeys.js

@@ -0,0 +1,17 @@
+/**
+ * Keys and IDs must not start with a digit (invalid in JS/JSON).
+ * This helper produces a safe key by prefixing when needed.
+ */
+/** Returns a key safe for use (prefix applied if key starts with a digit). */
+export function normalizeKeyIfStartsWithDigit(key, prefix) {
+    if (key === null || typeof key !== 'string' || key === '')
+        return key;
+    if (!/^\d/.test(key))
+        return key;
+    return `${prefix}_${key}`;
+}
+export function keyOrIdStartsWithDigit(value) {
+    if (value === null || value === undefined || typeof value !== 'string' || value === '')
+        return false;
+    return /^\d/.test(value);
+}

package/dist/compiler/index.d.ts

@@ -12,5 +12,7 @@ export declare function compileAllPages(opts: {
     stylesDir?: string;
     embeddableId?: string;
     configPath?: string;
+    /** When true, apply lint fixes (duplicate IDs, keys/IDs starting with a digit). When 'prompt', ask user to fix. */
+    fixLint?: true | 'prompt';
 }): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

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":"AAmDA;;;;;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;IACnB,mHAAmH;IACnH,OAAO,CAAC,EAAE,IAAI,GAAG,QAAQ,CAAA;CAC1B,iBA4cA"}