@payloadcms/figma 0.0.1-alpha.9 → 0.1.0-alpha.0

package/dist/utils/project.js

@@ -1,13 +1,15 @@
 /**
  * Project detection and scaffolding utilities
- */ import { spawn } from 'child_process';
+ */ import spawn from 'cross-spawn';
 import fs from 'fs/promises';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import { ensureGitignore } from './config.js';
 import { downloadTemplateFromGitHub } from './download-template.js';
-import { manageEnvFiles } from './env-management.js';
 import { tryInitRepoAndCommit } from './git.js';
 import { applyLambdaModifications } from './lambda-config.js';
+import { getRunCommand } from './package-manager.js';
+import { getOwnVersion } from './version-check.js';
 /**
  * Detect if current directory has a Payload project
  *
@@ -51,63 +53,76 @@ import { applyLambdaModifications } from './lambda-config.js';
     }
 }
 /**
- * Validate Payload version (must be 3.x)
+ * Validate Payload version (must be 4.x or newer)
  *
  * @param version - Version string from package.json
  * @returns True if version is valid
  */ export function validatePayloadVersion(version) {
-    // Extract major version (handle ^3.0.0, ~3.0.0, 3.0.0, etc.)
+    // Extract major version (handle ^4.0.0, ~4.0.0, 4.0.0, 4.0.0-canary.16, etc.)
     const match = version.match(/(\d+)/);
     if (!match) {
         return false;
     }
     const majorVersion = parseInt(match[1], 10);
-    return majorVersion === 3;
+    return majorVersion >= 4;
 }
 /**
- * Fetch the latest version of a package from npm registry
+ * Resolve a package version from an npm dist-tag or an explicit version.
  *
- * @param packageName - Package name to fetch version for
- * @returns Latest version string
- */ async function getLatestPackageVersion(packageName) {
-    const response = await fetch(`https://registry.npmjs.org/-/package/${packageName}/dist-tags`);
-    if (!response.ok) {
-        throw new Error(`Failed to fetch version for ${packageName}: ${response.statusText}`);
+ * A value matching a published dist-tag (e.g. 'latest', 'canary') resolves to
+ * that tag's concrete version. Any other value is treated as an explicit version
+ * and verified against the registry.
+ *
+ * @param packageName - Package name to look up
+ * @param versionOrTag - npm dist-tag or explicit semver version; defaults to 'latest'
+ * @returns The concrete version string to pin
+ */ async function resolvePackageVersion(packageName, versionOrTag = 'latest') {
+    const distTagsResponse = await fetch(`https://registry.npmjs.org/-/package/${packageName}/dist-tags`);
+    if (!distTagsResponse.ok) {
+        throw new Error(`Failed to fetch versions for ${packageName}: ${distTagsResponse.statusText}`);
+    }
+    const distTags = await distTagsResponse.json();
+    const tagged = distTags[versionOrTag];
+    if (typeof tagged === 'string') {
+        return tagged;
     }
-    const data = await response.json();
-    if (typeof data.latest !== 'string') {
-        throw new Error(`Invalid version data received for ${packageName}`);
+    // Not a dist-tag — treat as an explicit version and verify it's published.
+    const versionResponse = await fetch(`https://registry.npmjs.org/${packageName}/${versionOrTag}`);
+    if (versionResponse.ok) {
+        return versionOrTag;
     }
-    return data.latest;
+    throw new Error(`No "${versionOrTag}" version or dist-tag published for ${packageName}. Available dist-tags: ${Object.keys(distTags).join(', ')}`);
 }
 /**
  * Replace workspace versions in package.json with actual versions
  *
  * @param packageJson - Package JSON object to update
- * @param latestVersion - Latest Payload version to use
- */ function replaceWorkspaceVersions(packageJson, latestVersion) {
+ * @param coreVersion - Resolved core Payload version to use
+ */ function replaceWorkspaceVersions(packageJson, coreVersion, figmaVersion) {
     const deps = packageJson.dependencies;
     if (!deps) {
         return;
     }
     for (const [key, value] of Object.entries(deps)){
-        // Replace workspace:* or workspace:^ with actual version
-        if (typeof value === 'string' && value.startsWith('workspace:')) {
-            deps[key] = latestVersion;
+        if (key === '@payloadcms/figma') {
+            deps[key] = figmaVersion;
+        } else if (typeof value === 'string' && value.startsWith('workspace:')) {
+            deps[key] = coreVersion;
         } else if (key === 'payload' || key.startsWith('@payloadcms/')) {
-            deps[key] = latestVersion;
+            deps[key] = coreVersion;
         }
     }
-    // Also handle devDependencies if present
     const devDeps = packageJson.devDependencies;
     if (!devDeps) {
         return;
     }
     for (const [key, value] of Object.entries(devDeps)){
-        if (typeof value === 'string' && value.startsWith('workspace:')) {
-            devDeps[key] = latestVersion;
+        if (key === '@payloadcms/figma') {
+            devDeps[key] = figmaVersion;
+        } else if (typeof value === 'string' && value.startsWith('workspace:')) {
+            devDeps[key] = coreVersion;
         } else if (key === 'payload' || key.startsWith('@payloadcms/')) {
-            devDeps[key] = latestVersion;
+            devDeps[key] = coreVersion;
         }
     }
 }
@@ -116,18 +131,24 @@ import { applyLambdaModifications } from './lambda-config.js';
  *
  * @param projectPath - Path where to create the project
  * @param projectName - Name for the project
- */ export async function scaffoldProject(projectPath, projectName) {
+ * @param packageManager - Package manager to use
+ * @param templateSource - Optional template source override
+ * @param payloadVersion - npm dist-tag or explicit version for core payload packages (default 'canary')
+ */ export async function scaffoldProject(projectPath, projectName, packageManager = 'npm', templateSource, payloadVersion = 'canary') {
     // Create project directory if it doesn't exist
     await fs.mkdir(projectPath, {
         recursive: true
     });
     // Download template from GitHub
-    await downloadTemplateFromGitHub(projectPath);
+    await downloadTemplateFromGitHub(projectPath, templateSource);
     // Apply Lambda modifications BEFORE updating package.json
     // This ensures we don't overwrite version replacements
-    await applyLambdaModifications(projectPath);
-    // Get latest Payload version from npm
-    const latestVersion = await getLatestPackageVersion('payload');
+    await applyLambdaModifications(projectPath, packageManager);
+    // Resolve core Payload version from the selected dist-tag or version; figma uses CLI version
+    const [coreVersion, figmaVersion] = await Promise.all([
+        resolvePackageVersion('payload', payloadVersion),
+        getOwnVersion()
+    ]);
     // Delete any existing lock files from template (they reference workspace:* versions)
     // This ensures pnpm install creates a fresh lock file with actual versions
     const lockFiles = [
@@ -149,16 +170,24 @@ import { applyLambdaModifications } from './lambda-config.js';
     const packageJson = JSON.parse(packageJsonContent);
     packageJson.name = projectName;
     // Replace workspace:* versions with actual versions
-    replaceWorkspaceVersions(packageJson, latestVersion);
+    replaceWorkspaceVersions(packageJson, coreVersion, figmaVersion);
     await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n', 'utf-8');
-    // Manage environment files (generate PAYLOAD_SECRET)
-    await manageEnvFiles(projectPath);
     // Ensure .gitignore has required entries
+    // Note: .env file is created by init command with FIGMA_CONTENT_API_CONTENT_SYSTEM_ID
     await ensureGitignore(projectPath, [
         '.env',
         '.env.local',
         'lambda.zip'
     ]);
+    // Replace README with Figma-specific version
+    const readmeTemplatePath = fileURLToPath(new URL('../templates/README.md', import.meta.url));
+    let readmeContent = await fs.readFile(readmeTemplatePath, 'utf-8');
+    readmeContent = readmeContent.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+    readmeContent = readmeContent.replace(/\{\{RUN_COMMAND\}\}/g, getRunCommand(packageManager));
+    await fs.writeFile(path.join(projectPath, 'README.md'), readmeContent, 'utf-8');
+    // Copy .env.example template
+    const envExampleTemplatePath = fileURLToPath(new URL('../templates/.env.example', import.meta.url));
+    await fs.copyFile(envExampleTemplatePath, path.join(projectPath, '.env.example'));
 }
 /**
  * Initialize git repository after all setup is complete
@@ -181,7 +210,6 @@ import { applyLambdaModifications } from './lambda-config.js';
             'install'
         ], {
             cwd: projectPath,
-            shell: true,
             stdio: 'pipe'
         });
         let stdout = '';
@@ -246,5 +274,3 @@ import { applyLambdaModifications } from './lambda-config.js';
         return false;
     }
 }
-
-//# sourceMappingURL=project.js.map

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

@@ -0,0 +1,13 @@
+import type { BootstrapEnvironment } from '../api/control-plane.js';
+/**
+ * Resolve which environment to use from the bootstrap response.
+ *
+ * - Single environment: auto-select (environmentName optional, validated if provided)
+ * - Multiple environments: environmentName required, must match
+ *
+ * @throws Error if resolution fails (with available environment names)
+ */
+export declare function resolveEnvironment(params: {
+    environmentName?: string;
+    environments: BootstrapEnvironment[];
+}): BootstrapEnvironment;

package/dist/utils/resolve-environment.js

@@ -0,0 +1,29 @@
+/**
+ * Resolve which environment to use from the bootstrap response.
+ *
+ * - Single environment: auto-select (environmentName optional, validated if provided)
+ * - Multiple environments: environmentName required, must match
+ *
+ * @throws Error if resolution fails (with available environment names)
+ */ export function resolveEnvironment(params) {
+    const { environmentName, environments } = params;
+    if (environments.length === 0) {
+        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
+    const availableNames = environments.map((e)=>e.name).join(', ');
+    if (!environmentName) {
+        throw new Error(`Multiple environments available. Use --env to specify one: ${availableNames}`);
+    }
+    const matched = environments.find((e)=>e.name === environmentName);
+    if (!matched) {
+        throw new Error(`Environment "${environmentName}" not found. Available: ${availableNames}`);
+    }
+    return matched;
+}

package/dist/utils/s3-upload.d.ts

@@ -18,7 +18,6 @@ export interface UploadResults {
  *
  * @param filePath - Absolute path to file to upload
  * @param signedUrl - Signed S3 upload URL
- * @param contentType - MIME type (optional)
  * @throws Error if upload fails after retries
  */
 export declare function uploadFile(filePath: string, signedUrl: string, contentType?: string): Promise<void>;
@@ -39,5 +38,10 @@ export declare function uploadLambdaZip(zipPath: string, signedUrl: string): Pro
  * @param onProgress - Optional callback for progress updates (uploaded, total)
  * @returns Upload results with counts
  */
-export declare function uploadStaticAssets(projectPath: string, assetUrls: Record<string, string>, onProgress?: (uploaded: number, total: number) => void): Promise<UploadResults>;
-//# sourceMappingURL=s3-upload.d.ts.map
+export declare function uploadStaticAssets(params: {
+    assetUrls: Record<string, string>;
+    onProgress?: (uploaded: number, total: number) => void;
+    /** Map of S3 key → relative filesystem path (overrides default _next/ → .next/ resolution) */
+    pathMap?: Record<string, string>;
+    projectPath: string;
+}): Promise<UploadResults>;

package/dist/utils/s3-upload.js

@@ -1,5 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
+import { parseS3Error } from '../api/error-response.js';
 import * as log from './log.js';
 /**
  * Retry configuration
@@ -11,6 +12,37 @@ const INITIAL_RETRY_DELAY = 1000 // 1 second
  */ function sleep(ms) {
     return new Promise((resolve)=>setTimeout(resolve, ms));
 }
+/** Common MIME types for web assets, keyed by file extension */ const MIME_TYPES = {
+    '.avif': 'image/avif',
+    '.css': 'text/css',
+    '.csv': 'text/csv',
+    '.eot': 'application/vnd.ms-fontobject',
+    '.gif': 'image/gif',
+    '.html': 'text/html',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'application/javascript',
+    '.json': 'application/json',
+    '.map': 'application/json',
+    '.meta': 'application/json',
+    '.mjs': 'application/javascript',
+    '.mp4': 'video/mp4',
+    '.otf': 'font/otf',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.rsc': 'text/x-component',
+    '.svg': 'image/svg+xml',
+    '.ttf': 'font/ttf',
+    '.txt': 'text/plain',
+    '.wasm': 'application/wasm',
+    '.webm': 'video/webm',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.xml': 'application/xml',
+    '.zip': 'application/zip'
+};
 /**
  * Check if a signed URL is a mock URL
  */ function isMockUrl(signedUrl) {
@@ -23,7 +55,6 @@ const INITIAL_RETRY_DELAY = 1000 // 1 second
  *
  * @param filePath - Absolute path to file to upload
  * @param signedUrl - Signed S3 upload URL
- * @param contentType - MIME type (optional)
  * @throws Error if upload fails after retries
  */ export async function uploadFile(filePath, signedUrl, contentType) {
     // Skip actual upload for mock URLs
@@ -45,17 +76,22 @@ const INITIAL_RETRY_DELAY = 1000 // 1 second
     let lastError = null;
     for(let attempt = 0; attempt < MAX_RETRIES; attempt++){
         try {
+            const ext = path.extname(filePath).toLowerCase();
+            const determinedContentType = contentType ?? MIME_TYPES[ext];
             const response = await fetch(signedUrl, {
                 body: fileBuffer,
-                headers: contentType ? {
-                    'Content-Type': contentType
+                headers: determinedContentType ? {
+                    'Content-Type': determinedContentType
                 } : {},
                 method: 'PUT'
             });
             if (response.ok) {
                 return; // Success
             }
-            lastError = new Error(`Upload failed: ${response.status} ${response.statusText}`);
+            lastError = new Error(await parseS3Error({
+                context: `upload ${path.basename(filePath)}`,
+                response
+            }));
         } catch (error) {
             lastError = error instanceof Error ? error : new Error('Unknown error');
         }
@@ -83,7 +119,8 @@ const INITIAL_RETRY_DELAY = 1000 // 1 second
  * @param assetUrls - Map of asset paths to signed URLs
  * @param onProgress - Optional callback for progress updates (uploaded, total)
  * @returns Upload results with counts
- */ export async function uploadStaticAssets(projectPath, assetUrls, onProgress) {
+ */ export async function uploadStaticAssets(params) {
+    const { assetUrls, onProgress, pathMap, projectPath } = params;
     const results = {
         assetsFailed: 0,
         assetsUploaded: 0,
@@ -100,8 +137,8 @@ const INITIAL_RETRY_DELAY = 1000 // 1 second
         const batch = assetPaths.slice(i, i + CONCURRENCY);
         await Promise.all(batch.map(async (assetPath)=>{
             try {
-                // Convert _next back to .next for file system
-                const fsPath = assetPath.replace(/^_next\//, '.next/');
+                // Resolve filesystem path: use pathMap if available, else default _next/ → .next/
+                const fsPath = pathMap?.[assetPath] ?? assetPath.replace(/^_next\//, '.next/');
                 const fullPath = path.join(projectPath, fsPath);
                 const signedUrl = assetUrls[assetPath];
                 await uploadFile(fullPath, signedUrl);
@@ -119,5 +156,3 @@ const INITIAL_RETRY_DELAY = 1000 // 1 second
     }
     return results;
 }
-
-//# sourceMappingURL=s3-upload.js.map

package/dist/utils/token-display.d.ts

@@ -8,7 +8,10 @@ export declare function maskToken(token: string): string;
  */
 export declare function formatTimestamp(timestamp: number): string;
 /**
- * Show all stored project tokens
+ * Show the project token for the current project + environment scope.
+ *
+ * Resolves `projectId` and `environmentName` from env vars
+ * (`FIGMA_PROJECT_ID`, `FIGMA_ENVIRONMENT_NAME`) — the *user's* project
+ * environment, which is independent of the infra env (production/staging).
  */
 export declare function showProjectTokens(tokenStore: TokenStore): void;
-//# sourceMappingURL=token-display.d.ts.map

package/dist/utils/token-display.js

@@ -1,5 +1,6 @@
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
+import { getEnvVarSync } from './env-management.js';
 import { isDebug } from './is-debug.js';
 /**
  * Mask token for display (show first 4 and last 4 characters)
@@ -32,32 +33,56 @@ import { isDebug } from './is-debug.js';
     return pc.red(`${minutes}m`);
 }
 /**
- * Show all stored project tokens
+ * Show the project token for the current project + environment scope.
+ *
+ * Resolves `projectId` and `environmentName` from env vars
+ * (`FIGMA_PROJECT_ID`, `FIGMA_ENVIRONMENT_NAME`) — the *user's* project
+ * environment, which is independent of the infra env (production/staging).
  */ export function showProjectTokens(tokenStore) {
-    // Get all tenant IDs that have project tokens
-    const tenantIds = tokenStore.getAllProjectTokenTenantIds();
-    if (tenantIds.length === 0) {
-        p.log.step(pc.dim('No project tokens stored.'));
-        p.note(`Run ${pc.cyan('@payloadcms/figma init')} to create a CMS instance`, 'Tip');
+    const cwd = process.cwd();
+    const projectId = getEnvVarSync(cwd, 'FIGMA_PROJECT_ID');
+    const environmentName = getEnvVarSync(cwd, 'FIGMA_ENVIRONMENT_NAME');
+    if (!projectId || !environmentName) {
+        p.note(pc.dim('Set FIGMA_PROJECT_ID and FIGMA_ENVIRONMENT_NAME in your .env to view project tokens.'), 'Project Tokens');
         return;
     }
-    const projectTokenLines = [];
-    tenantIds.forEach((tenantId, index)=>{
-        const projectToken = tokenStore.getProjectToken(tenantId);
-        if (!projectToken) {
-            return;
-        }
-        const isValid = tokenStore.hasValidProjectToken(tenantId);
-        const status = isValid ? pc.green('✓ Valid') : pc.red('✗ Expired');
-        if (index > 0) {
-            projectTokenLines.push(''); // Blank line between tokens
-        }
-        projectTokenLines.push(`Tenant ID:      ${tenantId}`);
-        projectTokenLines.push(`Status:         ${status}`);
-        projectTokenLines.push(`Token:          ${isDebug() ? projectToken.token : maskToken(projectToken.token)}`);
-        projectTokenLines.push(`Expires:        ${formatTimestamp(projectToken.expiresAt)}`);
+    const header = [
+        `Project ID:     ${projectId}`,
+        `Environment:    ${environmentName}`
+    ];
+    const bootstrapData = tokenStore.getBootstrapData(projectId, environmentName);
+    if (!bootstrapData) {
+        p.note([
+            ...header,
+            pc.dim('No bootstrap data. Run `@payloadcms/figma init` to set up.')
+        ].join('\n'), 'Project Token');
+        return;
+    }
+    const projectInfo = {
+        environmentName,
+        projectId
+    };
+    const projectToken = tokenStore.getProjectToken({
+        projectInfo
+    });
+    if (!projectToken) {
+        p.note([
+            ...header,
+            `Tenant ID:      ${bootstrapData.contentSystemId}`,
+            pc.dim('No stored token.')
+        ].join('\n'), 'Project Token');
+        return;
+    }
+    const isValid = tokenStore.hasValidProjectToken({
+        projectInfo
     });
-    p.note(projectTokenLines.join('\n'), `Project Tokens (${tenantIds.length})`);
+    const status = isValid ? pc.green('✓ Valid') : pc.red('✗ Expired');
+    const projectTokenLines = [
+        ...header,
+        `Tenant ID:      ${bootstrapData.contentSystemId}`,
+        `Status:         ${status}`,
+        `Token:          ${isDebug() ? projectToken.token : maskToken(projectToken.token)}`,
+        `Expires:        ${formatTimestamp(projectToken.expiresAt)}`
+    ];
+    p.note(projectTokenLines.join('\n'), 'Project Token');
 }
-
-//# sourceMappingURL=token-display.js.map

package/dist/utils/typescript-validator.d.ts

@@ -8,4 +8,3 @@ export type TypeScriptCheckResult = {
  * Skips silently if TypeScript not available
  */
 export declare function runTypeScriptCheck(projectPath: string, packageManager: PackageManager): Promise<TypeScriptCheckResult>;
-//# sourceMappingURL=typescript-validator.d.ts.map

package/dist/utils/typescript-validator.js

@@ -1,18 +1,16 @@
-import { spawn } from 'child_process';
+import spawn from 'cross-spawn';
 /**
  * Run TypeScript type checking (tsc --noEmit)
  * Skips silently if TypeScript not available
  */ export async function runTypeScriptCheck(projectPath, packageManager) {
     return new Promise((resolve)=>{
         try {
-            const args = [
+            const child = spawn(packageManager, [
                 'exec',
                 'tsc',
                 '--noEmit'
-            ];
-            const child = spawn(packageManager, args, {
+            ], {
                 cwd: projectPath,
-                shell: true,
                 stdio: 'pipe'
             });
             let output = '';
@@ -52,7 +50,5 @@ import { spawn } from 'child_process';
 /**
  * Parse TypeScript error output
  */ function parseTypeScriptErrors(output) {
-    return output.split('\n').filter((line)=>line.includes('error TS')).map((line)=>line.trim());
+    return output.split(/\r?\n/).filter((line)=>line.includes('error TS')).map((line)=>line.trim());
 }
-
-//# sourceMappingURL=typescript-validator.js.map

package/dist/utils/version-check.d.ts

@@ -0,0 +1,2 @@
+export declare function checkForUpdates(currentVersion: string): Promise<void>;
+export declare function getOwnVersion(): Promise<string>;

package/dist/utils/version-check.js

@@ -0,0 +1,43 @@
+import * as p from '@clack/prompts';
+import fs from 'fs/promises';
+import path from 'path';
+import pc from 'picocolors';
+import { fileURLToPath } from 'url';
+const REGISTRY_URL = 'https://registry.npmjs.org/@payloadcms/figma';
+const TIMEOUT_MS = 3000;
+export async function checkForUpdates(currentVersion) {
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(()=>controller.abort(), TIMEOUT_MS);
+        const response = await fetch(REGISTRY_URL, {
+            signal: controller.signal
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            return;
+        }
+        const data = await response.json();
+        const latestVersion = data['dist-tags']?.latest;
+        if (!latestVersion || latestVersion === currentVersion) {
+            return;
+        }
+        p.log.warn(pc.yellow(`@payloadcms/figma ${currentVersion} differs from latest. Latest: ${latestVersion}`));
+        p.log.message(pc.dim(`  Run: npx @payloadcms/figma@${latestVersion} init --id <your-id>`));
+    } catch  {
+    // Silent catch - network errors, timeouts, parse errors should not interrupt CLI
+    }
+}
+export async function getOwnVersion() {
+    // Test/CI seam: e2e runs scaffold with the CLI's own version, but a locally
+    // built (unpublished) version isn't npm-resolvable. Allow overriding with a
+    // published version so `init`'s dependency install resolves.
+    const override = process.env.FIGMA_CLI_VERSION_OVERRIDE;
+    if (override) {
+        return override;
+    }
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const packageJsonPath = path.join(__dirname, '../../package.json');
+    const content = await fs.readFile(packageJsonPath, 'utf-8');
+    const pkg = JSON.parse(content);
+    return pkg.version;
+}