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

package/dist/auth/token-store-migration.js

@@ -131,7 +131,7 @@ function safeGet(config, key) {
     try {
         return config.get(key);
     } catch (error) {
-        log.warning(`Migration read failed (key: ${String(key)}). ` + `File: ${config.path}. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
+        log.debug(`Migration read failed (key: ${String(key)}). ` + `File: ${config.path}. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
         return undefined;
     }
 }
@@ -148,7 +148,7 @@ function safeGet(config, key) {
             projectName: params.projectName
         });
     } catch (error) {
-        log.warning(`Legacy token store could not be opened; skipping migration and leaving file intact. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
+        log.debug(`Legacy token store could not be opened; skipping migration and leaving file intact. ` + `Error: ${error instanceof Error ? error.message : 'Unknown'}`);
         return null;
     }
 }

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

@@ -12,6 +12,7 @@ export declare function getTokenStore(environment?: Environment): TokenStore;
  */
 export declare class TokenStore {
     private baseConfigName;
+    private deriveLegacyKey;
     private encryptionKey;
     private environment;
     private legacyRootDir;
@@ -69,6 +70,7 @@ export declare class TokenStore {
     private getLegacyRootDir;
     private getProjectStore;
     private createConfig;
+    private tryMigrateLegacyKey;
     private safeGet;
 }
 //# sourceMappingURL=token-store.d.ts.map

package/dist/auth/token-store.js

@@ -6,7 +6,7 @@ import { TOKEN_EXPIRY_BUFFER_SECONDS } from '../config/oauth.js';
 import { getInfraEnvironment } from '../constants.js';
 import { getEnvVarSync } from '../utils/env-management.js';
 import * as log from '../utils/log.js';
-import { deriveEncryptionKey } from './crypto-utils.js';
+import { deriveEncryptionKey, deriveLegacyEncryptionKey } from './crypto-utils.js';
 import { migrateOAuth, migrateProjectData, needsMigration } from './token-store-migration.js';
 /**
  * Environment-keyed instances for singleton pattern.
@@ -30,6 +30,7 @@ const PROJECT_STORE_SCHEMA_VERSION = 1;
  * The constructor is still exported for test isolation.
  */ export class TokenStore {
     baseConfigName;
+    deriveLegacyKey;
     encryptionKey;
     environment;
     legacyRootDir;
@@ -45,13 +46,14 @@ const PROJECT_STORE_SCHEMA_VERSION = 1;
         const encryptionKey = options?.encryptionKey ?? deriveEncryptionKey();
         const baseConfigName = options?.configName || projectName;
         this.baseConfigName = baseConfigName;
+        this.deriveLegacyKey = options?.deriveLegacyKey ?? deriveLegacyEncryptionKey;
         this.encryptionKey = encryptionKey;
         this.environment = environment;
         this.projectName = projectName;
         // Resolve the legacy root dir (matching Conf's env-paths convention)
         // without instantiating Conf, which would read/parse the encrypted file
         // and could wipe it under clearInvalidConfig.
-        this.legacyRootDir = envPaths(projectName).config;
+        this.legacyRootDir = options?.rootDir ?? envPaths(projectName).config;
         const legacyFilePath = path.join(this.legacyRootDir, `${baseConfigName}.json`);
         const newOAuthCwd = this.buildOAuthStoreCwd();
         const newOAuthFilePath = path.join(newOAuthCwd, `${this.buildOAuthConfigName()}.json`);
@@ -84,7 +86,7 @@ const PROJECT_STORE_SCHEMA_VERSION = 1;
         if (environment !== 'production') {
             const oldEnvProjectName = `payloadcms-figma-${environment}`;
             const oldEnvConfigName = options?.configName || oldEnvProjectName;
-            const oldEnvLegacyDir = envPaths(oldEnvProjectName).config;
+            const oldEnvLegacyDir = options?.oldEnvLegacyDir ?? envPaths(oldEnvProjectName).config;
             const oldEnvLegacyFilePath = path.join(oldEnvLegacyDir, `${oldEnvConfigName}.json`);
             if (needsMigration({
                 legacyFilePath: oldEnvLegacyFilePath,
@@ -396,6 +398,13 @@ const PROJECT_STORE_SCHEMA_VERSION = 1;
         try {
             return new Conf(confOptions);
         } catch (error) {
+            const migrated = this.tryMigrateLegacyKey(confOptions);
+            if (migrated) {
+                if (this.environment === 'staging') {
+                    log.info('Successfully migrated local token cache.');
+                }
+                return migrated;
+            }
             // Deserialization failed (e.g. encryption key changed).
             // Log diagnostics, then clear and replace with a fresh store.
             if (this.environment === 'staging') {
@@ -412,6 +421,37 @@ const PROJECT_STORE_SCHEMA_VERSION = 1;
             return config;
         }
     }
+    tryMigrateLegacyKey(confOptions) {
+        if (!confOptions.encryptionKey) {
+            return null;
+        }
+        let snapshot;
+        try {
+            const legacyConf = new Conf({
+                ...confOptions,
+                clearInvalidConfig: false,
+                encryptionKey: this.deriveLegacyKey()
+            });
+            snapshot = {
+                ...legacyConf.store
+            };
+        } catch  {
+            return null;
+        }
+        try {
+            const rewritten = new Conf({
+                ...confOptions,
+                clearInvalidConfig: true
+            });
+            rewritten.clear();
+            for (const [key, value] of Object.entries(snapshot)){
+                rewritten.set(key, value);
+            }
+            return rewritten;
+        } catch  {
+            return null;
+        }
+    }
     safeGet(params) {
         const { config, key } = params;
         try {

package/dist/auth/types.d.ts

@@ -109,10 +109,21 @@ export interface OAuthTokenRefreshParams {
 export type TokenStoreConfig = {
     /** Config file name (for testing) */
     configName?: string;
+    /**
+     * Override for the legacy key derivation used by transparent migration.
+     * Tests pass an explicit function so they don't depend on the host machine's
+     * actual entropy. Production code leaves this undefined and the constructor
+     * falls back to `deriveLegacyEncryptionKey`.
+     */
+    deriveLegacyKey?: () => string;
     /** Optional override for storage encryption key (primarily for tests). */
     encryptionKey?: string;
     /** Environment for config file naming */
     environment?: Environment;
+    /** Override for the old per-environment legacy directory (primarily for tests). */
+    oldEnvLegacyDir?: string;
+    /** Override for the storage root directory (primarily for tests). */
+    rootDir?: string;
 };
 /**
  * PKCE (Proof Key for Code Exchange) pair for OAuth2 public clients

package/dist/cli.js

@@ -1,6 +1,7 @@
 import * as p from '@clack/prompts';
 import arg from 'arg';
 import pc from 'picocolors';
+import { bootstrapCommand } from './commands/bootstrap.js';
 import { buildLambdaZipCommand } from './commands/build-lambda-zip.js';
 import { debugCommand } from './commands/debug.js';
 import { deployCommand } from './commands/deploy.js';
@@ -42,9 +43,12 @@ class Main {
             '--help': Boolean,
             '--id': String,
             '--infra-env': String,
+            '--json': Boolean,
             '--name': String,
+            '--no-skill': Boolean,
             '--skip-auth': Boolean,
             '--skip-build': Boolean,
+            '--template': String,
             '--version': Boolean,
             '--yes': Boolean,
             // Aliases
@@ -53,6 +57,7 @@ class Main {
             '-f': '--force',
             '-h': '--help',
             '-n': '--name',
+            '-t': '--template',
             '-v': '--version',
             '-y': '--yes'
         }, {
@@ -112,6 +117,13 @@ class Main {
             p.intro(pc.bgCyan(pc.black(' @payloadcms/figma ')));
             // Route to appropriate command handler
             switch(subcommand){
+                case 'bootstrap':
+                    await bootstrapCommand({
+                        id: this.args['--id'],
+                        env: this.args['--env'],
+                        json: this.args['--json']
+                    });
+                    break;
                 case 'build-lambda-zip':
                     await buildLambdaZipCommand();
                     break;
@@ -137,7 +149,9 @@ class Main {
                         debug: this.args['--debug'],
                         env: this.args['--env'],
                         force: this.args['--force'],
-                        skipAuth: this.args['--skip-auth']
+                        noSkill: this.args['--no-skill'],
+                        skipAuth: this.args['--skip-auth'],
+                        template: this.args['--template']
                     });
                     break;
                 case 'list-tokens':

package/dist/commands/bootstrap.d.ts

@@ -0,0 +1,18 @@
+export type BootstrapCommandOptions = {
+    /** Filter to a single environment (e.g. "production", "staging"). */
+    env?: string;
+    /** CMS Resource ID (FIGMA_PROJECT_ID, e.g. cms_…). */
+    id?: string;
+    /** Emit plain JSON instead of a styled note (handy for piping into jq). */
+    json?: boolean;
+};
+/**
+ * Fetch and display bootstrap info for a CMS resource.
+ *
+ * Calls the Control Plane bootstrap endpoint with the current OAuth credential
+ * and prints the resulting environments (`contentSystemId`, `tenantInstanceId`)
+ * plus OAuth client credentials. Useful for grabbing a tenant ID without having
+ * to `init` a project.
+ */
+export declare function bootstrapCommand(options?: BootstrapCommandOptions): Promise<void>;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/commands/bootstrap.js

@@ -0,0 +1,90 @@
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { ControlPlaneError, getBootstrapInfo } from '../api/control-plane.js';
+import { getValidCredential } from '../auth/oauth-flow.js';
+import { getTokenStore } from '../auth/token-store.js';
+import { getInfraEnvironment } from '../constants.js';
+import { isDebug } from '../utils/is-debug.js';
+import { maskToken } from '../utils/token-display.js';
+/**
+ * Fetch and display bootstrap info for a CMS resource.
+ *
+ * Calls the Control Plane bootstrap endpoint with the current OAuth credential
+ * and prints the resulting environments (`contentSystemId`, `tenantInstanceId`)
+ * plus OAuth client credentials. Useful for grabbing a tenant ID without having
+ * to `init` a project.
+ */ export async function bootstrapCommand(options = {}) {
+    if (!options.id) {
+        p.log.error(pc.red('--id <project-id> is required'));
+        p.note('The CMS Resource ID (FIGMA_PROJECT_ID), e.g. cms_abc123', 'Tip');
+        process.exit(1);
+    }
+    const tokenStore = getTokenStore(getInfraEnvironment());
+    let credential;
+    try {
+        credential = await getValidCredential(tokenStore);
+    } catch (error) {
+        p.log.error(pc.red(`Failed to read stored credentials: ${error instanceof Error ? error.message : 'Unknown error'}`));
+        p.note(`Run ${pc.cyan(`@payloadcms/figma logout --infra-env ${getInfraEnvironment()} -y`)} ` + `then ${pc.cyan(`@payloadcms/figma login --infra-env ${getInfraEnvironment()}`)} and retry.`, 'Re-authenticate');
+        if (isDebug() && error instanceof Error) {
+            // eslint-disable-next-line no-console
+            console.error(error);
+        }
+        process.exit(1);
+    }
+    if (!credential) {
+        p.log.error(pc.red('Not authenticated.'));
+        p.note(`Run ${pc.cyan('@payloadcms/figma login')} first`, 'Tip');
+        process.exit(1);
+    }
+    let info;
+    try {
+        info = await getBootstrapInfo(credential, options.id, options.env);
+    } catch (error) {
+        if (error instanceof ControlPlaneError) {
+            p.log.error(pc.red(`Bootstrap fetch failed: ${error.statusCode} ${error.message}`));
+            if (error.statusCode === 401) {
+                p.note(`Stored credentials for infra env ${pc.bold(getInfraEnvironment())} were rejected.\n` + `Run ${pc.cyan(`@payloadcms/figma logout --infra-env ${getInfraEnvironment()} -y`)} ` + `then ${pc.cyan(`@payloadcms/figma login --infra-env ${getInfraEnvironment()}`)} and retry.`, 'Re-authenticate');
+            } else if (error.statusCode === 404) {
+                p.note(`Resource ${pc.bold(options.id)} was not found in infra env ${pc.bold(getInfraEnvironment())}.\n` + `Try ${pc.cyan('--infra-env staging')} (or production) to target a different infra.`, 'Wrong infra environment?');
+            }
+        } else if (error instanceof Error) {
+            const causeMessage = error.cause instanceof Error ? `: ${error.cause.message}` : '';
+            p.log.error(pc.red(`${error.name}: ${error.message}${causeMessage}`));
+            if (isDebug()) {
+                // eslint-disable-next-line no-console
+                console.error(error);
+            }
+        } else {
+            p.log.error(pc.red('Unknown error'));
+        }
+        process.exit(1);
+    }
+    if (options.json) {
+        const showSecretsInJson = isDebug();
+        const payload = showSecretsInJson ? info : {
+            ...info,
+            oauthCredentials: {
+                ...info.oauthCredentials,
+                oauthClientSecret: maskToken(info.oauthCredentials.oauthClientSecret)
+            }
+        };
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    const showSecret = isDebug();
+    const lines = [
+        `Project ID:        ${options.id}`,
+        `OAuth Client ID:   ${info.oauthCredentials.oauthClientId}`,
+        `OAuth Client Secret: ${showSecret ? info.oauthCredentials.oauthClientSecret : maskToken(info.oauthCredentials.oauthClientSecret)}`,
+        '',
+        'Environments:'
+    ];
+    for (const env of info.environments){
+        lines.push(`  ${pc.bold(env.name)}`, `    Tenant ID (contentSystemId): ${env.contentSystemId}`, `    Tenant Instance ID:          ${env.tenantInstanceId}`);
+    }
+    p.note(lines.join('\n'), 'Bootstrap Info');
+}
+
+//# sourceMappingURL=bootstrap.js.map

package/dist/commands/init.d.ts

@@ -12,8 +12,12 @@ export interface InitCommandOptions {
     id?: string;
     /** Project name (for scaffolding) */
     name?: string;
+    /** Skip Payload skill installation */
+    noSkill?: boolean;
     /** Skip authentication check (for testing/development) */
     skipAuth?: boolean;
+    /** GitHub template override, e.g. "v3.80.0:website" or "owner/repo#ref:template-path" */
+    template?: string;
     /** Skip prompts and use defaults where possible */
     yes?: boolean;
 }

package/dist/commands/init.js

@@ -8,6 +8,7 @@ import { tryGetCredential } from '../auth/oauth-flow.js';
 import { getValidProjectToken, ProjectTokenError } from '../auth/project-token.js';
 import { getTokenStore } from '../auth/token-store.js';
 import { getInfraEnvironment, getProjectNotFoundMessage } from '../constants.js';
+import { downloadSkill } from '../lib/download-skill.js';
 import { ensureGitignore } from '../utils/config.js';
 import { addOrUpdateEnvVar } from '../utils/env-management.js';
 import { isDebug } from '../utils/is-debug.js';
@@ -21,6 +22,23 @@ import { resolveEnvironment } from '../utils/resolve-environment.js';
 import { checkForUpdates, getOwnVersion } from '../utils/version-check.js';
 import { loginCommand } from './login.js';
 import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
+import { DEFAULT_TEMPLATE_SOURCE } from '../utils/download-template.js';
+import { parseTemplateSpec, TemplateSpecParseError } from '../utils/parse-template-spec.js';
+async function maybeInstallPayloadSkill(args) {
+    if (args.noSkill) {
+        return;
+    }
+    const result = await downloadSkill({
+        projectDir: args.projectDir
+    });
+    if (result.ok) {
+        return;
+    }
+    if (result.reason === 'already-installed') {
+        return;
+    }
+    p.log.warn(pc.yellow(`⚠ Could not install Payload skill (${result.reason}${result.detail ? `: ${result.detail}` : ''}). Continuing.`));
+}
 /**
  * Generate and store project token for a content system
  * Non-blocking - will show warning but not exit on failure
@@ -111,6 +129,18 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
         process.exit(1);
     }
     const cmsResourceId = options.id;
+    // Parse --template spec early so malformed values abort before any I/O
+    let templateSource;
+    if (options.template) {
+        try {
+            templateSource = parseTemplateSpec(options.template);
+        } catch (error) {
+            const message = error instanceof TemplateSpecParseError ? error.message : 'Invalid --template value';
+            p.log.error(pc.red(`✗ ${message}`));
+            p.note('Format: [<owner>/<repo>#]<ref>:<template-path>\n' + 'Examples:\n' + '  blank\n' + '  v3.80.0:website\n' + '  myorg/payload-fork#feat-x:templates/custom', 'Template spec');
+            process.exit(1);
+        }
+    }
     // Fetch bootstrap info (oauth creds + environments)
     let bootstrapInfo = null;
     let resolvedEnv = null;
@@ -225,6 +255,18 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
             p.note('Run this command in a directory without an existing project or in an existing Payload project.', 'Action Required');
             process.exit(1);
         }
+        // npm leaves node_modules in a transient state after a sequence of
+        // add/remove calls; without a final `install` the subprocess that runs
+        // generate:importmap silently misses @payloadcms/figma subpath components.
+        s.start('Reconciling dependencies...');
+        try {
+            await installDependencies(process.cwd(), packageManager);
+            s.stop(pc.green('✓ Dependencies reconciled'));
+        } catch (error) {
+            s.stop(pc.red('✗ Failed to reconcile dependencies before generate:importmap'));
+            log.error(error instanceof Error ? error.message : 'Unknown error');
+            process.exit(1);
+        }
         // Generate import map to prevent errors on first dev run
         const importMapResult = await runScript(process.cwd(), 'generate:importmap', packageManager);
         if (!importMapResult) {
@@ -238,9 +280,16 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
             '.env.local',
             'lambda.zip'
         ]);
+        await maybeInstallPayloadSkill({
+            noSkill: options.noSkill,
+            projectDir: process.cwd()
+        });
         // Generate project token (unless skipping auth)
         if (!options.skipAuth && resolvedEnv) {
-            await generateProjectTokenWithFeedback(tokenStore, resolvedEnv.contentSystemId, s);
+            await generateProjectTokenWithFeedback(tokenStore, resolvedEnv.contentSystemId, s, {
+                environmentName: resolvedEnv.name,
+                projectId: cmsResourceId
+            });
         }
         // Success message for existing project
         p.outro(pc.green('✓ Project initialized successfully!'));
@@ -286,9 +335,13 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
             process.exit(1);
         }
         // Scaffold project
-        s.start('Downloading template from GitHub...');
+        const resolvedSource = {
+            ...DEFAULT_TEMPLATE_SOURCE,
+            ...templateSource
+        };
+        s.start(`Downloading template "${resolvedSource.templatePath}" from ` + `${resolvedSource.owner}/${resolvedSource.repo}@${resolvedSource.ref}...`);
         try {
-            await scaffoldProject(fullPath, projectName, packageManager);
+            await scaffoldProject(fullPath, projectName, packageManager, templateSource);
             s.stop(pc.green('✓ Template downloaded'));
             s.start('Installing dependencies...');
             await installDependencies(fullPath, packageManager);
@@ -339,14 +392,33 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
         } catch (error) {
             p.log.warn(pc.yellow(`⚠ Failed to update .env file: ${error instanceof Error ? error.message : 'Unknown error'}`));
         }
+        // npm leaves node_modules in a transient state after a sequence of
+        // add/remove calls; without a final `install` the subprocess that runs
+        // generate:importmap silently misses @payloadcms/figma subpath components.
+        s.start('Reconciling dependencies...');
+        try {
+            await installDependencies(fullPath, packageManager);
+            s.stop(pc.green('✓ Dependencies reconciled'));
+        } catch (error) {
+            s.stop(pc.red('✗ Failed to reconcile dependencies before generate:importmap'));
+            log.error(error instanceof Error ? error.message : 'Unknown error');
+            process.exit(1);
+        }
         // Generate import map to prevent errors on first dev run
         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'));
         }
+        await maybeInstallPayloadSkill({
+            noSkill: options.noSkill,
+            projectDir: fullPath
+        });
         // Generate project token (unless skipping auth)
         if (!options.skipAuth && resolvedEnv) {
-            await generateProjectTokenWithFeedback(tokenStore, resolvedEnv.contentSystemId, s);
+            await generateProjectTokenWithFeedback(tokenStore, resolvedEnv.contentSystemId, s, {
+                environmentName: resolvedEnv.name,
+                projectId: cmsResourceId
+            });
         }
         // Initialize git repository (after all files including lock file are ready)
         initializeGitRepo(fullPath);

package/dist/config/oauth.d.ts

@@ -1,5 +1,6 @@
 import type { OAuthConfig } from '../auth/types.js';
-export declare const DEFAULT_CALLBACK_PORT = 34462;
+export declare const DEFAULT_CALLBACK_PORTS: number[];
+export declare const DEFAULT_CALLBACK_PORT: number;
 /**
  * Get OAuth configuration for current environment.
  *

package/dist/config/oauth.js

@@ -1,5 +1,11 @@
 import { getEnvConfig, getInfraEnvironment } from '../constants.js';
-export const DEFAULT_CALLBACK_PORT = 34462;
+export const DEFAULT_CALLBACK_PORTS = [
+    34462,
+    34463,
+    34464,
+    34465
+];
+export const DEFAULT_CALLBACK_PORT = DEFAULT_CALLBACK_PORTS[0];
 /**
  * Get OAuth configuration for current environment.
  *

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

@@ -3483,6 +3483,8 @@ export type components = {
         CreateDocumentRequest: {
             /** @example cms-xxxxx-xxxxx */
             contentSystemId: string;
+            /** User-defined Payload environment name (e.g. "production"). */
+            environmentName?: string;
             /** @example posts */
             collection: string;
             doc: components['schemas']['DocumentData'];
@@ -3594,6 +3596,8 @@ export type components = {
         UpdateDocumentRequest: {
             /** @example cms-xxxxx-xxxxx */
             contentSystemId: string;
+            /** User-defined Payload environment name (e.g. "production"). */
+            environmentName?: string;
             /** @example posts */
             collection: string;
             /** @example false */
@@ -3627,6 +3631,8 @@ export type components = {
         DeleteDocumentRequest: {
             /** @example cms-xxxxx-xxxxx */
             contentSystemId: string;
+            /** User-defined Payload environment name (e.g. "production"). */
+            environmentName?: string;
             /** @example posts */
             collection: string;
             locale?: components['schemas']['LocaleClause'];

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

@@ -6,6 +6,7 @@ type ContentAPIOptions = {
     allowIDOnCreate?: boolean;
     auth: AuthMode;
     contentSystemId: string;
+    environmentName?: string;
     url: string;
 };
 export type ContentAPIAdapter = {
@@ -13,6 +14,7 @@ export type ContentAPIAdapter = {
     clearDatabase: () => Promise<void>;
     client: ReturnType<typeof createClient<paths>>;
     contentSystemId: string;
+    environmentName?: string;
     idType: 'uuid';
     url: string;
 } & BaseDatabaseAdapter;