@payloadcms/figma 0.0.1-alpha.64 → 0.0.1-alpha.66

package/dist/auth/callback-server.d.ts

@@ -7,6 +7,14 @@ export interface CallbackResult {
     /** State parameter for CSRF verification */
     state: string;
 }
+export type CallbackServerOptions = {
+    /** Additional callback ports to try after port. */
+    fallbackPorts?: number[];
+    /** First callback port to try. Defaults to the configured callback port range. */
+    port?: number;
+    /** Callback timeout in milliseconds. */
+    timeoutMs?: number;
+};
 /**
  * Error from OAuth callback
  */
@@ -20,18 +28,18 @@ export declare class CallbackError extends Error {
  * Starts a temporary server on localhost to receive the OAuth authorization code.
  * The server automatically shuts down after receiving the callback or on timeout.
  *
- * Implements dynamic port allocation: tries preferred port first, falls back to
- * OS-assigned port if unavailable.
+ * Tries the registered localhost callback ports in order. It does not use an
+ * OS-assigned random port because OAuth redirect URIs must be registered.
  */
 export declare class CallbackServer {
     private actualPort?;
-    private preferredPort;
+    private callbackPorts;
+    private readyPromise;
+    private rejectReady?;
+    private resolveReady?;
     private server;
     private timeoutMs;
-    constructor(options?: {
-        port?: number;
-        timeoutMs?: number;
-    });
+    constructor(options?: CallbackServerOptions);
     /**
      * Render error page shown in browser when auth fails
      */
@@ -57,5 +65,9 @@ export declare class CallbackServer {
      * @throws CallbackError if callback fails or times out
      */
     waitForCallback(expectedState: string): Promise<CallbackResult>;
+    /**
+     * Wait until the callback server is listening.
+     */
+    waitUntilReady(): Promise<number>;
 }
 //# sourceMappingURL=callback-server.d.ts.map

package/dist/auth/callback-server.js

@@ -2,7 +2,7 @@ import { readFileSync } from 'fs';
 import { createServer } from 'http';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { DEFAULT_CALLBACK_PORT } from '../config/oauth.js';
+import { DEFAULT_CALLBACK_PORT, DEFAULT_CALLBACK_PORTS } from '../config/oauth.js';
 const filename = fileURLToPath(import.meta.url);
 const dirname = path.dirname(filename);
 /**
@@ -20,17 +20,19 @@ const dirname = path.dirname(filename);
  * Starts a temporary server on localhost to receive the OAuth authorization code.
  * The server automatically shuts down after receiving the callback or on timeout.
  *
- * Implements dynamic port allocation: tries preferred port first, falls back to
- * OS-assigned port if unavailable.
+ * Tries the registered localhost callback ports in order. It does not use an
+ * OS-assigned random port because OAuth redirect URIs must be registered.
  */ export class CallbackServer {
     actualPort;
-    preferredPort;
+    callbackPorts;
+    readyPromise = null;
+    rejectReady;
+    resolveReady;
     server = null;
     timeoutMs;
     constructor(options = {}){
-        this.preferredPort = options.port || DEFAULT_CALLBACK_PORT;
+        this.callbackPorts = resolveCallbackPorts(options);
         this.timeoutMs = options.timeoutMs || 120000; // 2 minutes default
-        this.server = createServer();
     }
     /**
    * Render error page shown in browser when auth fails
@@ -47,7 +49,7 @@ const dirname = path.dirname(filename);
    * Get the actual port the server is listening on
    * @returns Port number (may differ from preferred if that was in use)
    */ getActualPort() {
-        return this.actualPort || this.preferredPort;
+        return this.actualPort || this.callbackPorts[0];
     }
     /**
    * Stop the server if running
@@ -65,6 +67,17 @@ const dirname = path.dirname(filename);
    * @throws CallbackError if callback fails or times out
    */ async waitForCallback(expectedState) {
         return new Promise((resolve, reject)=>{
+            if (this.server) {
+                reject(new CallbackError('Callback server is already running', 'server_error'));
+                return;
+            }
+            this.readyPromise = new Promise((resolveReady, rejectReady)=>{
+                this.resolveReady = resolveReady;
+                this.rejectReady = rejectReady;
+            });
+            this.readyPromise.catch(()=>{
+            // The caller may only await waitForCallback(); avoid an unhandled rejection.
+            });
             const cleanup = (handle)=>{
                 clearTimeout(handle);
                 if (this.server) {
@@ -77,8 +90,7 @@ const dirname = path.dirname(filename);
                 cleanup(timeoutHandle);
                 reject(new CallbackError('OAuth authorization timed out. Please try again.', 'timeout'));
             }, this.timeoutMs);
-            // Create HTTP server
-            this.server = createServer((req, res)=>{
+            const handleRequest = (req, res)=>{
                 const url = new URL(req.url || '', `http://localhost:${this.getActualPort()}`);
                 // Only handle /callback path
                 if (url.pathname !== '/callback') {
@@ -134,36 +146,65 @@ const dirname = path.dirname(filename);
                     code,
                     state
                 });
-            });
-            // Try to start server with dynamic port allocation
-            const tryListen = (port, isRetry = false)=>{
-                if (!this.server) {
-                    reject(new CallbackError('Server instance is not available', 'server_error'));
-                    return;
-                }
-                this.server.listen(port, '127.0.0.1', ()=>{
+            };
+            // Try registered callback ports in order.
+            const tryListen = (portIndex)=>{
+                const port = this.callbackPorts[portIndex];
+                const server = createServer(handleRequest);
+                this.server = server;
+                server.once('error', (err)=>{
+                    if (this.server === server) {
+                        this.server = null;
+                    }
+                    if (err.code === 'EADDRINUSE' && portIndex < this.callbackPorts.length - 1) {
+                        tryListen(portIndex + 1);
+                        return;
+                    }
+                    cleanup(timeoutHandle);
+                    const callbackError = err.code === 'EADDRINUSE' ? new CallbackError(`OAuth callback ports are all in use: ${this.callbackPorts.join(', ')}. Close the process using one of these ports and run login again.`, 'ports_in_use') : new CallbackError(`Failed to start callback server: ${err.message}`, 'server_error');
+                    this.rejectReady?.(callbackError);
+                    reject(callbackError);
+                });
+                server.listen(port, '127.0.0.1', ()=>{
+                    if (this.server !== server) {
+                        return;
+                    }
                     // Capture the actual port that was assigned
-                    const addr = this.server.address();
+                    const addr = server.address();
                     if (addr && typeof addr === 'object') {
                         this.actualPort = addr.port;
-                    }
-                });
-                // Handle server errors (port in use, etc)
-                this.server.once('error', (err)=>{
-                    if (err.code === 'EADDRINUSE' && !isRetry) {
-                        // Port in use, try with OS-assigned port (0 = dynamic)
-                        this.server.removeAllListeners();
-                        tryListen(0, true);
-                    } else {
-                        cleanup(timeoutHandle);
-                        reject(new CallbackError(`Failed to start callback server: ${err.message}${!isRetry ? ' (tried fallback port)' : ''}`));
+                        this.resolveReady?.(addr.port);
                     }
                 });
             };
-            // Start with preferred port
-            tryListen(this.preferredPort);
+            // Start with first configured port
+            tryListen(0);
         });
     }
+    /**
+   * Wait until the callback server is listening.
+   */ waitUntilReady() {
+        if (!this.readyPromise) {
+            return Promise.reject(new CallbackError('Callback server has not started', 'server_error'));
+        }
+        return this.readyPromise;
+    }
+}
+function resolveCallbackPorts(options) {
+    if (!options.port && !options.fallbackPorts) {
+        return DEFAULT_CALLBACK_PORTS;
+    }
+    const primaryPort = options.port || DEFAULT_CALLBACK_PORT;
+    const ports = uniquePorts([
+        primaryPort,
+        ...options.fallbackPorts || []
+    ]).slice(0, DEFAULT_CALLBACK_PORTS.length);
+    return ports.length > 0 ? ports : DEFAULT_CALLBACK_PORTS;
+}
+function uniquePorts(ports) {
+    return [
+        ...new Set(ports)
+    ];
 }
 
 //# sourceMappingURL=callback-server.js.map

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

@@ -30,6 +30,17 @@
  * @throws Error if unable to derive key due to missing machine information
  */
 export declare function deriveEncryptionKey(): string;
+/**
+ * @deprecated Exists solely to read token stores written by older versions of
+ * this CLI that mixed `os.hostname()` into the encryption-key derivation. macOS
+ * rewrites the kernel hostname across DHCP/VPN/sleep events, which made those
+ * stores periodically un-decryptable. Used only by the transparent-migration
+ * path in `token-store.ts` and should be removed in a future release once
+ * upgraded clients are sufficiently common.
+ *
+ * @returns 64-character hex string (32-byte key) suitable for AES-256
+ */
+export declare function deriveLegacyEncryptionKey(): string;
 /**
  * Get a short hash of the encryption key for diagnostics.
  * Returns first 8 chars of SHA-256 hash — enough to compare across invocations

package/dist/auth/crypto-utils.js

@@ -36,7 +36,6 @@ import path from 'path';
  */ function gatherMachineEntropy() {
     try {
         const entropy = [
-            os.hostname(),
             os.homedir(),
             os.userInfo().username,
             os.platform(),
@@ -88,6 +87,28 @@ import path from 'path';
     const key = crypto.pbkdf2Sync(machineId, salt, 100000, 32, 'sha256');
     return key.toString('hex');
 }
+/**
+ * @deprecated Exists solely to read token stores written by older versions of
+ * this CLI that mixed `os.hostname()` into the encryption-key derivation. macOS
+ * rewrites the kernel hostname across DHCP/VPN/sleep events, which made those
+ * stores periodically un-decryptable. Used only by the transparent-migration
+ * path in `token-store.ts` and should be removed in a future release once
+ * upgraded clients are sufficiently common.
+ *
+ * @returns 64-character hex string (32-byte key) suitable for AES-256
+ */ export function deriveLegacyEncryptionKey() {
+    const entropy = [
+        os.hostname(),
+        os.homedir(),
+        os.userInfo().username,
+        os.platform(),
+        os.arch()
+    ];
+    const machineId = entropy.join('::');
+    const salt = getOrCreateSalt();
+    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

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

@@ -14,7 +14,9 @@ export declare class OAuthFlowError extends Error {
 export interface OAuthFlowOptions {
     /** OAuth2 client ID (defaults to config) */
     clientId?: string;
-    /** Callback server port (defaults to DEFAULT_CALLBACK_PORT) */
+    /** Callback server fallback ports to try after port */
+    fallbackPorts?: number[];
+    /** First callback server port to try */
     port?: number;
     /** Redirect URI (defaults to config) */
     redirectUri?: string;

package/dist/auth/oauth-flow.js

@@ -1,6 +1,6 @@
 import * as p from '@clack/prompts';
 import crypto from 'crypto';
-import { DEFAULT_CALLBACK_PORT, getOAuthConfig } from '../config/oauth.js';
+import { getOAuthConfig } from '../config/oauth.js';
 import * as log from '../utils/log.js';
 import { buildAuthorizationUrl, openBrowser } from './browser.js';
 import { CallbackServer } from './callback-server.js';
@@ -53,25 +53,27 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
         };
     }
     // REAL OAUTH IMPLEMENTATION
-    const { clientId = oauthConfig.clientId, port = DEFAULT_CALLBACK_PORT, redirectUri = oauthConfig.redirectUri, scopes = oauthConfig.scopes, timeoutMs = 120000 } = options;
+    const { clientId = oauthConfig.clientId, fallbackPorts, port, redirectUri = oauthConfig.redirectUri, scopes = oauthConfig.scopes, timeoutMs = 120000 } = options;
     // Generate PKCE pair for enhanced security
     const { codeChallenge, codeChallengeMethod, codeVerifier } = generatePKCEPair();
     // Generate random state for CSRF protection
     const state = crypto.randomBytes(32).toString('base64url');
     // Create callback server
     const callbackServer = new CallbackServer({
+        fallbackPorts,
         port,
         timeoutMs
     });
     try {
         // Start waiting for callback (this starts the server and captures actual port)
         const callbackPromise = callbackServer.waitForCallback(state);
-        // Wait a bit for server to start and determine actual port
-        await new Promise((resolve)=>setTimeout(resolve, 100));
+        callbackPromise.catch(()=>{
+        // The callback promise is awaited below; avoid an unhandled rejection if startup fails early.
+        });
         // Get the actual port (may differ from preferred if that was in use)
-        const actualPort = callbackServer.getActualPort();
+        const actualPort = await callbackServer.waitUntilReady();
         // Build redirect URI with actual port
-        const actualRedirectUri = redirectUri.replace(/:\d+/, `:${actualPort}`);
+        const actualRedirectUri = replaceRedirectUriPort(redirectUri, actualPort);
         // Build authorization URL
         const authUrl = buildAuthorizationUrl({
             authorizationUrl: oauthConfig.authorizationUrl,
@@ -213,5 +215,10 @@ import { exchangeCodeForTokens, refreshAccessToken, TokenRefreshError } from './
         return null;
     }
 }
+function replaceRedirectUriPort(redirectUri, port) {
+    const url = new URL(redirectUri);
+    url.port = String(port);
+    return url.toString();
+}
 
 //# sourceMappingURL=oauth-flow.js.map

package/dist/auth/project-token.js

@@ -5,7 +5,7 @@
  * to the Content API. Project tokens are scoped to a specific tenant/CMS
  * and have a shorter lifespan (15-30 minutes) than OAuth tokens.
  */ import { getProjectToken as fetchProjectToken } from '../api/figma-api.js';
-import { TOKEN_EXPIRY_BUFFER_SECONDS } from '../config/oauth.js';
+import { PROJECT_TOKEN_EXPIRY_BUFFER_SECONDS } from '../config/oauth.js';
 import { getInfraEnvironment } from '../constants.js';
 import * as log from '../utils/log.js';
 import { JWTValidationError, validateProjectToken } from './jwt-validator.js';
@@ -27,7 +27,7 @@ function buildCacheKey(params) {
     return `${params.tenantId}::${projectId}::${environmentName}`;
 }
 function isCachedTokenValid(entry) {
-    const bufferMs = TOKEN_EXPIRY_BUFFER_SECONDS * 1000;
+    const bufferMs = PROJECT_TOKEN_EXPIRY_BUFFER_SECONDS * 1000;
     return Date.now() < entry.expiresAt - bufferMs;
 }
 /** Test-only: clears the in-memory token cache and any in-flight refresh promises. */ export function __resetProjectTokenCacheForTests() {

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

@@ -2,11 +2,11 @@
 import envPaths from 'env-paths';
 import fsSync from 'node:fs';
 import path from 'node:path';
-import { TOKEN_EXPIRY_BUFFER_SECONDS } from '../config/oauth.js';
+import { PROJECT_TOKEN_EXPIRY_BUFFER_SECONDS, 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,6 +46,7 @@ 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;
@@ -274,7 +276,7 @@ const PROJECT_STORE_SCHEMA_VERSION = 1;
     }
     isProjectTokenExpired(token) {
         const now = Date.now();
-        const bufferMs = TOKEN_EXPIRY_BUFFER_SECONDS * 1000;
+        const bufferMs = PROJECT_TOKEN_EXPIRY_BUFFER_SECONDS * 1000;
         const expiryWithBuffer = token.expiresAt - bufferMs;
         return now >= expiryWithBuffer;
     }
@@ -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,6 +109,13 @@ 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 */

package/dist/cli.js

@@ -45,8 +45,10 @@ class Main {
             '--infra-env': String,
             '--json': Boolean,
             '--name': String,
+            '--no-skill': Boolean,
             '--skip-auth': Boolean,
             '--skip-build': Boolean,
+            '--template': String,
             '--version': Boolean,
             '--yes': Boolean,
             // Aliases
@@ -55,6 +57,7 @@ class Main {
             '-f': '--force',
             '-h': '--help',
             '-n': '--name',
+            '-t': '--template',
             '-v': '--version',
             '-y': '--yes'
         }, {
@@ -146,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/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;
@@ -250,6 +280,10 @@ 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, {
@@ -301,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);
@@ -371,6 +409,10 @@ import { cacheAllEnvironments } from '../utils/cache-bootstrap.js';
         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, {

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.
  *
@@ -14,4 +15,11 @@ export declare const DEFAULT_CALLBACK_PORT = 34462;
  */
 export declare function getOAuthConfig(): OAuthConfig;
 export declare const TOKEN_EXPIRY_BUFFER_SECONDS = 300;
+/**
+ * Freshness buffer for project tokens. Figma's `pixie` issues 300-second project
+ * tokens, so reusing the 300-second OAuth buffer would treat every fresh token as
+ * already-expired and bypass the cache entirely. 30 seconds is well above the
+ * round-trip time for the calls these tokens authorize.
+ */
+export declare const PROJECT_TOKEN_EXPIRY_BUFFER_SECONDS = 30;
 //# sourceMappingURL=oauth.d.ts.map

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.
  *
@@ -31,5 +37,11 @@ export const DEFAULT_CALLBACK_PORT = 34462;
     };
 }
 export const TOKEN_EXPIRY_BUFFER_SECONDS = 300;
+/**
+ * Freshness buffer for project tokens. Figma's `pixie` issues 300-second project
+ * tokens, so reusing the 300-second OAuth buffer would treat every fresh token as
+ * already-expired and bypass the cache entirely. 30 seconds is well above the
+ * round-trip time for the calls these tokens authorize.
+ */ export const PROJECT_TOKEN_EXPIRY_BUFFER_SECONDS = 30;
 
 //# sourceMappingURL=oauth.js.map