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

package/dist/auth/crypto-utils.d.ts

@@ -30,4 +30,10 @@
  * @throws Error if unable to derive key due to missing machine information
  */
 export declare function deriveEncryptionKey(): string;
+/**
+ * Get a short hash of the encryption key for diagnostics.
+ * Returns first 8 chars of SHA-256 hash — enough to compare across invocations
+ * without exposing the actual key.
+ */
+export declare function getEncryptionKeyHash(): string;
 //# sourceMappingURL=crypto-utils.d.ts.map

package/dist/auth/crypto-utils.js

@@ -33,19 +33,13 @@ import os from 'os';
  * @throws Error if unable to gather sufficient entropy
  */ function gatherMachineEntropy() {
     try {
-        const userInfo = os.userInfo();
-        const networkInterfaces = os.networkInterfaces();
-        // Get MAC address from first available network interface (if available)
-        const macAddress = Object.values(networkInterfaces).flat().find((iface)=>iface && !iface.internal && iface.mac !== '00:00:00:00:00:00')?.mac;
         const entropy = [
             os.hostname(),
             os.homedir(),
-            userInfo.username,
+            os.userInfo().username,
             os.platform(),
-            os.arch(),
-            macAddress
-        ].filter(Boolean) // Remove any undefined values
-        ;
+            os.arch()
+        ];
         if (entropy.length < 4) {
             throw new Error('Insufficient machine entropy available');
         }
@@ -92,5 +86,13 @@ import os from 'os';
     const key = crypto.pbkdf2Sync(machineId, salt, 100000, 32, 'sha256');
     return key.toString('hex');
 }
+/**
+ * Get a short hash of the encryption key for diagnostics.
+ * Returns first 8 chars of SHA-256 hash — enough to compare across invocations
+ * without exposing the actual key.
+ */ export function getEncryptionKeyHash() {
+    const key = deriveEncryptionKey();
+    return crypto.createHash('sha256').update(key).digest('hex').substring(0, 8);
+}
 
 //# sourceMappingURL=crypto-utils.js.map

package/dist/auth/oauth-flow.d.ts

@@ -59,4 +59,9 @@ export declare function executeOAuthFlow(tokenStore: TokenStore, options?: OAuth
  * @throws OAuthFlowError if refresh fails
  */
 export declare function getValidAccessToken(tokenStore: TokenStore): Promise<null | string>;
+/**
+ * Like getValidAccessToken but returns null instead of throwing on refresh failure.
+ * Use in commands that want to fall through to a login prompt on failure.
+ */
+export declare function tryGetAccessToken(tokenStore: TokenStore): Promise<null | string>;
 //# sourceMappingURL=oauth-flow.d.ts.map

package/dist/auth/oauth-flow.js

@@ -155,19 +155,36 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
     if (!refreshToken) {
         return null;
     }
-    // Try to refresh
+    // Try to refresh (with one retry for transient auth errors)
     try {
         const tokens = await refreshAccessToken(refreshToken);
         tokenStore.setTokens(tokens);
         return tokens.accessToken;
     } catch (error) {
-        // Only clear tokens for actual auth failures, not transient errors
         const isAuthFailure = error instanceof TokenRefreshError && (error.statusCode === 401 || error.statusCode === 403 || error.statusCode === 400 && error.errorCode === 'invalid_grant');
         if (isAuthFailure) {
-            tokenStore.clearTokens();
+            // Retry once — a transient 401 (e.g. misconfigured proxy) shouldn't wipe tokens
+            try {
+                const tokens = await refreshAccessToken(refreshToken);
+                tokenStore.setTokens(tokens);
+                return tokens.accessToken;
+            } catch  {
+                // Retry also failed — token is genuinely revoked
+                tokenStore.clearTokens();
+            }
         }
         throw new OAuthFlowError('Failed to refresh access token', error instanceof Error ? error : undefined);
     }
 }
+/**
+ * Like getValidAccessToken but returns null instead of throwing on refresh failure.
+ * Use in commands that want to fall through to a login prompt on failure.
+ */ export async function tryGetAccessToken(tokenStore) {
+    try {
+        return await getValidAccessToken(tokenStore);
+    } catch  {
+        return null;
+    }
+}
 
 //# sourceMappingURL=oauth-flow.js.map

package/dist/auth/token-store.d.ts

