@payloadcms/figma 0.0.1-alpha.52 → 0.0.1-alpha.54

package/dist/cli.js

@@ -9,8 +9,8 @@ import { initCommand } from './commands/init.js';
 import { listTokensCommand } from './commands/list-tokens.js';
 import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
+import { upgradeCommand } from './commands/upgrade.js';
 import { setInfraEnvironment } from './constants.js';
-import { handleUpgrade } from './utils/handle-upgrade.js';
 import { helpMessage } from './utils/messages.js';
 /**
  * Entrypoint for bin/cli.js
@@ -31,6 +31,7 @@ class Main {
         this.args = arg({
             '--all': Boolean,
             '--debug': Boolean,
+            '--dry-run': Boolean,
             '--env': String,
             '--force': Boolean,
             '--help': Boolean,
@@ -86,15 +87,6 @@ class Main {
                 helpMessage();
                 process.exit(0);
             }
-            // Check for upgrade migrations
-            try {
-                const upgradeChanges = await handleUpgrade(process.cwd());
-                if (upgradeChanges.length > 0) {
-                    p.log.info(`Migrated project: ${upgradeChanges.join(', ')}`);
-                }
-            } catch  {
-            // Never block CLI execution due to upgrade check
-            }
             // Debug command outputs plain text for copy-paste — skip styled intro
             if (subcommand === 'debug') {
                 await debugCommand();
@@ -147,6 +139,11 @@ class Main {
                         debug: this.args['--debug']
                     });
                     break;
+                case 'upgrade':
+                    await upgradeCommand({
+                        isDryRun: this.args['--dry-run']
+                    });
+                    break;
                 default:
                     p.log.error(pc.red(`Unknown command: ${subcommand}`));
                     p.note('Use --help to see available commands', 'Tip');

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,5 @@
+export type UpgradeCommandOptions = {
+    isDryRun?: boolean;
+};
+export declare function upgradeCommand(options?: UpgradeCommandOptions): Promise<void>;
+//# sourceMappingURL=upgrade.d.ts.map

package/dist/commands/upgrade.js

@@ -0,0 +1,331 @@
+import * as p from '@clack/prompts';
+import fs from 'fs/promises';
+import path from 'path';
+import pc from 'picocolors';
+import { Project } from 'ts-morph';
+import { fileURLToPath } from 'url';
+import { getBootstrapInfo, getCmsResourceId } from '../api/control-plane.js';
+import { getValidAccessToken } from '../auth/oauth-flow.js';
+import { getTokenStore } from '../auth/token-store.js';
+import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
+import { addOrUpdateEnvVar, getEnvVar, removeEnvVar } from '../utils/env-management.js';
+import { formatFile } from '../utils/formatter.js';
+import { getPackageManager } from '../utils/package-manager.js';
+import { removeFigmaContentSystemId } from '../utils/payload-config-ast.js';
+import { findPayloadConfig } from '../utils/payload-config-finder.js';
+import { checkPackageInstalled, installPackage } from '../utils/payload-package-check.js';
+import { getOwnVersion } from '../utils/version-check.js';
+export async function upgradeCommand(options = {}) {
+    const cwd = process.cwd();
+    const { isDryRun = false } = options;
+    const changes = [];
+    const warnings = [];
+    const spinner = p.spinner();
+    spinner.start('Checking for needed migrations...');
+    spinner.stop('Checking for needed migrations...');
+    await migrateEnvRename({
+        changes,
+        cwd,
+        isDryRun
+    });
+    await migrateProjectId({
+        changes,
+        cwd,
+        isDryRun,
+        warnings
+    });
+    await ensureBootstrapCached({
+        changes,
+        cwd,
+        isDryRun
+    });
+    await migrateRemoveDeprecatedEnvVars({
+        changes,
+        cwd,
+        isDryRun,
+        warnings
+    });
+    await migrateConfigAst({
+        changes,
+        cwd,
+        isDryRun
+    });
+    await migratePackageVersion({
+        changes,
+        cwd,
+        isDryRun
+    });
+    for (const warning of warnings){
+        p.log.warning(warning);
+    }
+    if (changes.length === 0) {
+        p.log.success('Everything is up to date.');
+        return;
+    }
+    if (isDryRun) {
+        p.log.info(`Dry run: ${changes.length} change(s) detected.`);
+    } else {
+        p.log.success(`${changes.length} change(s) applied.`);
+    }
+}
+const DEPRECATED_ENV_VARS = [
+    'FIGMA_CONTENT_API_CONTENT_SYSTEM_ID',
+    'FIGMA_TENANT_ID',
+    'FIGMA_OAUTH_CLIENT_ID',
+    'FIGMA_OAUTH_CLIENT_SECRET'
+];
+async function migrateEnvRename({ changes, cwd, isDryRun }) {
+    try {
+        const oldValue = await getEnvVar(cwd, 'FIGMA_ENV');
+        if (oldValue === null) {
+            return;
+        }
+        if (isDryRun) {
+            p.log.message(`${pc.dim('○')} Would rename FIGMA_ENV → FIGMA_INFRA_ENV`);
+            changes.push('Rename FIGMA_ENV → FIGMA_INFRA_ENV');
+            return;
+        }
+        await addOrUpdateEnvVar(cwd, 'FIGMA_INFRA_ENV', oldValue);
+        await removeEnvVar(cwd, 'FIGMA_ENV');
+        p.log.message(`${pc.green('●')} Env: Renamed FIGMA_ENV → FIGMA_INFRA_ENV`);
+        changes.push('Renamed FIGMA_ENV → FIGMA_INFRA_ENV');
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Env rename migration failed: ${msg}`);
+    }
+}
+async function migrateProjectId({ changes, cwd, isDryRun, warnings = [] }) {
+    try {
+        const existingProjectId = await getEnvVar(cwd, 'FIGMA_PROJECT_ID');
+        if (existingProjectId) {
+            return;
+        }
+        const oldContentSystemId = await getEnvVar(cwd, 'FIGMA_CONTENT_API_CONTENT_SYSTEM_ID');
+        if (!oldContentSystemId) {
+            return;
+        }
+        if (isDryRun) {
+            p.log.message(`${pc.dim('○')} Would resolve FIGMA_PROJECT_ID from content system ID`);
+            changes.push('Resolve FIGMA_PROJECT_ID from content system ID');
+            return;
+        }
+        const store = getTokenStore();
+        const accessToken = await getValidAccessToken(store);
+        if (!accessToken) {
+            warnings.push('Not authenticated — could not resolve FIGMA_PROJECT_ID. Run `npx @payloadcms/figma login` first.');
+            return;
+        }
+        const cmsResourceId = await getCmsResourceId(accessToken, oldContentSystemId);
+        await addOrUpdateEnvVar(cwd, 'FIGMA_PROJECT_ID', cmsResourceId);
+        // Resolve actual environment name from bootstrap API
+        try {
+            const bootstrapInfo = await getBootstrapInfo(accessToken, cmsResourceId);
+            cacheAllEnvironments(store, cmsResourceId, bootstrapInfo);
+            const envName = bootstrapInfo.environments[0]?.name ?? 'production';
+            await addOrUpdateEnvVar(cwd, 'FIGMA_ENVIRONMENT_NAME', envName);
+        } catch  {
+            await addOrUpdateEnvVar(cwd, 'FIGMA_ENVIRONMENT_NAME', 'production');
+        }
+        p.log.message(`${pc.green('●')} Env: Resolved FIGMA_PROJECT_ID from content system ID`);
+        changes.push('Resolved FIGMA_PROJECT_ID from content system ID');
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Project ID migration failed: ${msg}`);
+    }
+}
+async function ensureBootstrapCached(params) {
+    try {
+        const projectId = await getEnvVar(params.cwd, 'FIGMA_PROJECT_ID');
+        if (!projectId) {
+            return;
+        }
+        const environmentName = await getEnvVar(params.cwd, 'FIGMA_ENVIRONMENT_NAME') ?? 'production';
+        const store = getTokenStore();
+        if (store.getBootstrapData(projectId, environmentName)) {
+            return;
+        }
+        const accessToken = await getValidAccessToken(store);
+        if (!accessToken) {
+            return;
+        }
+        const bootstrapInfo = await getBootstrapInfo(accessToken, projectId);
+        cacheAllEnvironments(store, projectId, bootstrapInfo);
+        // Fix FIGMA_ENVIRONMENT_NAME if it doesn't match any actual environment
+        const envNames = bootstrapInfo.environments.map((e)=>e.name);
+        if (!envNames.includes(environmentName) && envNames.length > 0) {
+            const correctName = envNames[0];
+            if (params.isDryRun) {
+                p.log.message(`${pc.dim('○')} Would fix FIGMA_ENVIRONMENT_NAME: ${environmentName} → ${correctName}`);
+                params.changes.push(`Fix FIGMA_ENVIRONMENT_NAME`);
+                return;
+            }
+            await addOrUpdateEnvVar(params.cwd, 'FIGMA_ENVIRONMENT_NAME', correctName);
+            p.log.message(`${pc.green('●')} Env: Fixed FIGMA_ENVIRONMENT_NAME: ${environmentName} → ${correctName}`);
+            params.changes.push(`Fixed FIGMA_ENVIRONMENT_NAME: ${environmentName} → ${correctName}`);
+        }
+    } catch  {
+    // Best-effort — runtime will retry if needed
+    }
+}
+async function migrateRemoveDeprecatedEnvVars({ changes, cwd, isDryRun, warnings = [] }) {
+    try {
+        const presentVars = [];
+        for (const key of DEPRECATED_ENV_VARS){
+            const value = await getEnvVar(cwd, key);
+            if (value !== null) {
+                presentVars.push(key);
+            }
+        }
+        if (presentVars.length === 0) {
+            return;
+        }
+        // Only remove when bootstrap data is available (proves the project is set up correctly)
+        const projectId = await getEnvVar(cwd, 'FIGMA_PROJECT_ID');
+        if (!projectId) {
+            warnings.push('Cannot remove deprecated env vars without FIGMA_PROJECT_ID. Run upgrade again after project ID migration.');
+            return;
+        }
+        const environmentName = await getEnvVar(cwd, 'FIGMA_ENVIRONMENT_NAME') ?? 'production';
+        const store = getTokenStore();
+        const bootstrapData = store.getBootstrapData(projectId, environmentName);
+        if (!bootstrapData) {
+            // Try fetching from API
+            const accessToken = await getValidAccessToken(store);
+            if (accessToken) {
+                try {
+                    const bootstrapInfo = await getBootstrapInfo(accessToken, projectId);
+                    cacheAllEnvironments(store, projectId, bootstrapInfo);
+                } catch  {
+                    warnings.push('Could not verify bootstrap data — keeping deprecated env vars. Run `npx @payloadcms/figma init` to complete migration.');
+                    return;
+                }
+            } else {
+                warnings.push('Not authenticated — keeping deprecated env vars. Run `npx @payloadcms/figma login` first.');
+                return;
+            }
+        }
+        if (isDryRun) {
+            p.log.message(`${pc.dim('○')} Would remove deprecated env vars: ${presentVars.join(', ')}`);
+            changes.push(`Remove deprecated env vars: ${presentVars.join(', ')}`);
+            return;
+        }
+        const removed = [];
+        for (const key of presentVars){
+            await removeEnvVar(cwd, key);
+            removed.push(key);
+        }
+        p.log.message(`${pc.green('●')} Env: Removed deprecated env vars: ${removed.join(', ')}`);
+        changes.push(`Removed deprecated env vars: ${removed.join(', ')}`);
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Deprecated env var removal failed: ${msg}`);
+    }
+}
+async function migrateConfigAst({ changes, cwd, isDryRun }) {
+    try {
+        const configPath = await findPayloadConfig(cwd);
+        if (!configPath) {
+            return;
+        }
+        const project = new Project({
+            skipAddingFilesFromTsConfig: true
+        });
+        const sourceFile = project.addSourceFileAtPath(configPath);
+        const wouldRemove = removeFigmaContentSystemId(sourceFile);
+        if (!wouldRemove) {
+            return;
+        }
+        if (isDryRun) {
+            p.log.message(`${pc.dim('○')} Would remove contentSystemId from payload.config.ts`);
+            changes.push('Remove contentSystemId from payload.config.ts');
+            return;
+        }
+        // Re-parse fresh since the detection already mutated the AST
+        const freshProject = new Project({
+            skipAddingFilesFromTsConfig: true
+        });
+        const freshSourceFile = freshProject.addSourceFileAtPath(configPath);
+        removeFigmaContentSystemId(freshSourceFile);
+        await freshSourceFile.save();
+        try {
+            const packageManager = await getPackageManager(cwd);
+            await formatFile(configPath, packageManager);
+        } catch  {
+        // Formatting is best-effort
+        }
+        p.log.message(`${pc.green('●')} Config: Removed contentSystemId from payload.config.ts`);
+        changes.push('Removed contentSystemId from payload.config.ts');
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Config AST migration failed: ${msg}`);
+    }
+}
+async function migratePackageVersion({ changes, cwd, isDryRun }) {
+    try {
+        const isInstalled = await checkPackageInstalled(cwd, '@payloadcms/figma');
+        if (!isInstalled) {
+            return;
+        }
+        const cliDir = path.dirname(fileURLToPath(import.meta.url));
+        const isFromRegistry = cliDir.includes('node_modules') || cliDir.includes('.npm');
+        if (isFromRegistry) {
+            await migrateRegistryPackageVersion({
+                changes,
+                cliDir,
+                cwd,
+                isDryRun
+            });
+        } else {
+            await migrateLocalPackageVersion({
+                changes,
+                cliDir,
+                cwd,
+                isDryRun
+            });
+        }
+    } catch (error) {
+        const msg = error instanceof Error ? error.message : 'Unknown error';
+        p.log.warning(`Package version sync failed: ${msg}`);
+    }
+}
+async function migrateRegistryPackageVersion({ changes, cliDir: _cliDir, cwd, isDryRun }) {
+    const cliVersion = await getOwnVersion();
+    const pkgJsonPath = path.join(cwd, 'package.json');
+    const pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf-8'));
+    const installedVersion = pkgJson.dependencies?.['@payloadcms/figma']?.replace(/^[\^~>=<]+/, '');
+    if (!installedVersion || installedVersion === cliVersion) {
+        return;
+    }
+    if (isDryRun) {
+        p.log.message(`${pc.dim('○')} Would update @payloadcms/figma ${installedVersion} → ${cliVersion}`);
+        changes.push(`Update @payloadcms/figma ${installedVersion} → ${cliVersion}`);
+        return;
+    }
+    const packageManager = await getPackageManager(cwd);
+    await installPackage(cwd, '@payloadcms/figma', packageManager, cliVersion);
+    p.log.message(`${pc.green('●')} Package: Updated @payloadcms/figma ${installedVersion} → ${cliVersion}`);
+    changes.push(`Updated @payloadcms/figma ${installedVersion} → ${cliVersion}`);
+}
+async function migrateLocalPackageVersion({ changes, cliDir, cwd, isDryRun }) {
+    if (isDryRun) {
+        p.log.message(`${pc.dim('○')} Would install @payloadcms/figma from local build`);
+        changes.push('Install @payloadcms/figma from local build');
+        return;
+    }
+    // Dynamic import — findPackageRoot and packLocalPackage will be exported in a later task
+    const { findPackageRoot, packLocalPackage } = await import('../utils/handle-upgrade.js');
+    const pkgDir = await findPackageRoot(cliDir);
+    if (!pkgDir) {
+        return;
+    }
+    const packageManager = await getPackageManager(cwd);
+    const tgzPath = packLocalPackage(pkgDir);
+    const destTgz = path.join(cwd, path.basename(tgzPath));
+    await fs.rename(tgzPath, destTgz);
+    await installPackage(cwd, destTgz, packageManager);
+    await fs.unlink(destTgz).catch(()=>{});
+    p.log.message(`${pc.green('●')} Package: Installed @payloadcms/figma from local build`);
+    changes.push('Installed @payloadcms/figma from local build');
+}
+
+//# sourceMappingURL=upgrade.js.map

package/dist/constants.js

@@ -47,8 +47,8 @@ export function getInfraEnvironment() {
     if (process.env.FIGMA_INFRA_ENV?.toLowerCase() === 'staging') {
         return 'staging';
     }
-    // Fall back to .env file in cwd
-    const envFileValue = getEnvVarSync(process.cwd(), 'FIGMA_INFRA_ENV');
+    // Fall back to .env file in cwd (check both new and old env var names)
+    const envFileValue = getEnvVarSync(process.cwd(), 'FIGMA_INFRA_ENV') ?? getEnvVarSync(process.cwd(), 'FIGMA_ENV');
     if (envFileValue) {
         const env = envFileValue.toLowerCase();
         if (env === 'staging') {

package/dist/db-content-api/generated/content-api-types.d.ts

@@ -1494,6 +1494,117 @@ export type paths = {
                         };
                     };
                 };
+                /** @description Unauthorized */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+                /** @description Forbidden */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+                /** @description Not Found */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+                /** @description Internal Server Error */
+                500: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    '/api/v0/documents:findDistinct': {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    'application/json': components['schemas']['FindDistinctDocumentsRequest'];
+                };
+            };
+            responses: {
+                /** @description Distinct values found */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': components['schemas']['FindDistinctDocumentsResponse'];
+                    };
+                };
+                /** @description Bad Request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
+                /** @description Unauthorized */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        'application/json': {
+                            /** @example Error message describing the issue. */
+                            message: string;
+                        };
+                    };
+                };
                 /** @description Forbidden */
                 403: {
                     headers: {
@@ -2953,12 +3064,21 @@ export type components = {
             contentSystemScope?: string;
         };
         HealthResponse: {
-            /** @example ok */
-            status: string;
-            /** @example connected */
-            database: string;
-            /** @example available */
-            s3: string;
+            /**
+             * @example ok
+             * @enum {string}
+             */
+            status: 'ok';
+            /**
+             * @example connected
+             * @enum {string}
+             */
+            database: 'connected' | 'disconnected';
+            /**
+             * @example available
+             * @enum {string}
+             */
+            s3: 'available' | 'unavailable';
             /** @example 2026-01-01T00:00:00.000Z */
             timestamp: string;
         };
@@ -3177,14 +3297,51 @@ export type components = {
                 count: number;
             };
         };
+        /** @example es */
+        LocaleClause: string;
         /**
-         * @example array
-         * @enum {string}
+         * @example {
+         *       "paths": [
+         *         "field_a",
+         *         "field_b"
+         *       ]
+         *     }
          */
-        PathType: 'array';
+        UniquePath: {
+            paths: string[];
+        };
+        PathTypeRelationship: {
+            /** @enum {string} */
+            type: 'relationship';
+            collection: string | string[];
+            hasMany?: boolean;
+        };
+        PathTypeJoin: {
+            /** @enum {string} */
+            type: 'join';
+            collection: string | string[];
+            hasMany?: boolean;
+            on: string;
+        };
+        /** @enum {string} */
+        PathTypeBlocks: 'blocks';
+        /** @example array */
+        PathType: 'array' | components['schemas']['PathTypeRelationship'] | components['schemas']['PathTypeJoin'] | components['schemas']['PathTypeBlocks'];
         /**
          * @example {
-         *       "author.tagIds": "array"
+         *       "author.tagIds": "array",
+         *       "author": {
+         *         "type": "relationship",
+         *         "collection": "users",
+         *         "hasMany": false
+         *       },
+         *       "relatedPosts": {
+         *         "type": "join",
+         *         "collection": "posts",
+         *         "hasMany": true,
+         *         "on": "category"
+         *       },
+         *       "blocks": "blocks"
          *     }
          */
         PathTypesMeta: {
@@ -3192,6 +3349,7 @@ export type components = {
         };
         RequestMeta: {
             localizedPaths?: string[];
+            uniquePaths?: components['schemas']['UniquePath'][];
             pathTypes?: components['schemas']['PathTypesMeta'];
         };
         DataValue: string | number | boolean | unknown | components['schemas']['DataValue'][] | {
@@ -3227,6 +3385,7 @@ export type components = {
             contentSystemId: string;
             /** @example posts */
             collection: string;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             where?: components['schemas']['WhereClause'];
         };
@@ -3291,29 +3450,46 @@ export type components = {
             page?: number;
             sort?: components['schemas']['SortClause'];
         }[];
-        /** @example es */
-        LocaleClause: string;
         /**
          * @example {
-         *       "mode": "include",
-         *       "paths": [
-         *         "title",
-         *         "author.name",
-         *         "tags"
-         *       ]
+         *       "title": true,
+         *       "author": {
+         *         "name": true,
+         *         "email": true
+         *       },
+         *       "tags": true
          *     }
          */
-        SelectClause: {
-            /** @enum {string} */
-            mode: 'exclude' | 'include';
-            paths: string[];
+        IncludeSelectClause: {
+            [key: string]: true | {
+                [key: string]: components['schemas']['IncludeSelectClause'];
+            };
+        };
+        /**
+         * @example {
+         *       "title": false,
+         *       "author": {
+         *         "name": false,
+         *         "email": false
+         *       },
+         *       "tags": false
+         *     }
+         */
+        ExcludeSelectClause: {
+            [key: string]: false | {
+                [key: string]: components['schemas']['ExcludeSelectClause'];
+            };
         };
+        /** @description Field selection - use include mode (true) or exclude mode (false), but not both */
+        SelectClause: components['schemas']['IncludeSelectClause'] | components['schemas']['ExcludeSelectClause'];
         CreateDocumentRequest: {
             /** @example cms-xxxxx-xxxxx */
             contentSystemId: string;
             /** @example posts */
             collection: string;
             doc: components['schemas']['DocumentData'];
+            locale?: components['schemas']['LocaleClause'];
+            meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
                 locale?: components['schemas']['LocaleClause'];
@@ -3353,6 +3529,47 @@ export type components = {
             sort?: components['schemas']['SortClause'];
             where?: components['schemas']['WhereClause'];
         };
+        FindDistinctDocumentsResponse: {
+            result: {
+                /**
+                 * @example [
+                 *       "value1",
+                 *       "value2"
+                 *     ]
+                 */
+                data: unknown[];
+                totalDocs: number;
+                limit: number;
+                page: number;
+                totalPages: number;
+                pagingCounter: number;
+                hasPrevPage: boolean;
+                hasNextPage: boolean;
+                prevPage: number | null;
+                nextPage: number | null;
+            };
+        };
+        FindDistinctDocumentsRequest: {
+            /** @example cms-xxxxx-xxxxx */
+            contentSystemId: string;
+            /** @example posts */
+            collection: string;
+            /**
+             * @description Path to the field to get distinct values for
+             * @example title
+             */
+            distinctBy: string;
+            join?: components['schemas']['JoinClause'];
+            /** @example 10 */
+            limit?: number;
+            locale?: components['schemas']['LocaleClause'];
+            /** @example 1 */
+            page?: number;
+            meta?: components['schemas']['RequestMeta'];
+            select?: components['schemas']['SelectClause'];
+            sort?: components['schemas']['SortClause'];
+            where?: components['schemas']['WhereClause'];
+        };
         UpdateDocumentResponse: {
             result?: {
                 /** @example 1 */
@@ -3388,6 +3605,7 @@ export type components = {
             doc: components['schemas']['DataWithOperations'];
             /** @example 10 */
             limit?: number;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
@@ -3396,7 +3614,6 @@ export type components = {
             };
             sort?: components['schemas']['SortClause'];
             where: components['schemas']['WhereClause'];
-            locale?: components['schemas']['LocaleClause'];
         };
         DeleteDocumentResponse: {
             result?: {
@@ -3414,6 +3631,7 @@ export type components = {
             contentSystemId: string;
             /** @example posts */
             collection: string;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
@@ -3421,7 +3639,6 @@ export type components = {
                 select?: components['schemas']['SelectClause'];
             };
             where: components['schemas']['WhereClause'];
-            locale?: components['schemas']['LocaleClause'];
         };
         CountDocumentVersionResponse: {
             result: {
@@ -3434,6 +3651,7 @@ export type components = {
             contentSystemId: string;
             /** @example posts */
             collection: string;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             where?: components['schemas']['WhereClause'];
         };
@@ -3495,6 +3713,8 @@ export type components = {
                 parent?: string | number;
                 version: components['schemas']['DocumentData'] & unknown;
             };
+            locale?: components['schemas']['LocaleClause'];
+            meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
                 locale?: components['schemas']['LocaleClause'];
@@ -3569,9 +3789,9 @@ export type components = {
             where: components['schemas']['WhereClause'];
             /** @example 10 */
             limit?: number;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             sort?: components['schemas']['SortClause'];
-            locale?: components['schemas']['LocaleClause'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];
                 locale?: components['schemas']['LocaleClause'];
@@ -3594,6 +3814,7 @@ export type components = {
             contentSystemId: string;
             /** @example posts */
             collection: string;
+            locale?: components['schemas']['LocaleClause'];
             meta?: components['schemas']['RequestMeta'];
             returning?: false | {
                 join?: components['schemas']['JoinClause'];

package/dist/plugin/build-config.js

@@ -62,18 +62,6 @@ function missingOAuthCredential(name) {
     }
 }
 export async function buildFigmaConfig(config) {
-    // Auto-migrate old env vars in local dev (never in Lambda/production)
-    if (process.env.NODE_ENV !== 'production' && !process.env.AWS_LAMBDA_FUNCTION_NAME) {
-        try {
-            const { handleEnvUpgrade } = await import('../utils/handle-upgrade.js');
-            const upgradeChanges = await handleEnvUpgrade(process.cwd());
-            if (upgradeChanges.length > 0) {
-                log.warning(`Auto-migrated .env: ${upgradeChanges.join(', ')}`);
-            }
-        } catch  {
-        // Never block config build due to upgrade check
-        }
-    }
     const envConfig = getEnvConfig();
     // Resolve contentSystemId: config first, then local store fallback (dev)
     let { contentSystemId } = config.figma;

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type arg from 'arg';
 export interface Args extends arg.Spec {
     '--debug': BooleanConstructor;
+    '--dry-run': BooleanConstructor;
     '--env': StringConstructor;
     '--force': BooleanConstructor;
     '--help': BooleanConstructor;

package/dist/utils/handle-upgrade.d.ts

@@ -1,12 +1,9 @@
 /**
- * Migrate .env file from old env var format to new format.
- * Non-blocking — returns list of changes made, never throws.
+ * Walk up from a directory to find the nearest package.json with name "@payloadcms/figma".
  */
-export declare function handleEnvUpgrade(projectPath: string): Promise<string[]>;
+export declare function findPackageRoot(startDir: string): Promise<null | string>;
 /**
- * Full upgrade migration: .env + payload.config.ts AST changes + version sync.
- * Called from CLI entry point before command routing.
- * Non-blocking — returns list of changes made, never throws.
+ * Build and pack the local @payloadcms/figma package, returning the tgz path.
  */
-export declare function handleUpgrade(projectPath: string): Promise<string[]>;
+export declare function packLocalPackage(pkgDir: string): string;
 //# sourceMappingURL=handle-upgrade.d.ts.map

package/dist/utils/handle-upgrade.js

@@ -1,36 +1,9 @@
 import { execSync } from 'child_process';
 import fs from 'fs/promises';
 import path from 'path';
-import { Project } from 'ts-morph';
-import { fileURLToPath } from 'url';
-import { getBootstrapInfo, getCmsResourceId } from '../api/control-plane.js';
-import { getValidAccessToken } from '../auth/oauth-flow.js';
-import { getTokenStore } from '../auth/token-store.js';
-import { cacheAllEnvironments } from './cache-bootstrap.js';
-import { addOrUpdateEnvVar, getEnvVar, removeEnvVar } from './env-management.js';
-import { formatFile } from './formatter.js';
-import * as log from './log.js';
-import { getPackageManager } from './package-manager.js';
-import { removeFigmaContentSystemId } from './payload-config-ast.js';
-import { findPayloadConfig } from './payload-config-finder.js';
-import { checkPackageInstalled, installPackage } from './payload-package-check.js';
-import { getOwnVersion } from './version-check.js';
-const OLD_ENV_VARS = [
-    'FIGMA_ENV',
-    'FIGMA_CONTENT_API_CONTENT_SYSTEM_ID',
-    'FIGMA_TENANT_ID',
-    'FIGMA_OAUTH_CLIENT_ID',
-    'FIGMA_OAUTH_CLIENT_SECRET'
-];
-const REMOVABLE_ENV_VARS = [
-    'FIGMA_CONTENT_API_CONTENT_SYSTEM_ID',
-    'FIGMA_TENANT_ID',
-    'FIGMA_OAUTH_CLIENT_ID',
-    'FIGMA_OAUTH_CLIENT_SECRET'
-];
 /**
  * Walk up from a directory to find the nearest package.json with name "@payloadcms/figma".
- */ async function findPackageRoot(startDir) {
+ */ export async function findPackageRoot(startDir) {
     let dir = startDir;
     while(true){
         const pkgPath = path.join(dir, 'package.json');
@@ -51,7 +24,7 @@ const REMOVABLE_ENV_VARS = [
 }
 /**
  * Build and pack the local @payloadcms/figma package, returning the tgz path.
- */ function packLocalPackage(pkgDir) {
+ */ export function packLocalPackage(pkgDir) {
     execSync('pnpm build', {
         cwd: pkgDir,
         stdio: 'pipe'
@@ -64,179 +37,5 @@ const REMOVABLE_ENV_VARS = [
     const tgzPath = path.join(pkgDir, tgzName);
     return tgzPath;
 }
-/**
- * Attempt to resolve bootstrap data: check cache first, then API call.
- */ async function resolveBootstrapData(projectId, environmentName) {
-    const store = getTokenStore();
-    const cached = store.getBootstrapData(projectId, environmentName);
-    if (cached) {
-        return cached;
-    }
-    try {
-        const accessToken = await getValidAccessToken(store);
-        if (!accessToken) {
-            return null;
-        }
-        const bootstrapInfo = await getBootstrapInfo(accessToken, projectId);
-        cacheAllEnvironments(store, projectId, bootstrapInfo);
-        return store.getBootstrapData(projectId, environmentName);
-    } catch  {
-        return null;
-    }
-}
-/**
- * Migrate .env file from old env var format to new format.
- * Non-blocking — returns list of changes made, never throws.
- */ export async function handleEnvUpgrade(projectPath) {
-    try {
-        const oldValues = {};
-        let hasOldVars = false;
-        for (const key of OLD_ENV_VARS){
-            const value = await getEnvVar(projectPath, key);
-            oldValues[key] = value;
-            if (value !== null) {
-                hasOldVars = true;
-            }
-        }
-        if (!hasOldVars) {
-            return [];
-        }
-        const changes = [];
-        // Rename FIGMA_ENV → FIGMA_INFRA_ENV
-        if (oldValues.FIGMA_ENV !== null) {
-            await addOrUpdateEnvVar(projectPath, 'FIGMA_INFRA_ENV', oldValues.FIGMA_ENV);
-            await removeEnvVar(projectPath, 'FIGMA_ENV');
-            changes.push('Renamed FIGMA_ENV → FIGMA_INFRA_ENV');
-        }
-        // Remove old vars if bootstrap data is available
-        const projectId = await getEnvVar(projectPath, 'FIGMA_PROJECT_ID');
-        const environmentName = await getEnvVar(projectPath, 'FIGMA_ENVIRONMENT_NAME') ?? 'production';
-        if (projectId) {
-            const bootstrapData = await resolveBootstrapData(projectId, environmentName);
-            if (bootstrapData) {
-                const removed = [];
-                for (const key of REMOVABLE_ENV_VARS){
-                    if (oldValues[key] !== null) {
-                        await removeEnvVar(projectPath, key);
-                        removed.push(key);
-                    }
-                }
-                if (removed.length > 0) {
-                    changes.push(`Removed deprecated env vars: ${removed.join(', ')}`);
-                }
-            } else {
-                log.warning('Could not resolve bootstrap data — keeping deprecated env vars. ' + 'Run `npx @payloadcms/figma init` to complete migration.');
-            }
-        }
-        return changes;
-    } catch (error) {
-        log.warning(`Upgrade migration failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
-        return [];
-    }
-}
-/**
- * Full upgrade migration: .env + payload.config.ts AST changes + version sync.
- * Called from CLI entry point before command routing.
- * Non-blocking — returns list of changes made, never throws.
- */ export async function handleUpgrade(projectPath) {
-    const changes = await handleEnvUpgrade(projectPath);
-    // Resolve CMS Resource ID from old content system ID via dataset API
-    try {
-        const existingProjectId = await getEnvVar(projectPath, 'FIGMA_PROJECT_ID');
-        if (!existingProjectId) {
-            const oldContentSystemId = await getEnvVar(projectPath, 'FIGMA_CONTENT_API_CONTENT_SYSTEM_ID');
-            if (oldContentSystemId) {
-                const store = getTokenStore();
-                const accessToken = await getValidAccessToken(store);
-                if (accessToken) {
-                    const cmsResourceId = await getCmsResourceId(accessToken, oldContentSystemId);
-                    await addOrUpdateEnvVar(projectPath, 'FIGMA_PROJECT_ID', cmsResourceId);
-                    await addOrUpdateEnvVar(projectPath, 'FIGMA_ENVIRONMENT_NAME', 'production');
-                    changes.push('Resolved FIGMA_PROJECT_ID from content system ID');
-                    // Fetch bootstrap data and cache it, then remove old vars
-                    try {
-                        const bootstrapInfo = await getBootstrapInfo(accessToken, cmsResourceId);
-                        cacheAllEnvironments(store, cmsResourceId, bootstrapInfo);
-                        const removed = [];
-                        for (const key of REMOVABLE_ENV_VARS){
-                            const value = await getEnvVar(projectPath, key);
-                            if (value !== null) {
-                                await removeEnvVar(projectPath, key);
-                                removed.push(key);
-                            }
-                        }
-                        if (removed.length > 0) {
-                            changes.push(`Removed deprecated env vars: ${removed.join(', ')}`);
-                        }
-                    } catch  {
-                        log.warning('Could not fetch bootstrap data — keeping deprecated env vars. ' + 'Run `npx @payloadcms/figma init` to complete migration.');
-                    }
-                } else {
-                    log.warning('Not authenticated — could not resolve FIGMA_PROJECT_ID. ' + 'Run `npx @payloadcms/figma init` to complete migration.');
-                }
-            }
-        }
-    } catch (error) {
-        log.warning(`Project ID migration failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    }
-    try {
-        const configPath = await findPayloadConfig(projectPath);
-        if (configPath) {
-            const project = new Project({
-                skipAddingFilesFromTsConfig: true
-            });
-            const sourceFile = project.addSourceFileAtPath(configPath);
-            const removed = removeFigmaContentSystemId(sourceFile);
-            if (removed) {
-                await sourceFile.save();
-                try {
-                    const packageManager = await getPackageManager(projectPath);
-                    await formatFile(configPath, packageManager);
-                } catch  {
-                // Formatting is best-effort
-                }
-                changes.push('Removed contentSystemId from payload.config.ts');
-            }
-        }
-    } catch (error) {
-        log.warning(`Config migration failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    }
-    // Sync @payloadcms/figma version in project's package.json
-    try {
-        const isInstalled = await checkPackageInstalled(projectPath, '@payloadcms/figma');
-        if (isInstalled) {
-            const cliDir = path.dirname(fileURLToPath(import.meta.url));
-            const isFromRegistry = cliDir.includes('node_modules') || cliDir.includes('.npm');
-            if (isFromRegistry) {
-                // Registry install: sync to CLI version
-                const cliVersion = await getOwnVersion();
-                const pkgJsonPath = path.join(projectPath, 'package.json');
-                const pkgJson = JSON.parse(await fs.readFile(pkgJsonPath, 'utf-8'));
-                const installedVersion = pkgJson.dependencies?.['@payloadcms/figma']?.replace(/^[\^~>=<]+/, '');
-                if (installedVersion && installedVersion !== cliVersion) {
-                    const packageManager = await getPackageManager(projectPath);
-                    await installPackage(projectPath, '@payloadcms/figma', packageManager, cliVersion);
-                    changes.push(`Updated @payloadcms/figma ${installedVersion} → ${cliVersion}`);
-                }
-            } else {
-                // Local CLI: pack and install tgz into the project
-                const pkgDir = await findPackageRoot(cliDir);
-                if (pkgDir) {
-                    log.debug('CLI running from local path — packing and installing into project...');
-                    const packageManager = await getPackageManager(projectPath);
-                    const tgzPath = packLocalPackage(pkgDir);
-                    const destTgz = path.join(projectPath, path.basename(tgzPath));
-                    await fs.rename(tgzPath, destTgz);
-                    await installPackage(projectPath, destTgz, packageManager);
-                    await fs.unlink(destTgz).catch(()=>{});
-                    changes.push('Installed @payloadcms/figma from local build');
-                }
-            }
-        }
-    } catch (error) {
-        log.warning(`Package version sync failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    }
-    return changes;
-}
 
 //# sourceMappingURL=handle-upgrade.js.map

package/dist/utils/messages.js

@@ -17,6 +17,7 @@ export function helpMessage() {
       ${pc.cyan('debug')}            Show debug info for troubleshooting
       ${pc.cyan('env')}              Switch active environment
       ${pc.cyan('deploy')}           Deploy your project to Figma
+      ${pc.cyan('upgrade')}          Run upgrade migrations
       ${pc.cyan('build-lambda-zip')} Build Lambda deployment zip
 
   ${pc.bold('OPTIONS')}
@@ -50,6 +51,11 @@ export function helpMessage() {
       ${pc.dim('--yes, -y')}                             Skip confirmation prompts
       ${pc.dim('--skip-build')}                          Skip building and use existing build
 
+  ${pc.bold('UPGRADE COMMAND')}
+
+      ${pc.cyan('@payloadcms/figma upgrade')}              Run all upgrade migrations
+      ${pc.dim('--dry-run')}                               Preview changes without applying
+
   ${pc.bold('GLOBAL OPTIONS')}
 
       ${pc.dim('--infra-env <env>')}                     Target infrastructure (production or staging)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@payloadcms/figma",
-  "version": "0.0.1-alpha.52",
+  "version": "0.0.1-alpha.54",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
   "exports": {