@payloadcms/figma 0.0.1-alpha.62 → 0.0.1-alpha.63

package/dist/commands/debug.js

@@ -36,14 +36,14 @@ function appendSystemSection(lines, env) {
     lines.push('');
 }
 function appendAuthSection(lines, tokenStore, cwd) {
-    const tokens = tokenStore.getTokens();
+    const tokens = tokenStore.getOauthInfo();
     lines.push('Auth:');
     if (!tokens) {
         lines.push('  Status:           Not authenticated');
         lines.push('');
         return;
     }
-    const isValid = tokenStore.hasValidTokens();
+    const isValid = tokenStore.hasValidOauthToken();
     lines.push(`  Status:           ${isValid ? 'Authenticated' : 'Token expired'}`);
     const email = getEmailFromClaims(tokenStore, cwd);
     if (email) {
@@ -62,7 +62,7 @@ function appendTokenStoreDiagnostics(lines, tokenStore) {
     lines.push(`  File:             ${filePath}`);
     lines.push(`  File Exists:      ${fileExists}`);
     lines.push(`  File Size:        ${fileSize}B`);
-    const canRead = tokenStore.getTokens() !== null || tokenStore.getRefreshToken() !== null;
+    const canRead = tokenStore.getOauthInfo() !== null || tokenStore.getCurrentRefreshToken() !== null;
     lines.push(`  Decryption:       ${fileExists ? canRead || fileSize === 0 ? 'OK' : 'FAILED' : 'N/A'}`);
     lines.push(`  Key Hash:         ${getEncryptionKeyHash()}`);
     lines.push('');
@@ -85,7 +85,12 @@ function appendProjectSection(lines, tokenStore, cwd) {
             lines.push(`  Content System ID:  ${bootstrapData.contentSystemId}`);
             lines.push(`  Tenant Instance ID: ${bootstrapData.tenantInstanceId}`);
             lines.push(`  OAuth Client ID:    ${maskToken(bootstrapData.oauthClientId)}`);
-            const projectToken = tokenStore.getProjectToken(bootstrapData.contentSystemId);
+            const projectToken = tokenStore.getProjectToken({
+                projectInfo: {
+                    environmentName,
+                    projectId
+                }
+            });
             if (projectToken) {
                 lines.push(`  Project Token:      ${formatExpiryTime(projectToken.expiresAt)}`);
             }
@@ -103,25 +108,24 @@ async function appendPackagesSection(lines) {
     lines.push(`  payload:            ${payloadVersion}`);
 }
 /**
- * Try resolving email from bootstrap data, then iterate all stored project tokens.
+ * Resolve email from the current project + environment scoped token when available.
  */ function getEmailFromClaims(tokenStore, cwd) {
     const projectId = getEnvVarSync(cwd, 'FIGMA_PROJECT_ID');
     const environmentName = getEnvVarSync(cwd, 'FIGMA_ENVIRONMENT_NAME');
     if (projectId && environmentName) {
         const bootstrapData = tokenStore.getBootstrapData(projectId, environmentName);
         if (bootstrapData) {
-            const email = tokenStore.getProjectTokenClaims(bootstrapData.contentSystemId)?.email;
+            const email = tokenStore.getProjectToken({
+                projectInfo: {
+                    environmentName,
+                    projectId
+                }
+            })?.claims?.email;
             if (email) {
                 return email;
             }
         }
     }
-    for (const id of tokenStore.getAllProjectTokenTenantIds()){
-        const email = tokenStore.getProjectTokenClaims(id)?.email;
-        if (email) {
-            return email;
-        }
-    }
     return null;
 }
 function getPayloadVersion() {

package/dist/commands/dump-tokens.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Handle the `@payloadcms/figma dump-tokens` command
+ *
+ * Exports decrypted versions of encrypted token store files in
+ * `oauth/` and `projects/` subdirectories (new structure) plus any legacy
+ * per-env directories from older package versions. Creates
+ * `.decrypted.json` files next to each encrypted `.json` file.
+ *
+ * Skips the `payloadcms-figma-crypto.json` salt file at the root.
+ */
+export declare function dumpTokensCommand(): Promise<void>;
+//# sourceMappingURL=dump-tokens.d.ts.map

package/dist/commands/dump-tokens.js

@@ -0,0 +1,69 @@
+import * as p from '@clack/prompts';
+import envPaths from 'env-paths';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { deriveEncryptionKey, exportDecryptedStoreFiles } from '../auth/crypto-utils.js';
+/**
+ * Handle the `@payloadcms/figma dump-tokens` command
+ *
+ * Exports decrypted versions of encrypted token store files in
+ * `oauth/` and `projects/` subdirectories (new structure) plus any legacy
+ * per-env directories from older package versions. Creates
+ * `.decrypted.json` files next to each encrypted `.json` file.
+ *
+ * Skips the `payloadcms-figma-crypto.json` salt file at the root.
+ */ export async function dumpTokensCommand() {
+    const encryptionKey = deriveEncryptionKey();
+    const newRoot = envPaths('payloadcms-figma').config;
+    const stagingLegacyRoot = envPaths('payloadcms-figma-staging').config;
+    const candidateDirs = [
+        path.join(newRoot, 'oauth'),
+        path.join(newRoot, 'projects'),
+        stagingLegacyRoot
+    ];
+    const targetDirs = Array.from(new Set(candidateDirs)).filter((dir)=>fsSync.existsSync(dir));
+    if (targetDirs.length === 0) {
+        // eslint-disable-next-line no-console
+        console.log('No token store directories found.');
+        return;
+    }
+    // eslint-disable-next-line no-console
+    console.log(pc.yellow('⚠  dump-tokens writes DECRYPTED token files to disk.'));
+    // eslint-disable-next-line no-console
+    console.log('Target directories:');
+    for (const dir of targetDirs){
+        // eslint-disable-next-line no-console
+        console.log(`  ${dir}`);
+    }
+    // eslint-disable-next-line no-console
+    console.log('');
+    const confirmed = await p.confirm({
+        initialValue: false,
+        message: 'Continue? Remember to delete the decrypted files after use.'
+    });
+    if (p.isCancel(confirmed) || !confirmed) {
+        // eslint-disable-next-line no-console
+        console.log('Cancelled.');
+        return;
+    }
+    const decryptedFiles = [];
+    for (const dir of targetDirs){
+        decryptedFiles.push(...exportDecryptedStoreFiles(dir, encryptionKey));
+    }
+    if (decryptedFiles.length === 0) {
+        // eslint-disable-next-line no-console
+        console.log('No encrypted files could be decrypted with the current machine key.');
+        return;
+    }
+    // eslint-disable-next-line no-console
+    console.log(`\nCreated ${decryptedFiles.length} decrypted file(s):`);
+    for (const file of decryptedFiles){
+        // eslint-disable-next-line no-console
+        console.log(`  ${file}`);
+    }
+    // eslint-disable-next-line no-console
+    console.log('\nNote: These files contain sensitive tokens. Delete after use.');
+}
+
+//# sourceMappingURL=dump-tokens.js.map

package/dist/commands/init.js

@@ -29,12 +29,16 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
  * @param tokenStore - Token store instance
  * @param contentSystemId - Content System ID to generate token for
  * @param spinner - Clack spinner instance for status updates (only used in debug mode)
- */ async function generateProjectTokenWithFeedback(tokenStore, contentSystemId, spinner) {
+ */ async function generateProjectTokenWithFeedback(tokenStore, contentSystemId, spinner, projectInfo) {
     if (isDebug()) {
         spinner.start('Generating project token...');
     }
     try {
-        const projectToken = await getValidProjectToken(tokenStore, contentSystemId);
+        const projectToken = await getValidProjectToken({
+            projectInfo,
+            tenantId: contentSystemId,
+            tokenStore
+        });
         if (isDebug()) {
             if (projectToken) {
                 spinner.stop(pc.green('✓ Project token generated'));
@@ -78,7 +82,7 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
         p.log.warn(pc.yellow('Skipping authentication (--skip-auth mode)'));
     } else {
         // Check for valid cached tokens first (no API call needed)
-        if (!tokenStore.hasValidTokens()) {
+        if (!tokenStore.hasValidOauthToken()) {
             // Need to refresh or authenticate - show spinner for API call
             s.start('Checking authentication...');
             const credential = await tryGetCredential(tokenStore);

package/dist/commands/list-tokens.js

@@ -26,13 +26,13 @@ const ALL_ENVIRONMENTS = [
 }
 function showTokenDetails(env) {
     const tokenStore = getTokenStore(env);
-    const tokens = tokenStore.getTokens();
+    const tokens = tokenStore.getOauthInfo();
     if (!tokens) {
         p.log.warn(pc.yellow(`No tokens found${formatEnvSuffix(env, ' for ')}. Not authenticated.`));
         p.note(`Run ${pc.cyan('@payloadcms/figma login')} to authenticate`, 'Tip');
         return;
     }
-    const isValid = tokenStore.hasValidTokens();
+    const isValid = tokenStore.hasValidOauthToken();
     const status = isValid ? pc.green('✓ Valid') : pc.red('✗ Expired');
     p.log.step(pc.bold(`Token Status${formatEnvSuffix(env, ' (', ')')}`));
     // Build OAuth token info display

package/dist/commands/login.js

@@ -22,7 +22,7 @@ import * as log from '../utils/log.js';
     try {
         const existingCredential = await getValidCredential(tokenStore);
         if (existingCredential) {
-            const tokens = tokenStore.getTokens();
+            const tokens = tokenStore.getOauthInfo();
             p.log.warn(pc.yellow(`Already logged in${formatEnvSuffix(env)}`));
             if (tokens?.userId) {
                 log.info(`User ID: ${tokens.userId}`);

package/dist/commands/logout.js

@@ -2,6 +2,7 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { getTokenStore } from '../auth/token-store.js';
 import { getInfraEnvironment } from '../constants.js';
+import { getEnvVarSync } from '../utils/env-management.js';
 import { formatEnvSuffix } from '../utils/format-env-suffix.js';
 import * as log from '../utils/log.js';
 const ALL_ENVIRONMENTS = [
@@ -23,7 +24,7 @@ const ALL_ENVIRONMENTS = [
 }
 async function logoutSingleEnvironment(env) {
     const tokenStore = getTokenStore(env);
-    const hasTokens = tokenStore.getTokens() !== null;
+    const hasTokens = tokenStore.getOauthInfo() !== null;
     if (!hasTokens) {
         p.log.warn(pc.yellow(`No tokens found${formatEnvSuffix(env, ' for ')}. Already logged out.`));
         return;
@@ -40,7 +41,7 @@ async function logoutSingleEnvironment(env) {
     s.start('Clearing tokens...');
     try {
         tokenStore.clearTokens();
-        tokenStore.clearAllProjectTokens();
+        clearCurrentProjectToken(tokenStore, env);
         s.stop(pc.green(`✓ Logged out${formatEnvSuffix(env, ' from ')}`));
     } catch (error) {
         s.stop(pc.red('✗ Failed to clear tokens'));
@@ -52,7 +53,7 @@ async function logoutAllEnvironments() {
     // Check which environments have tokens
     const envsWithTokens = ALL_ENVIRONMENTS.filter((env)=>{
         const store = getTokenStore(env);
-        return store.getTokens() !== null;
+        return store.getOauthInfo() !== null;
     });
     if (envsWithTokens.length === 0) {
         p.log.warn(pc.yellow('No tokens found in any environment. Already logged out.'));
@@ -73,7 +74,7 @@ async function logoutAllEnvironments() {
         for (const env of envsWithTokens){
             const store = getTokenStore(env);
             store.clearTokens();
-            store.clearAllProjectTokens();
+            clearCurrentProjectToken(store, env);
         }
         s.stop(pc.green('✓ Logged out from all environments'));
     } catch (error) {
@@ -82,5 +83,23 @@ async function logoutAllEnvironments() {
         process.exit(1);
     }
 }
+function clearCurrentProjectToken(store, env) {
+    const projectId = getEnvVarSync(process.cwd(), 'FIGMA_PROJECT_ID');
+    if (!projectId) {
+        return;
+    }
+    const bootstrapData = store.getBootstrapData(projectId, env);
+    if (!bootstrapData?.contentSystemId) {
+        return;
+    }
+    const projectInfo = {
+        environmentName: env,
+        projectId
+    };
+    // Clear scoped token for this tenant.
+    store.clearProjectToken({
+        projectInfo
+    });
+}
 
 //# sourceMappingURL=logout.js.map

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

@@ -25,7 +25,10 @@ export function createAuthMiddleware(opts) {
             if (opts.auth.mode === 'apiKey') {
                 request.headers.set('X-Api-Key', opts.auth.apiKey);
             } else if (opts.auth.mode === 'tokenStore') {
-                const token = await getValidProjectToken(opts.auth.tokenStore, opts.contentSystemId);
+                const token = await getValidProjectToken({
+                    tenantId: opts.contentSystemId,
+                    tokenStore: opts.auth.tokenStore
+                });
                 if (!token) {
                     throw new Error('Authentication required. Run `npx @payloadcms/figma login` to authenticate.');
                 }

package/dist/oauth/defaults.d.ts

@@ -1,10 +1,12 @@
 import type { CollectionConfig, EmailField, TextField } from 'payload';
 import type { VerifyFunction } from './types.js';
+export declare const DEFAULT_USER_INFO_COOKIE_NAME = "figma-user-info";
 export declare const defaultScope: string[];
 export declare const defaultUsernameField: TextField;
-export declare const defaultVerify: ({ collection, strategyName, usernameField, }: {
+export declare const defaultVerify: ({ collection, strategyName, userInfoCookieName, usernameField, }: {
     collection: CollectionConfig;
     strategyName: string;
+    userInfoCookieName?: string;
     usernameField: EmailField | TextField;
 }) => VerifyFunction;
 //# sourceMappingURL=defaults.d.ts.map

package/dist/oauth/defaults.js

@@ -2,10 +2,11 @@ import { parseCookies } from 'payload';
 import { v4 as uuid } from 'uuid';
 import { hasUserTokenPropsChanged } from './utilities/hasUserTokenPropsChanged.js';
 import { isDuplicateKeyError } from './utilities/isDuplicateKeyError.js';
-function getFigmaUserInfo(headers) {
+export const DEFAULT_USER_INFO_COOKIE_NAME = 'figma-user-info';
+function getFigmaUserInfo(headers, cookieName) {
     try {
         const cookies = parseCookies(headers);
-        const encoded = cookies.get('figma-user-info');
+        const encoded = cookies.get(cookieName);
         if (!encoded) {
             return null;
         }
@@ -28,7 +29,7 @@ export const defaultUsernameField = {
     },
     unique: true
 };
-export const defaultVerify = ({ collection, strategyName, usernameField })=>async ({ headers, payload, token })=>{
+export const defaultVerify = ({ collection, strategyName, userInfoCookieName = DEFAULT_USER_INFO_COOKIE_NAME, usernameField })=>async ({ headers, payload, token })=>{
         let tokenUsername = 'preferred_username';
         if (usernameField.name !== 'preferredUsername') {
             tokenUsername = usernameField.name;
@@ -38,12 +39,12 @@ export const defaultVerify = ({ collection, strategyName, usernameField })=>asyn
                 user: null
             };
         }
-        const figmaUserInfo = getFigmaUserInfo(headers);
+        const figmaUserInfo = getFigmaUserInfo(headers, userInfoCookieName);
         let responseHeaders;
         // Clear the cookie after reading
         if (figmaUserInfo) {
             responseHeaders = new Headers();
-            responseHeaders.append('Set-Cookie', 'figma-user-info=; Max-Age=0; Path=/;');
+            responseHeaders.append('Set-Cookie', `${userInfoCookieName}=; Max-Age=0; Path=/;`);
         }
         let user = null;
         const depth = typeof collection.auth === 'object' ? collection.auth.depth : undefined;

package/dist/oauth/endpoints/getLoginEndpoint.js

@@ -262,7 +262,7 @@ export const getLoginEndpoint = ({ collection, collectionOptions, endpointSlug,
                     })).toString('base64');
                     const userInfoCookie = generateCookie({
                         ...cookieOptions,
-                        name: 'figma-user-info',
+                        name: pluginOptions?.userInfoCookieName ?? 'figma-user-info',
                         expires: new Date(Date.now() + 60_000),
                         returnCookieAsObject: false,
                         value: userInfoValue

package/dist/oauth/index.js

@@ -144,6 +144,7 @@ export const oAuth2Plugin = (pluginOptions)=>(config)=>{
                     verify: collectionOptions.verify ?? defaultVerify({
                         collection: existingCollection,
                         strategyName,
+                        userInfoCookieName: pluginOptions?.userInfoCookieName,
                         usernameField
                     })
                 });

package/dist/oauth/types.d.ts

@@ -148,6 +148,16 @@ export interface PluginOptions {
      * @default 'oauth'
      */
     strategyName?: string;
+    /**
+     * The name of the short-lived cookie used to carry Figma user profile
+     * info from the login endpoint to `defaultVerify`.
+     *
+     * Override in local dev when running multiple Payload apps on localhost
+     * to avoid cookie collisions (all localhost apps share a cookie jar).
+     *
+     * @default 'figma-user-info'
+     */
+    userInfoCookieName?: string;
 }
 export type CookieOptions = {
     domain?: string;

package/dist/plugin/auth-preflight.d.ts

@@ -0,0 +1,8 @@
+import type { TokenStore } from '../auth/token-store.js';
+/**
+ * Print a one-shot banner when the plugin is about to use `tokenStore`
+ * auth but no valid OAuth credential is present. Keeps the dev loop
+ * actionable instead of relying on per-request middleware errors.
+ */
+export declare function logMissingCliAuth(tokenStore: TokenStore): void;
+//# sourceMappingURL=auth-preflight.d.ts.map

package/dist/plugin/auth-preflight.js

@@ -0,0 +1,20 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+/**
+ * Print a one-shot banner when the plugin is about to use `tokenStore`
+ * auth but no valid OAuth credential is present. Keeps the dev loop
+ * actionable instead of relying on per-request middleware errors.
+ */ export function logMissingCliAuth(tokenStore) {
+    if (tokenStore.hasValidOauthToken()) {
+        return;
+    }
+    const lines = [
+        'Not logged in to the Figma CLI.',
+        'Content API requests will fail until you authenticate.',
+        '',
+        `Run ${pc.cyan('npx @payloadcms/figma login')} to log in, then restart the dev server.`
+    ];
+    p.note(lines.join('\n'), pc.yellow('Figma authentication required'));
+}
+
+//# sourceMappingURL=auth-preflight.js.map

package/dist/plugin/bootstrap-preflight.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reason the Content System ID could not be resolved. Drives the
+ * banner's copy so the dev sees the specific remediation step.
+ */
+export type MissingContentSystemIdReason = {
+    environmentName: string;
+    kind: 'environment-not-found';
+    projectId: string;
+} | {
+    kind: 'network';
+    message: string;
+} | {
+    kind: 'no-config';
+} | {
+    kind: 'unauthenticated';
+};
+/**
+ * Print a banner explaining why Content System ID resolution failed and
+ * what to run next. Called just before `buildFigmaConfig` throws, so the
+ * actionable step is visible above the stack trace.
+ */
+export declare function logMissingContentSystemId(reason: MissingContentSystemIdReason): void;
+//# sourceMappingURL=bootstrap-preflight.d.ts.map

package/dist/plugin/bootstrap-preflight.js

@@ -0,0 +1,45 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+/**
+ * Print a banner explaining why Content System ID resolution failed and
+ * what to run next. Called just before `buildFigmaConfig` throws, so the
+ * actionable step is visible above the stack trace.
+ */ export function logMissingContentSystemId(reason) {
+    const lines = buildBody(reason);
+    p.note(lines.join('\n'), pc.yellow('Figma project not configured'));
+}
+function buildBody(reason) {
+    const loginCmd = pc.cyan('npx @payloadcms/figma login');
+    const initCmd = pc.cyan('npx @payloadcms/figma init');
+    const initForceCmd = pc.cyan('npx @payloadcms/figma init --force');
+    if (reason.kind === 'no-config') {
+        return [
+            'No Figma project configuration found.',
+            '',
+            `Run ${initCmd} to set up this project.`
+        ];
+    }
+    if (reason.kind === 'unauthenticated') {
+        return [
+            'Project config found, but you are not logged in.',
+            'Cannot fetch bootstrap data without a valid session.',
+            '',
+            `Run ${loginCmd}, then restart the dev server.`
+        ];
+    }
+    if (reason.kind === 'network') {
+        return [
+            'Could not reach the Figma API to fetch bootstrap data.',
+            `Error: ${reason.message}`,
+            '',
+            'Check your network, then restart the dev server.'
+        ];
+    }
+    return [
+        `Environment ${pc.bold(reason.environmentName)} not found for project ${pc.bold(reason.projectId)}.`,
+        '',
+        `Run ${initForceCmd} to reconfigure, or set FIGMA_ENVIRONMENT_NAME to a valid environment.`
+    ];
+}
+
+//# sourceMappingURL=bootstrap-preflight.js.map

package/dist/plugin/build-config.js

@@ -15,7 +15,11 @@ import { createStorageClient } from '../storage-content-api/client.js';
 import { getGenerateSignedURLHandler } from '../storage-content-api/client-uploads/generateSignedURL.js';
 import { contentApiStorageAdapter } from '../storage-content-api/index.js';
 import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
+import { getEnvVarSync } from '../utils/env-management.js';
 import * as log from '../utils/log.js';
+import { logMissingCliAuth } from './auth-preflight.js';
+import { logMissingContentSystemId } from './bootstrap-preflight.js';
+import { getDevCookieNames } from './dev-cookie-names.js';
 /**
  * Fields added to users collection for Figma profile info
  */ const figmaUserFields = [
@@ -47,20 +51,58 @@ function missingOAuthCredential(name) {
 }
 /**
  * Fetch bootstrap data from the API and cache all environments locally.
- * Returns the requested environment's data, or null if resolution fails.
+ * Returns the requested environment's data, or a typed failure reason.
  */ async function resolveAndCacheBootstrap(store, projectId, environmentName) {
+    let credential;
+    try {
+        credential = await getValidCredential(store);
+    } catch (error) {
+        return {
+            ok: false,
+            reason: {
+                kind: 'network',
+                message: messageOf(error)
+            }
+        };
+    }
+    if (!credential) {
+        return {
+            ok: false,
+            reason: {
+                kind: 'unauthenticated'
+            }
+        };
+    }
     try {
-        const credential = await getValidCredential(store);
-        if (!credential) {
-            return null;
-        }
         const bootstrapInfo = await getBootstrapInfo(credential, projectId);
         cacheAllEnvironments(store, projectId, bootstrapInfo);
-        return store.getBootstrapData(projectId, environmentName);
     } catch (error) {
-        log.warning(`Failed to resolve bootstrap data: ${error instanceof Error ? error.message : 'Unknown error'}. ` + 'Try running `npx @payloadcms/figma login` to refresh authentication.');
-        return null;
+        return {
+            ok: false,
+            reason: {
+                kind: 'network',
+                message: messageOf(error)
+            }
+        };
     }
+    const data = store.getBootstrapData(projectId, environmentName);
+    if (!data) {
+        return {
+            ok: false,
+            reason: {
+                environmentName,
+                kind: 'environment-not-found',
+                projectId
+            }
+        };
+    }
+    return {
+        data,
+        ok: true
+    };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : 'Unknown error';
 }
 export async function buildFigmaConfig(config) {
     const envConfig = getEnvConfig();
@@ -68,16 +110,27 @@ export async function buildFigmaConfig(config) {
     let { contentSystemId } = config.figma;
     contentSystemId ??= process.env.FIGMA_CONTENT_API_CONTENT_SYSTEM_ID;
     let bootstrapData = null;
+    let bootstrapReason = null;
     // Local dev: resolve from project ID + bootstrap cache
+    // Use getEnvVarSync fallback because Next.js evaluates config before dotenv populates process.env
     if (!contentSystemId) {
-        const projectId = process.env.FIGMA_PROJECT_ID;
-        const environmentName = process.env.FIGMA_ENVIRONMENT_NAME;
-        if (projectId && environmentName) {
+        const projectId = process.env.FIGMA_PROJECT_ID ?? getEnvVarSync(process.cwd(), 'FIGMA_PROJECT_ID');
+        const environmentName = process.env.FIGMA_ENVIRONMENT_NAME ?? getEnvVarSync(process.cwd(), 'FIGMA_ENVIRONMENT_NAME');
+        if (!projectId || !environmentName) {
+            bootstrapReason = {
+                kind: 'no-config'
+            };
+        } else {
             const store = getTokenStore();
             bootstrapData = store.getBootstrapData(projectId, environmentName);
             // Runtime fallback: fetch from API if not cached (e.g. environment switch without re-init)
             if (!bootstrapData) {
-                bootstrapData = await resolveAndCacheBootstrap(store, projectId, environmentName);
+                const resolution = await resolveAndCacheBootstrap(store, projectId, environmentName);
+                if (resolution.ok) {
+                    bootstrapData = resolution.data;
+                } else {
+                    bootstrapReason = resolution.reason;
+                }
             }
             if (bootstrapData) {
                 contentSystemId = bootstrapData.contentSystemId;
@@ -85,10 +138,17 @@ export async function buildFigmaConfig(config) {
         }
     }
     if (!contentSystemId) {
+        logMissingContentSystemId(bootstrapReason ?? {
+            kind: 'no-config'
+        });
         throw new Error('Content System ID could not be resolved. ' + 'Run `npx @payloadcms/figma init` to set up your project.');
     }
     const url = process.env.FIGMA_CONTENT_API_URL || envConfig.contentApiUrl;
     const isProduction = process.env.NODE_ENV === 'production';
+    const usesTokenStoreAuth = !process.env.FIGMA_CONTENT_API_ACCESS_KEY && process.env.FIGMA_DEV_JWT !== 'true';
+    if (usesTokenStoreAuth) {
+        logMissingCliAuth(getTokenStore());
+    }
     // Determine database adapter based on environment
     let db;
     if (config.figma.useContentSystem === false) {
@@ -219,6 +279,7 @@ export async function buildFigmaConfig(config) {
                         usernameField: 'email'
                     }
                 ],
+                ...isProduction ? {} : getDevCookieNames(contentSystemId),
                 debug: !!process.env.DEBUG,
                 disabled: false
             }),

package/dist/plugin/dev-cookie-names.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Namespace OAuth cookies per-app in local dev so multiple Payload apps
+ * running on localhost (shared cookie jar across ports) don't clobber each
+ * other's sessions on logout. Uses projectId so the cookie stays stable when
+ * switching environments in the same checkout; falls back to contentSystemId
+ * when projectId isn't in `.env`.
+ *
+ * In production, cookies are isolated by unique hostnames and this is unused.
+ */
+export declare function getDevCookieNames(contentSystemId: string): {
+    cookieName: string;
+    userInfoCookieName: string;
+};
+//# sourceMappingURL=dev-cookie-names.d.ts.map

package/dist/plugin/dev-cookie-names.js

@@ -0,0 +1,19 @@
+import { getEnvVarSync } from '../utils/env-management.js';
+/**
+ * Namespace OAuth cookies per-app in local dev so multiple Payload apps
+ * running on localhost (shared cookie jar across ports) don't clobber each
+ * other's sessions on logout. Uses projectId so the cookie stays stable when
+ * switching environments in the same checkout; falls back to contentSystemId
+ * when projectId isn't in `.env`.
+ *
+ * In production, cookies are isolated by unique hostnames and this is unused.
+ */ export function getDevCookieNames(contentSystemId) {
+    const projectId = process.env.FIGMA_PROJECT_ID ?? getEnvVarSync(process.cwd(), 'FIGMA_PROJECT_ID') ?? contentSystemId;
+    const suffix = projectId.slice(0, 8);
+    return {
+        cookieName: `figma-${suffix}-oauth-token`,
+        userInfoCookieName: `figma-${suffix}-user-info`
+    };
+}
+
+//# sourceMappingURL=dev-cookie-names.js.map