@@ -24,7 +24,9 @@ export declare function getTokenStore(environment?: Environment): TokenStore;
  */
 export declare class TokenStore {
     private config;
+    private environment;
     constructor(options?: TokenStoreConfig);
+    private safeGet;
     /**
      * Retrieve stored tokens
      * @returns FigmaTokens if stored, null otherwise

package/dist/auth/token-store.js

@@ -1,6 +1,8 @@
 /* eslint-disable perfectionist/sort-classes */ import Conf from 'conf';
+import fsSync from 'node:fs';
 import { TOKEN_EXPIRY_BUFFER_SECONDS } from '../config/oauth.js';
 import { getInfraEnvironment } from '../constants.js';
+import * as log from '../utils/log.js';
 import { deriveEncryptionKey } from './crypto-utils.js';
 /**
  * Environment-keyed instances for singleton pattern
@@ -34,24 +36,57 @@ import { deriveEncryptionKey } from './crypto-utils.js';
  * The constructor is still exported for test isolation.
  */ export class TokenStore {
     config;
+    environment;
     constructor(options){
         if (process.env.AWS_EXECUTION_ENV) {
             throw new Error('TokenStore cannot be used in AWS Lambda environments');
         }
         const environment = options?.environment ?? 'production';
         const projectName = environment === 'production' ? 'payloadcms-figma' : `payloadcms-figma-${environment}`;
-        this.config = new Conf({
-            clearInvalidConfig: true,
+        this.environment = environment;
+        const confOptions = {
+            clearInvalidConfig: false,
             configName: options?.configName || projectName,
             encryptionKey: options?.encryptionKey || deriveEncryptionKey(),
             projectName
-        });
+        };
+        try {
+            this.config = new Conf(confOptions);
+        } catch (error) {
+            // Deserialization failed (e.g. encryption key changed).
+            // Log diagnostics, clear the corrupted file, then create a fresh store.
+            if (environment === 'staging') {
+                log.warning(`Token store corrupted, resetting. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
+            }
+            // Temporarily allow clearing so Conf can reinitialize
+            this.config = new Conf({
+                ...confOptions,
+                clearInvalidConfig: true
+            });
+            // Force a write so the corrupt file is replaced with an empty store.
+            // Without this, clearInvalidConfig only ignores bad reads in memory
+            // and the corrupt file persists, triggering this fallback every time.
+            this.config.clear();
+        }
+    }
+    safeGet(key) {
+        try {
+            return this.config.get(key);
+        } catch (error) {
+            if (this.environment === 'staging') {
+                const filePath = this.config.path;
+                const fileExists = fsSync.existsSync(filePath);
+                const fileSize = fileExists ? fsSync.statSync(filePath).size : 0;
+                log.warning(`Token store read failed (key: ${key}). ` + `File: ${filePath}, exists: ${fileExists}, size: ${fileSize}B. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
+            }
+            return undefined;
+        }
     }
     /**
    * Retrieve stored tokens
    * @returns FigmaTokens if stored, null otherwise
    */ getTokens() {
-        const tokens = this.config.get('tokens');
+        const tokens = this.safeGet('tokens');
         return tokens || null;
     }
     /**
@@ -59,6 +94,16 @@ import { deriveEncryptionKey } from './crypto-utils.js';
    * @param tokens - Figma OAuth2 tokens to store
    */ setTokens(tokens) {
         this.config.set('tokens', tokens);
+        // Verify the round-trip: read back what we just wrote
+        const readBack = this.safeGet('tokens');
+        if (!readBack || readBack.accessToken !== tokens.accessToken) {
+            if (this.environment === 'staging') {
+                const filePath = this.config.path;
+                const fileExists = fsSync.existsSync(filePath);
+                const fileSize = fileExists ? fsSync.statSync(filePath).size : 0;
+                log.warning(`Token verify-after-write FAILED. ` + `File: ${filePath}, exists: ${fileExists}, size: ${fileSize}B. ` + `Written accessToken starts: ${tokens.accessToken.substring(0, 10)}..., ` + `Read back: ${readBack ? readBack.accessToken.substring(0, 10) + '...' : 'null'}`);
+            }
+        }
     }
     /**
    * Clear all stored tokens (used for logout)
@@ -80,8 +125,7 @@ import { deriveEncryptionKey } from './crypto-utils.js';
    * Includes a buffer time to avoid using tokens that are about to expire
    * @returns true if token is expired or will expire within buffer time
    */ isExpired() {
-        // Access config directly to avoid circular dependency with getTokens()
-        const tokens = this.config.get('tokens');
+        const tokens = this.safeGet('tokens');
         if (!tokens) {
             return true;
         }
@@ -136,7 +180,7 @@ import { deriveEncryptionKey } from './crypto-utils.js';
    * @param tenantId - The tenant/CMS ID
    * @returns ProjectToken if stored and valid, null otherwise
    */ getProjectToken(tenantId) {
-        const projectTokens = this.config.get('projectTokens') || {};
+        const projectTokens = this.safeGet('projectTokens') || {};
         const projectToken = projectTokens[tenantId];
         if (!projectToken) {
             return null;
@@ -153,7 +197,7 @@ import { deriveEncryptionKey } from './crypto-utils.js';
    * @param tenantId - The tenant/CMS ID
    * @param projectToken - The project token to store
    */ setProjectToken(tenantId, projectToken) {
-        const projectTokens = this.config.get('projectTokens') || {};
+        const projectTokens = this.safeGet('projectTokens') || {};
         projectTokens[tenantId] = projectToken;
         this.config.set('projectTokens', projectTokens);
     }
@@ -161,7 +205,7 @@ import { deriveEncryptionKey } from './crypto-utils.js';
    * Clear a project token for a specific tenant
    * @param tenantId - The tenant/CMS ID
    */ clearProjectToken(tenantId) {
-        const projectTokens = this.config.get('projectTokens') || {};
+        const projectTokens = this.safeGet('projectTokens') || {};
         delete projectTokens[tenantId];
         this.config.set('projectTokens', projectTokens);
     }
@@ -204,7 +248,7 @@ import { deriveEncryptionKey } from './crypto-utils.js';
    * Get all tenant IDs that have stored project tokens
    * @returns Array of tenant IDs
    */ getAllProjectTokenTenantIds() {
-        const projectTokens = this.config.get('projectTokens') || {};
+        const projectTokens = this.safeGet('projectTokens') || {};
         return Object.keys(projectTokens);
     }
     /**
@@ -221,7 +265,7 @@ import { deriveEncryptionKey } from './crypto-utils.js';
    * @param environmentName - The environment name
    * @returns BootstrapData if stored, null otherwise
    */ getBootstrapData(projectId, environmentName) {
-        const allData = this.config.get('bootstrapData') || {};
+        const allData = this.safeGet('bootstrapData') || {};
         return allData[this.bootstrapKey(projectId, environmentName)] || null;
     }
     /**
@@ -230,7 +274,7 @@ import { deriveEncryptionKey } from './crypto-utils.js';
    * @param environmentName - The environment name
    * @param data - The bootstrap data to store
    */ setBootstrapData(projectId, environmentName, data) {
-        const allData = this.config.get('bootstrapData') || {};
+        const allData = this.safeGet('bootstrapData') || {};
         allData[this.bootstrapKey(projectId, environmentName)] = data;
         this.config.set('bootstrapData', allData);
     }
@@ -239,7 +283,7 @@ import { deriveEncryptionKey } from './crypto-utils.js';
    * @param projectId - The CMS resource/project ID
    * @param environmentName - The environment name
    */ clearBootstrapData(projectId, environmentName) {
-        const allData = this.config.get('bootstrapData') || {};
+        const allData = this.safeGet('bootstrapData') || {};
         delete allData[this.bootstrapKey(projectId, environmentName)];
         this.config.set('bootstrapData', allData);
     }

package/dist/cli.js

@@ -43,8 +43,11 @@ class Main {
             '--version': Boolean,
             '--yes': Boolean,
             // Aliases
+            '--environment': '--env',
+            '-e': '--env',
             '-f': '--force',
             '-h': '--help',
+            '-n': '--name',
             '-v': '--version',
             '-y': '--yes'
         }, {

package/dist/commands/debug.js

@@ -2,6 +2,7 @@ import fsSync from 'node:fs';
 import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
+import { getEncryptionKeyHash } from '../auth/crypto-utils.js';
 import { getTokenStore } from '../auth/token-store.js';
 import { getInfraEnvironment } from '../constants.js';
 import { getEnvVarSync } from '../utils/env-management.js';
@@ -22,6 +23,7 @@ import { getOwnVersion } from '../utils/version-check.js';
     ];
     appendSystemSection(lines, env);
     appendAuthSection(lines, tokenStore, cwd);
+    appendTokenStoreDiagnostics(lines, tokenStore);
     appendProjectSection(lines, tokenStore, cwd);
     await appendPackagesSection(lines);
     // eslint-disable-next-line no-console
@@ -52,6 +54,19 @@ function appendAuthSection(lines, tokenStore, cwd) {
     lines.push(`  Token Expires:    ${formatExpiryTime(tokens.expiresAt)}`);
     lines.push('');
 }
+function appendTokenStoreDiagnostics(lines, tokenStore) {
+    lines.push('Token Store:');
+    const filePath = tokenStore.getStoragePath();
+    const fileExists = fsSync.existsSync(filePath);
+    const fileSize = fileExists ? fsSync.statSync(filePath).size : 0;
+    lines.push(`  File:             ${filePath}`);
+    lines.push(`  File Exists:      ${fileExists}`);
+    lines.push(`  File Size:        ${fileSize}B`);
+    const canRead = tokenStore.getTokens() !== null || tokenStore.getRefreshToken() !== null;
+    lines.push(`  Decryption:       ${fileExists ? canRead || fileSize === 0 ? 'OK' : 'FAILED' : 'N/A'}`);
+    lines.push(`  Key Hash:         ${getEncryptionKeyHash()}`);
+    lines.push('');
+}
 function appendProjectSection(lines, tokenStore, cwd) {
     const projectId = getEnvVarSync(cwd, 'FIGMA_PROJECT_ID');
     const environmentName = getEnvVarSync(cwd, 'FIGMA_ENVIRONMENT_NAME');

package/dist/commands/deploy.js

@@ -3,9 +3,9 @@ import spawn from 'cross-spawn';
 import path from 'path';
 import pc from 'picocolors';
 import { ControlPlaneError, createDeployment, getBootstrapInfo, performDeployment } from '../api/control-plane.js';
-import { getValidAccessToken } from '../auth/oauth-flow.js';
+import { tryGetAccessToken } from '../auth/oauth-flow.js';
 import { getTokenStore } from '../auth/token-store.js';
-import { CONTENT_SYSTEM_NOT_FOUND_MESSAGE } from '../constants.js';
+import { getInfraEnvironment, getProjectNotFoundMessage } from '../constants.js';
 import { collectStaticAssets, createLambdaZip, getFileSize } from '../utils/asset-collection.js';
 import { detectBuild, getBuildCommand } from '../utils/build-detection.js';
 import { getEnvVar } from '../utils/env-management.js';
@@ -71,11 +71,11 @@ import { loginCommand } from './login.js';
         }
         // Check authentication
         const tokenStore = getTokenStore();
-        let accessToken = await getValidAccessToken(tokenStore);
+        let accessToken = await tryGetAccessToken(tokenStore);
         if (!accessToken) {
             p.log.message('Please log in to continue');
             await loginCommand();
-            accessToken = await getValidAccessToken(tokenStore);
+            accessToken = await tryGetAccessToken(tokenStore);
             if (!accessToken) {
                 p.log.error(pc.red('✗ Authentication failed'));
                 process.exit(1);
@@ -94,14 +94,19 @@ import { loginCommand } from './login.js';
             spinner.stop(pc.green(`✓ Target: ${resolvedEnv.name}`));
         } catch (error) {
             if (error instanceof ControlPlaneError && (error.statusCode === 404 || error.statusCode === 410)) {
-                spinner.stop(pc.red('✗ Content system not found'));
-                p.log.error(pc.red(CONTENT_SYSTEM_NOT_FOUND_MESSAGE));
+                spinner.stop(pc.red('✗ Project not found'));
+                p.log.error(pc.red(getProjectNotFoundMessage({
+                    environment: getInfraEnvironment(),
+                    projectId
+                })));
                 process.exit(1);
             }
             spinner.stop(pc.red('✗ Failed to resolve deployment target'));
             p.log.error(error instanceof Error ? error.message : 'Unknown error');
             process.exit(1);
         }
+        // Signal buildFigmaConfig to extract schedules during build
+        process.env.FIGMA_EXTRACT_SCHEDULES = 'true';
         // ===== BUILD =====
         let buildInfo;
         if (options.skipBuild) {

package/dist/commands/init.js

@@ -4,10 +4,10 @@ import path from 'path';
 import pc from 'picocolors';
 import { ControlPlaneError, getBootstrapInfo } from '../api/control-plane.js';
 import { FigmaApiError } from '../api/figma-api.js';
-import { getValidAccessToken } from '../auth/oauth-flow.js';
+import { tryGetAccessToken } from '../auth/oauth-flow.js';
 import { getValidProjectToken, ProjectTokenError } from '../auth/project-token.js';
 import { getTokenStore } from '../auth/token-store.js';
-import { CONTENT_SYSTEM_NOT_FOUND_MESSAGE, getInfraEnvironment } from '../constants.js';
+import { getInfraEnvironment, getProjectNotFoundMessage } from '../constants.js';
 import { ensureGitignore } from '../utils/config.js';
 import { addOrUpdateEnvVar } from '../utils/env-management.js';
 import { isDebug } from '../utils/is-debug.js';
@@ -77,33 +77,24 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
         // Skip authentication for testing/development
         p.log.warn(pc.yellow('Skipping authentication (--skip-auth mode)'));
     } else {
-        try {
-            // Check for valid cached tokens first (no API call needed)
-            if (!tokenStore.hasValidTokens()) {
-                // Need to refresh or authenticate - show spinner for API call
-                s.start('Checking authentication...');
-                const token = await getValidAccessToken(tokenStore);
-                if (!token) {
-                    s.stop('Authentication required to continue');
-                    // Run login command
-                    await loginCommand({
-                        showNextSteps: false
-                    });
-                    // Get token after auth
-                    const newToken = await getValidAccessToken(tokenStore);
-                    if (!newToken) {
-                        p.log.error('Authentication failed');
-                        process.exit(1);
-                    }
-                } else {
-                    s.stop(pc.green('✓ Authenticated'));
+        // Check for valid cached tokens first (no API call needed)
+        if (!tokenStore.hasValidTokens()) {
+            // Need to refresh or authenticate - show spinner for API call
+            s.start('Checking authentication...');
+            const token = await tryGetAccessToken(tokenStore);
+            if (!token) {
+                s.stop('Authentication required to continue');
+                await loginCommand({
+                    showNextSteps: false
+                });
+                const newToken = await tryGetAccessToken(tokenStore);
+                if (!newToken) {
+                    p.log.error('Authentication failed');
+                    process.exit(1);
                 }
+            } else {
+                s.stop(pc.green('✓ Authenticated'));
             }
-        } catch (error) {
-            s.stop(pc.red('✗ Authentication failed'));
-            log.error(error instanceof Error ? error.message : 'Unknown error');
-            p.note('Run `figma auth` to authenticate', 'Tip');
-            process.exit(1);
         }
     }
     // Note: We no longer check for figma.config.json here
@@ -122,21 +113,17 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
     let oauthClientId = null;
     let oauthClientSecret = null;
     if (!options.skipAuth) {
-        const accessToken = await getValidAccessToken(tokenStore);
+        const accessToken = await tryGetAccessToken(tokenStore);
         if (accessToken) {
             try {
                 bootstrapInfo = await getBootstrapInfo(accessToken, cmsResourceId);
-                const envName = options.env ?? process.env.FIGMA_ENVIRONMENT_NAME ?? undefined;
-                resolvedEnv = resolveEnvironment({
-                    environmentName: envName,
-                    environments: bootstrapInfo.environments
-                });
-                oauthClientId = bootstrapInfo.oauthCredentials.oauthClientId;
-                oauthClientSecret = bootstrapInfo.oauthCredentials.oauthClientSecret;
             } catch (error) {
                 log.debug(`Control Plane Error: ${error.statusCode} - ${error.message}`);
                 if (error instanceof ControlPlaneError && (error.statusCode === 404 || error.statusCode === 410)) {
-                    p.log.error(pc.red(CONTENT_SYSTEM_NOT_FOUND_MESSAGE));
+                    p.log.error(pc.red(getProjectNotFoundMessage({
+                        environment: getInfraEnvironment(),
+                        projectId: cmsResourceId
+                    })));
                     process.exit(1);
                 }
                 const message = error instanceof Error ? error.message : 'Unknown error';
@@ -144,6 +131,18 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
                 p.log.error(pc.dim(`Details: ${message}`));
                 process.exit(1);
             }
+            try {
+                const envName = options.env ?? process.env.FIGMA_ENVIRONMENT_NAME ?? undefined;
+                resolvedEnv = resolveEnvironment({
+                    environmentName: envName,
+                    environments: bootstrapInfo.environments
+                });
+                oauthClientId = bootstrapInfo.oauthCredentials.oauthClientId;
+                oauthClientSecret = bootstrapInfo.oauthCredentials.oauthClientSecret;
+            } catch (error) {
+                p.log.error(pc.red(error instanceof Error ? error.message : 'Unknown error'));
+                process.exit(1);
+            }
         }
     }
     // Step 4: Detect or scaffold Payload project
@@ -238,7 +237,10 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
             process.exit(1);
         }
         // Generate import map to prevent errors on first dev run
-        await runScript(process.cwd(), 'generate:importmap', packageManager);
+        const importMapResult = await runScript(process.cwd(), 'generate:importmap', packageManager);
+        if (!importMapResult) {
+            p.log.warn(pc.yellow('⚠ Import map generation failed — it will be generated on first dev run'));
+        }
         // Apply Lambda modifications (run.sh, standalone output, lambda:buildzip script)
         await applyLambdaModifications(process.cwd(), packageManager);
         // Ensure .gitignore has required entries
@@ -260,27 +262,30 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
     } else {
         // ===== NEW PROJECT FLOW =====
         // p.log.info('No project detected - Creating New Project')
-        // Prompt for path
-        const projectPathInput = await p.text({
-            initialValue: './',
-            message: 'Enter path to create project:',
-            placeholder: './my-cms-project',
-            validate: (value)=>{
-                if (!value) {
-                    return 'Path is required';
+        let projectPath;
+        if (options.name) {
+            projectPath = options.name;
+        } else {
+            const projectPathInput = await p.text({
+                initialValue: './',
+                message: 'Enter path to create project:',
+                placeholder: './my-cms-project',
+                validate: (value)=>{
+                    if (!value) {
+                        return 'Path is required';
+                    }
+                    // Allow relative or absolute paths
+                    return undefined;
                 }
-                // Allow relative or absolute paths
-                return undefined;
+            });
+            if (p.isCancel(projectPathInput)) {
+                p.cancel('Operation cancelled');
+                process.exit(0);
             }
-        });
-        if (p.isCancel(projectPathInput)) {
-            p.cancel('Operation cancelled');
-            process.exit(0);
+            projectPath = projectPathInput;
         }
-        const projectPath = projectPathInput;
         const fullPath = path.resolve(process.cwd(), projectPath);
-        // Get project name from path or prompt
-        const projectName = options.name || path.basename(fullPath);
+        const projectName = path.basename(fullPath);
         const packageManager = detectPackageManagerFromEnvironment();
         // Create directory
         try {
@@ -346,7 +351,10 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
             p.log.warn(pc.yellow(`⚠ Failed to update .env file: ${error instanceof Error ? error.message : 'Unknown error'}`));
         }
         // Generate import map to prevent errors on first dev run
-        await runScript(fullPath, 'generate:importmap', packageManager);
+        const importMapResult = await runScript(fullPath, 'generate:importmap', packageManager);
+        if (!importMapResult) {
+            p.log.warn(pc.yellow('⚠ Import map generation failed — it will be generated on first dev run'));
+        }
         // Generate project token (unless skipping auth)
         if (!options.skipAuth && resolvedEnv) {
             await generateProjectTokenWithFeedback(tokenStore, resolvedEnv.contentSystemId, s);

package/dist/constants.d.ts

@@ -23,9 +23,17 @@ type EnvironmentConfig = {
 export declare const ENV_CONFIG: Record<Environment, EnvironmentConfig>;
 /**
  * User-facing error message when Content API returns 404 or 410.
- * Used across CLI commands and the db adapter for consistent messaging.
+ * Used by the db adapter for consistent messaging at runtime.
  */
 export declare const CONTENT_SYSTEM_NOT_FOUND_MESSAGE = "Content system not found. Verify your Content System ID is correct, or contact your team admin for assistance.";
+/**
+ * Build a user-facing error message for CLI commands when a project is not found (404/410).
+ * Includes infra-env context and actionable suggestions.
+ */
+export declare function getProjectNotFoundMessage(params: {
+    environment: Environment;
+    projectId: string;
+}): string;
 /**
  * Set infrastructure environment override (used by --infra-env CLI flag)
  * Pass undefined to clear the override

package/dist/constants.js

@@ -22,8 +22,22 @@ import { getEnvVarSync } from './utils/env-management.js';
 };
 /**
  * User-facing error message when Content API returns 404 or 410.
- * Used across CLI commands and the db adapter for consistent messaging.
+ * Used by the db adapter for consistent messaging at runtime.
  */ export const CONTENT_SYSTEM_NOT_FOUND_MESSAGE = 'Content system not found. Verify your Content System ID is correct, or contact your team admin for assistance.';
+/**
+ * Build a user-facing error message for CLI commands when a project is not found (404/410).
+ * Includes infra-env context and actionable suggestions.
+ */ export function getProjectNotFoundMessage(params) {
+    const { environment, projectId } = params;
+    return [
+        `Project not found on ${environment} (ID: ${projectId}).`,
+        '',
+        'Suggestions:',
+        '  • Verify your project ID is correct',
+        "  • Ensure you're logged into the correct Figma account",
+        '  • Contact your team admin for assistance'
+    ].join('\n');
+}
 let envOverride;
 /**
  * Set infrastructure environment override (used by --infra-env CLI flag)
@@ -55,6 +69,7 @@ export function getInfraEnvironment() {
             return 'staging';
         }
         if (env !== 'production') {
+            // eslint-disable-next-line no-console
             console.warn(`Warning: Invalid FIGMA_INFRA_ENV value "${envFileValue}" in .env file. Using production.`);
         }
         return 'production';

package/dist/db-content-api/index.d.ts

@@ -13,6 +13,7 @@ export type ContentAPIAdapter = {
     clearDatabase: () => Promise<void>;
     client: ReturnType<typeof createClient<paths>>;
     contentSystemId: string;
+    idType: 'uuid';
     url: string;
 } & BaseDatabaseAdapter;
 export declare const contentAPIAdapter: (opts: ContentAPIOptions) => DatabaseAdapterObj;

package/dist/db-content-api/index.js

@@ -7,7 +7,7 @@ import { getGlobalSlug } from './temp-utilities/slug.js';
 import { addFallbackSort } from './temp-utilities/sorting.js';
 import { unwrapDocument, unwrapFindResponse } from './temp-utilities/unwrapDocument.js';
 import { createAuthMiddleware, createErrorMiddleware } from './utilities/auth.js';
-import { dataToContentAPI } from './utilities/data/index.js';
+import { dataToContentAPI, resolveVersionContent } from './utilities/data/index.js';
 import { convertPayloadJoinsToContentAPI } from './utilities/joins.js';
 import { addFallbackLocale } from './utilities/locale/index.js';
 import { buildMeta } from './utilities/meta/buildMeta.js';
@@ -225,8 +225,8 @@ async function updateVersion(args) {
         }
     };
     const locale = addFallbackLocale(args.locale, this.payload);
-    // versionData contains version metadata plus nested version content
     const { publishedLocale, version, ...versionMeta } = args.versionData;
+    const resolvedVersion = resolveVersionContent(version, versionMeta);
     const { data: response, error } = await this.client.POST('/api/v0/document_versions:update', {
         body: {
             collection: args.collection,
@@ -238,7 +238,7 @@ async function updateVersion(args) {
                 latest: versionMeta.latest,
                 parent: versionMeta.parent != null ? String(versionMeta.parent) : undefined,
                 updatedAt: versionMeta.updatedAt,
-                version: dataToContentAPI(this.payload, args.collection, version, {
+                version: dataToContentAPI(this.payload, args.collection, resolvedVersion, {
                     publishedLocale
                 })
             },
@@ -299,6 +299,37 @@ async function findOne(args) {
     });
     return docs[0] ?? null;
 }
+async function findDistinct(args) {
+    const locale = addFallbackLocale(args.locale, this.payload);
+    const { data: response, error } = await this.client.POST('/api/v0/documents:findDistinct', {
+        body: {
+            collection: args.collection,
+            contentSystemId: this.contentSystemId,
+            distinctBy: args.field,
+            limit: args.limit,
+            locale,
+            page: args.page ?? 1,
+            sort: addFallbackSort(args.sort, this.payload, args.collection),
+            where: convertPayloadWhereToContentAPI(args.where ?? {}),
+            ...buildMeta(this.payload, {
+                collection: args.collection,
+                locale,
+                where: args.where
+            })
+        }
+    });
+    if (error) {
+        throw new Error(`Content API findDistinct error: ${JSON.stringify(error)}`);
+    }
+    const { data, ...pagination } = response.result;
+    return {
+        ...pagination,
+        // Content API returns flat values; Payload expects objects keyed by field name.
+        values: data.map((value)=>({
+                [args.field]: value
+            }))
+    };
+}
 async function updateMany(args) {
     const locale = addFallbackLocale(args.locale, this.payload);
     const { data: response, error } = await this.client.POST('/api/v0/documents:update', {
@@ -418,7 +449,18 @@ async function deleteOne(args) {
 async function create(args) {
     const isGlobalCollection = args.collection.startsWith('_global-');
     const customIDType = this.payload.collections[args.collection]?.customIDType;
-    const id = (isGlobalCollection || customIDType || this.allowIDOnCreate) && args.data.id != null && (typeof args.data.id === 'string' || typeof args.data.id === 'number') ? String(args.data.id) : uuid();
+    // See test: "should allow creating docs with payload.db.create with custom ID".
+    // TODO: customID is not yet in our installed types. Remove this when it is.
+    // When provided (e.g. from payload.db.create), it takes priority over data.id.
+    const customID = args.customID;
+    let id;
+    if (customID != null) {
+        id = String(customID);
+    } else if ((isGlobalCollection || customIDType || this.allowIDOnCreate) && args.data.id != null && (typeof args.data.id === 'string' || typeof args.data.id === 'number')) {
+        id = String(args.data.id);
+    } else {
+        id = uuid();
+    }
     const locale = addFallbackLocale(args.locale, this.payload);
     const { data: response, error } = await this.client.POST('/api/v0/documents:create', {
         body: {
@@ -580,8 +622,9 @@ function findGlobal(args) {
     });
 }
 async function updateGlobal(args) {
-    // Use upsert to ensure the global exists
-    // Use slug as the consistent document ID for globals
+    // TODO: upsert's `createOnMissing` path generates a new `createdAt` on every call,
+    // which overwrites the original timestamp on updates. The fix belongs in the Content API:
+    // `createOnMissing` should preserve `createdAt` on updates and only set it on creates.
     return this.upsert({
         collection: getGlobalSlug(args.slug),
         data: args.data,
@@ -678,11 +721,12 @@ export const contentAPIAdapter = (opts)=>({
                 deleteOne: deleteOne,
                 deleteVersions: deleteVersions,
                 find: find,
-                findDistinct: ()=>Promise.reject(new Error('findDistinct is not yet implemented for Content API adapter')),
+                findDistinct: findDistinct,
                 findGlobal: findGlobal,
                 findGlobalVersions: findGlobalVersions,
                 findOne: findOne,
                 findVersions: findVersions,
+                idType: 'uuid',
                 init,
                 packageName: '@payloadcms/db-content-api',
                 payload,

package/dist/db-content-api/utilities/data/index.d.ts

@@ -37,6 +37,13 @@ export declare function dataToContentAPI(payload: Payload, collectionSlug: strin
  * Note: Date fields come as ISO strings from Content API and stay as strings
  * (matching MongoDB and other adapters' behavior)
  */
+/**
+ * Extract version content from versionData that may be flat (no nested `version` key).
+ * Some callers spread version content at the top level alongside metadata
+ * (e.g. `{ ...version.version, createdAt }`), so we reconstruct the `version`
+ * object by filtering out known metadata keys.
+ */
+export declare function resolveVersionContent(version: unknown, versionMeta: Record<string, unknown>): unknown;
 export declare function dataFromContentAPI(payload: Payload, collectionSlug: string, data: unknown): unknown;
 export {};
 //# sourceMappingURL=index.d.ts.map

package/dist/db-content-api/utilities/data/index.js

@@ -84,10 +84,16 @@ import { transformToLocalizeStatus } from './transformPublishedLocale.js';
         transformed.id = String(transformed.id);
     }
     // Add timestamps (Content API no longer auto-sets these in DB)
-    // updatedAt is always set, createdAt only on create operations
+    // Preserve existing timestamps when already present (e.g. version data that carries
+    // the parent document's timestamps), otherwise generate new ones.
+    // Explicit null means "don't change" — strip it so the API keeps the existing value.
     const now = new Date().toISOString();
-    transformed.updatedAt = now;
-    if (options?.createdAt) {
+    if (transformed.updatedAt === null) {
+        delete transformed.updatedAt;
+    } else if (transformed.updatedAt === undefined) {
+        transformed.updatedAt = now;
+    }
+    if (options?.createdAt && !transformed.createdAt) {
         transformed.createdAt = now;
     }
     return transformed;
@@ -101,7 +107,24 @@ import { transformToLocalizeStatus } from './transformPublishedLocale.js';
  *
  * Note: Date fields come as ISO strings from Content API and stay as strings
  * (matching MongoDB and other adapters' behavior)
- */ export function dataFromContentAPI(payload, collectionSlug, data) {
+ */ /**
+ * Extract version content from versionData that may be flat (no nested `version` key).
+ * Some callers spread version content at the top level alongside metadata
+ * (e.g. `{ ...version.version, createdAt }`), so we reconstruct the `version`
+ * object by filtering out known metadata keys.
+ */ export function resolveVersionContent(version, versionMeta) {
+    if (version !== undefined) {
+        return version;
+    }
+    const metaKeys = [
+        'createdAt',
+        'updatedAt',
+        'latest',
+        'parent'
+    ];
+    return Object.fromEntries(Object.entries(versionMeta).filter(([key])=>!metaKeys.includes(key)));
+}
+export function dataFromContentAPI(payload, collectionSlug, data) {
     if (!data || typeof data !== 'object') {
         return data;
     }

package/dist/db-content-api/utilities/where.js

@@ -85,7 +85,7 @@ export function convertPayloadWhereToContentAPI(where, options = {}) {
                 conditions.push({
                     operator: 'equals',
                     path: fieldPath,
-                    value
+                    value: fieldPath === 'id' && typeof value === 'number' ? String(value) : value
                 });
                 continue;
             }
@@ -106,6 +106,12 @@ export function convertPayloadWhereToContentAPI(where, options = {}) {
                 if (op === 'exists' && typeof operatorValue === 'string') {
                     finalValue = operatorValue === 'true';
                 }
+                // Content API stores all document IDs as strings.
+                // Payload sends numeric values for collections with custom numeric ID fields,
+                // so we must stringify to match.
+                if (fieldPath === 'id' && typeof finalValue === 'number') {
+                    finalValue = String(finalValue);
+                }
                 conditions.push({
                     operator: op,
                     path: fieldPath,

package/dist/deploy/schedule-extract-plugin.d.ts

@@ -0,0 +1,11 @@
+import type { Config } from 'payload';
+/**
+ * Payload plugin that extracts cron schedule metadata and writes
+ * `.next/static/payload-schedules.json` during `figma deploy` builds.
+ *
+ * Only runs when `FIGMA_EXTRACT_SCHEDULES=true`, which is set exclusively by
+ * the deploy CLI before spawning `next build`. At Lambda runtime and during
+ * local development the env var is absent and this plugin is a no-op.
+ */
+export declare function scheduleExtractPlugin(): (config: Config) => Config;
+//# sourceMappingURL=schedule-extract-plugin.d.ts.map

package/dist/deploy/schedule-extract-plugin.js

@@ -0,0 +1,34 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Payload plugin that extracts cron schedule metadata and writes
+ * `.next/static/payload-schedules.json` during `figma deploy` builds.
+ *
+ * Only runs when `FIGMA_EXTRACT_SCHEDULES=true`, which is set exclusively by
+ * the deploy CLI before spawning `next build`. At Lambda runtime and during
+ * local development the env var is absent and this plugin is a no-op.
+ */ export function scheduleExtractPlugin() {
+    return (config)=>{
+        if (process.env.FIGMA_EXTRACT_SCHEDULES !== 'true') {
+            return config;
+        }
+        const schedules = [
+            ...(config.jobs?.tasks ?? []).flatMap((task)=>(task.schedule ?? []).map((sched)=>({
+                        slug: task.slug,
+                        cron: sched.cron
+                    }))),
+            ...(config.jobs?.workflows ?? []).flatMap((workflow)=>(workflow.schedule ?? []).map((sched)=>({
+                        slug: workflow.slug,
+                        cron: sched.cron
+                    })))
+        ];
+        const outDir = path.join(process.cwd(), '.next', 'static');
+        fs.mkdirSync(outDir, {
+            recursive: true
+        });
+        fs.writeFileSync(path.join(outDir, 'payload-schedules.json'), JSON.stringify(schedules));
+        return config;
+    };
+}
+
+//# sourceMappingURL=schedule-extract-plugin.js.map

package/dist/plugin/build-config.d.ts

@@ -6,9 +6,10 @@ import type { Config, SanitizedConfig } from 'payload';
  * - `db`: Omitted (auto-injected by Figma platform)
  * - `secret`: Omitted (auto-injected by Figma platform)
  * - `editor`: Optional (defaults to lexicalEditor() if not provided)
+ * - `contentSystemId`: Optional (resolved automatically from env vars or bootstrap cache)
  *
  * @example
- * // Minimal config (contentSystemId resolved from bootstrap data)
+ * // Minimal config (contentSystemId resolved automatically)
  * const config: FigmaConfig = {
  *   figma: {},
  *   collections: [...]

package/dist/plugin/build-config.js

@@ -7,6 +7,7 @@ import { getValidAccessToken } from '../auth/oauth-flow.js';
 import { getTokenStore } from '../auth/token-store.js';
 import { getEnvConfig } from '../constants.js';
 import { contentAPIAdapter } from '../db-content-api/index.js';
+import { scheduleExtractPlugin } from '../deploy/schedule-extract-plugin.js';
 import { health } from '../endpoints/health.js';
 import { schema } from '../endpoints/schema.js';
 import { oAuth2Plugin } from '../oauth/index.js';
@@ -63,9 +64,11 @@ function missingOAuthCredential(name) {
 }
 export async function buildFigmaConfig(config) {
     const envConfig = getEnvConfig();
-    // Resolve contentSystemId: config first, then local store fallback (dev)
+    // Resolve contentSystemId: config first, env var, then local store fallback (dev)
     let { contentSystemId } = config.figma;
+    contentSystemId ??= process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID;
     let bootstrapData = null;
+    // Local dev: resolve from project ID + bootstrap cache
     if (!contentSystemId) {
         const projectId = process.env.FIGMA_PROJECT_ID;
         const environmentName = process.env.FIGMA_ENVIRONMENT_NAME;
@@ -218,7 +221,8 @@ export async function buildFigmaConfig(config) {
                 ],
                 debug: !!process.env.DEBUG,
                 disabled: false
-            })
+            }),
+            scheduleExtractPlugin()
         ]
     };
     // Inject figma fields into users collection

package/dist/types.d.ts

@@ -3,15 +3,19 @@ export interface Args extends arg.Spec {
     '--debug': BooleanConstructor;
     '--dry-run': BooleanConstructor;
     '--env': StringConstructor;
+    '--environment': string;
     '--force': BooleanConstructor;
     '--help': BooleanConstructor;
     '--id': StringConstructor;
     '--infra-env': StringConstructor;
     '--list': BooleanConstructor;
     '--logout': BooleanConstructor;
+    '--name': StringConstructor;
     '--yes': BooleanConstructor;
+    '-e': string;
     '-f': string;
     '-h': string;
+    '-n': string;
     '-y': string;
 }
 export type CliArgs = arg.Result<Args>;

package/dist/utils/formatter.js

@@ -1,9 +1,13 @@
 import spawn from 'cross-spawn';
 import path from 'path';
+import * as log from './log.js';
 /**
  * Format file with Prettier
  * Returns warning if formatting fails but does not throw
  */ export async function formatFile(filePath, packageManager) {
+    const cmd = `${packageManager} exec prettier --write ${filePath}`;
+    const cwd = path.dirname(filePath);
+    log.debug(`Running formatter: ${cmd} (cwd: ${cwd})`);
     return new Promise((resolve)=>{
         try {
             const child = spawn(packageManager, [
@@ -12,31 +16,41 @@ import path from 'path';
                 '--write',
                 filePath
             ], {
-                cwd: path.dirname(filePath),
+                cwd,
                 stdio: 'pipe'
             });
+            let stderr = '';
+            child.stderr?.on('data', (data)=>{
+                stderr += data.toString();
+            });
             child.on('close', (code)=>{
                 if (code === 0) {
+                    log.debug('Prettier formatting succeeded');
                     resolve({
                         success: true
                     });
                 } else {
+                    const detail = stderr.trim();
+                    log.debug(`Prettier exited with code ${code}${detail ? `: ${detail}` : ''}`);
                     resolve({
                         success: false,
-                        warning: 'Could not format file with Prettier'
+                        warning: `Could not format file with Prettier (exit code ${code})${detail ? `: ${detail}` : ''}`
                     });
                 }
             });
-            child.on('error', ()=>{
+            child.on('error', (err)=>{
+                log.debug(`Prettier spawn error: ${err.message}`);
                 resolve({
                     success: false,
-                    warning: 'Could not format file with Prettier'
+                    warning: `Could not format file with Prettier: ${err.message}`
                 });
             });
-        } catch  {
+        } catch (err) {
+            const message = err instanceof Error ? err.message : 'Unknown error';
+            log.debug(`Prettier failed to spawn: ${message}`);
             resolve({
                 success: false,
-                warning: 'Could not format file with Prettier'
+                warning: `Could not format file with Prettier: ${message}`
             });
         }
     });

package/dist/utils/messages.d.ts

@@ -6,5 +6,4 @@ export declare function moveMessage(args: {
     nextAppDir: string;
     projectDir: string;
 }): string;
-export declare function feedbackOutro(): string;
 //# sourceMappingURL=messages.d.ts.map

package/dist/utils/messages.js

@@ -36,6 +36,7 @@ export function helpMessage() {
 
       ${pc.cyan('@payloadcms/figma init --id <cms-resource-id>')}     Initialize project
       ${pc.cyan('@payloadcms/figma init --id <id> --env staging')}    Initialize for specific environment
+      ${pc.dim('--name, -n <name>')}                     Set project directory name (skips prompt)
       ${pc.dim('--force')}                               Force reconfiguration of existing project
 
   ${pc.bold('ENV COMMAND')}
@@ -109,8 +110,5 @@ It is recommended to do this from your IDE if your app has existing file referen
 Once moved, rerun the @payloadcms/figma command again.
 `;
 }
-export function feedbackOutro() {
-    return `${pc.bgCyan(pc.black(' Have feedback? '))} Visit us on ${createTerminalLink('GitHub', 'https://github.com/payloadcms/payload')}.`;
-}
 
 //# sourceMappingURL=messages.js.map

package/dist/utils/payload-config-ast.d.ts

@@ -57,11 +57,6 @@ export type FigmaPropertyConfig = {
  * Modifies the AST in memory - caller must call sourceFile.save()
  */
 export declare function addFigmaProperty(sourceFile: SourceFile, config: FigmaPropertyConfig): ASTModificationResult;
-/**
- * Read figma configuration from payload.config.ts
- * Returns the figma object if it exists, null otherwise
- */
-export declare function readFigmaConfig(sourceFile: SourceFile): FigmaPropertyConfig | null;
 /**
  * Remove the contentSystemId property from figma config object.
  * Used during upgrade migration — contentSystemId is now resolved from bootstrap data.

package/dist/utils/payload-config-ast.js

@@ -385,14 +385,9 @@ import * as log from './log.js';
         };
     }
     // Add figma property
-    // Note: useContentSystem is optional and defaults to true, so we don't generate it during init
-    // contentSystemId is stored in .env file and referenced via process.env with non-null assertion
-    const figmaObj = config.useContentSystem === false ? `{
-    contentSystemId: process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID!,
-    useContentSystem: false,
-  }` : `{
-    contentSystemId: process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID!,
-  }`;
+    // contentSystemId is resolved automatically by buildFigmaConfig from env vars or bootstrap cache.
+    // useContentSystem defaults to true, so we only generate it when explicitly false.
+    const figmaObj = config.useContentSystem === false ? `{\nuseContentSystem: false,\n}` : '{}';
     configArg.addPropertyAssignment({
         name: 'figma',
         initializer: figmaObj
@@ -404,74 +399,6 @@ import * as log from './log.js';
         modified
     };
 }
-/**
- * Read figma configuration from payload.config.ts
- * Returns the figma object if it exists, null otherwise
- */ export function readFigmaConfig(sourceFile) {
-    // Find buildFigmaConfig call (this function is only used with Figma configs)
-    const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
-    const buildConfigCall = callExpressions.find((ce)=>{
-        const expr = ce.getExpression();
-        const text = expr.getText();
-        return text === 'buildFigmaConfig' || text.endsWith('.buildFigmaConfig');
-    });
-    if (!buildConfigCall) {
-        log.debug('No buildFigmaConfig call found');
-        return null;
-    }
-    // Get config object argument
-    const configArg = buildConfigCall.getArguments()[0];
-    if (!configArg || !Node.isObjectLiteralExpression(configArg)) {
-        log.debug('buildConfig argument is not an object literal');
-        return null;
-    }
-    // Find figma property
-    const figmaProperty = configArg.getProperty('figma');
-    if (!figmaProperty || !Node.isPropertyAssignment(figmaProperty)) {
-        log.debug('No figma property found in buildConfig');
-        return null;
-    }
-    // Get initializer (the object value)
-    const initializer = figmaProperty.getInitializer();
-    if (!initializer || !Node.isObjectLiteralExpression(initializer)) {
-        log.debug('figma property is not an object literal');
-        return null;
-    }
-    // Extract values
-    const contentSystemIdProp = initializer.getProperty('contentSystemId');
-    const useContentSystemProp = initializer.getProperty('useContentSystem');
-    if (!contentSystemIdProp) {
-        log.debug('Missing required figma property: contentSystemId');
-        return null;
-    }
-    // Extract contentSystemId - support both literal strings and env var references
-    let contentSystemId;
-    if (Node.isPropertyAssignment(contentSystemIdProp)) {
-        const initializer = contentSystemIdProp.getInitializer();
-        const text = initializer?.getText() || '';
-        // Support both patterns:
-        // 1. Literal string: 'cms_abc123' or "cms_abc123"
-        // 2. Environment variable: process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID
-        if (text.includes('process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID')) {
-            // For env var reference, return a marker that indicates it's from env
-            // The actual value will be read at runtime
-            contentSystemId = 'process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID';
-        } else {
-            // Remove quotes for literal strings
-            contentSystemId = text.replace(/['"]/g, '');
-        }
-    }
-    const useContentSystem = Node.isPropertyAssignment(useContentSystemProp) ? useContentSystemProp.getInitializer()?.getText() === 'true' : undefined // Optional: undefined if not specified
-    ;
-    if (!contentSystemId) {
-        log.debug('Could not extract contentSystemId value');
-        return null;
-    }
-    return {
-        contentSystemId,
-        useContentSystem
-    };
-}
 /**
  * Remove the contentSystemId property from figma config object.
  * Used during upgrade migration — contentSystemId is now resolved from bootstrap data.
@@ -504,6 +431,10 @@ import * as log from './log.js';
         return false;
     }
     contentSystemIdProp.remove();
+    // Collapse empty object to avoid ts-morph whitespace artifacts
+    if (initializer.getProperties().length === 0) {
+        initializer.replaceWithText('{}');
+    }
     return true;
 }
 

package/dist/utils/payload-config-modifier.js

@@ -1,5 +1,5 @@
 import pc from 'picocolors';
-import { Project } from 'ts-morph';
+import { IndentationText, Project } from 'ts-morph';
 import { formatFile } from './formatter.js';
 import * as log from './log.js';
 import { getAddCommand, getRunCommand } from './package-manager.js';
@@ -57,6 +57,10 @@ import { getOwnVersion } from './version-check.js';
         // 3. Parse config with ts-morph
         log.debug('Parsing config file with ts-morph...');
         const project = new Project({
+            manipulationSettings: {
+                indentationText: IndentationText.TwoSpaces,
+                useTrailingCommas: true
+            },
             skipAddingFilesFromTsConfig: true
         });
         const sourceFile = project.addSourceFileAtPath(configPath);
@@ -107,6 +111,10 @@ import { getOwnVersion } from './version-check.js';
         }
         // Save file if any modifications were made
         if (modified) {
+            sourceFile.formatText({
+                indentSize: 2,
+                tabSize: 2
+            });
             await sourceFile.save();
             log.debug('Config file saved');
             // 7. Handle package management

package/dist/utils/resolve-environment.d.ts

@@ -2,7 +2,7 @@ import type { BootstrapEnvironment } from '../api/control-plane.js';
 /**
  * Resolve which environment to use from the bootstrap response.
  *
- * - Single environment: auto-select (environmentName optional)
+ * - Single environment: auto-select (environmentName optional, validated if provided)
  * - Multiple environments: environmentName required, must match
  *
  * @throws Error if resolution fails (with available environment names)

package/dist/utils/resolve-environment.js

@@ -1,7 +1,7 @@
 /**
  * Resolve which environment to use from the bootstrap response.
  *
- * - Single environment: auto-select (environmentName optional)
+ * - Single environment: auto-select (environmentName optional, validated if provided)
  * - Multiple environments: environmentName required, must match
  *
  * @throws Error if resolution fails (with available environment names)
@@ -11,6 +11,9 @@
         throw new Error('No environments found for this project.');
     }
     if (environments.length === 1) {
+        if (environmentName && environments[0].name !== environmentName) {
+            throw new Error(`Environment "${environmentName}" not found. Available: ${environments[0].name}`);
+        }
         return environments[0];
     }
     // Multiple environments — name required

package/package.json

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