perf(cpa): use AST for templates

.gitignore

@@ -47,6 +47,7 @@ test/media
 *payloadtests.db-shm
 *payloadtests.db-wal
 /versions
+no-restrict-file-*
 
 # Created by https://www.toptal.com/developers/gitignore/api/node,macos,windows,webstorm,sublimetext,visualstudiocode
 # Edit at https://www.toptal.com/developers/gitignore?templates=node,macos,windows,webstorm,sublimetext,visualstudiocode

packages/create-payload-app/CLAUDE.md

@@ -0,0 +1,120 @@
+# create-payload-app
+
+Package for creating new Payload projects with custom configurations.
+
+## Architecture
+
+### AST-Based File Modification
+
+create-payload-app uses AST (Abstract Syntax Tree) parsing with ts-morph to modify template files during project creation.
+
+**3-Phase Pipeline:**
+
+1. **Detection** - Parse files and locate expected structures
+2. **Transformation** - Pure functions modify AST
+3. **Modification** - Validate, write, format with prettier
+
+### File Structure
+
+```txt
+src/lib/ast/
+├── types.ts                    # Shared types for AST operations
+├── utils.ts                    # Low-level AST helpers
+├── utils.spec.ts              # Unit tests for utils
+├── payload-config.ts          # Payload config transformations
+├── payload-config.spec.ts    # Unit tests for payload-config
+├── package-json.ts            # package.json modifications
+└── package-json.spec.ts      # Unit tests for package-json
+```
+
+### Key Functions
+
+**High-level API:**
+
+- `configurePayloadConfig(filePath, options)` - Main entry point for payload config
+- `updatePackageJson(filePath, options)` - Update package.json
+
+**Transformations:**
+
+- `addDatabaseAdapter(sourceFile, adapter, envVar)` - Add/replace db adapter
+- `addStorageAdapter(sourceFile, adapter)` - Add storage plugin
+- `removeSharp(sourceFile)` - Remove sharp dependency
+
+### Templates
+
+All templates follow standard structure:
+
+- `buildConfig()` call with object literal argument
+- `db` property for database adapter
+- `plugins` array (can be empty)
+
+No comment markers needed - AST finds structure by code patterns.
+
+### Package Management Flows
+
+create-payload-app has two distinct flows for handling package installation:
+
+#### Flow 1: `--init-next` (Next.js Integration)
+
+```mermaid
+sequenceDiagram
+    participant CLI
+    participant initNext
+    participant FS as File System
+    participant PM as Package Manager
+    participant AST as AST Operations
+
+    CLI->>initNext: --init-next with dbType
+    initNext->>FS: Copy template files
+    initNext->>PM: pnpm add payload @payloadcms/next @payloadcms/db-{type}
+    PM->>FS: Install packages to node_modules
+    initNext->>AST: configurePayloadConfig(filePath, {db})
+    AST->>FS: Update payload.config.ts (imports/config)
+    AST->>FS: Update package.json (dependencies)
+    initNext->>CLI: ✓ Project ready
+```
+
+**Key points:**
+
+- Uses `pnpm add` to install specific packages
+- Packages installed before AST modifications
+- No final `pnpm install` step
+
+#### Flow 2: Template/Example Creation
+
+```mermaid
+sequenceDiagram
+    participant CLI
+    participant createProject
+    participant FS as File System
+    participant AST as AST Operations
+    participant PM as Package Manager
+
+    CLI->>createProject: --template with dbType
+    createProject->>FS: Copy template/example files
+    createProject->>AST: configurePayloadConfig(projectDir, {db})
+    AST->>FS: Update payload.config.ts (imports/config)
+    AST->>FS: Update package.json (dependencies)
+    createProject->>PM: pnpm install
+    PM->>FS: Install packages from package.json
+    createProject->>CLI: ✓ Project ready
+```
+
+**Key points:**
+
+- Updates package.json first
+- Single `pnpm install` at end installs all dependencies
+- Package manager resolves dependencies from package.json
+
+**Package Operations:**
+
+- **Install**: Runs actual `pnpm add` or `pnpm install` command (Flow 1 or Flow 2 respectively)
+- **Package removal**: AST removes imports and updates package.json (orphaned packages cleaned up on next install)
+- No explicit `pnpm remove` - package.json modifications only
+
+### Testing
+
+**Unit tests:** Test individual transformation functions
+**Integration tests:** Test full create-payload-app flows
+
+Run tests: `pnpm --filter create-payload-app test`

packages/create-payload-app/package.json

@@ -70,8 +70,10 @@
     "figures": "^6.1.0",
     "fs-extra": "^9.0.1",
     "globby": "11.1.0",
+    "prettier": "^3.5.0",
     "tar": "^7.4.3",
-    "terminal-link": "^2.1.1"
+    "terminal-link": "^2.1.1",
+    "ts-morph": "^21.0.1"
   },
   "devDependencies": {
     "@types/esprima": "^4.0.6",

packages/create-payload-app/src/ast-integration.spec.ts

@@ -0,0 +1,155 @@
+import * as fs from 'fs'
+import * as fse from 'fs-extra'
+import * as path from 'path'
+import * as os from 'os'
+import { configurePayloadConfig } from './lib/configure-payload-config'
+import type { DbType, StorageAdapterType } from './types'
+import { DB_ADAPTER_CONFIG, STORAGE_ADAPTER_CONFIG } from './lib/ast/adapter-config'
+
+interface TestCase {
+  name: string
+  template: string
+  dbType: DbType
+  storageAdapter: StorageAdapterType
+}
+
+const TEST_CASES: TestCase[] = [
+  {
+    name: 'blank + mongodb + localDisk',
+    template: 'blank',
+    dbType: 'mongodb',
+    storageAdapter: 'localDisk',
+  },
+  {
+    name: 'blank + postgres + vercelBlobStorage',
+    template: 'blank',
+    dbType: 'postgres',
+    storageAdapter: 'vercelBlobStorage',
+  },
+  {
+    name: 'website + mongodb + s3Storage',
+    template: 'website',
+    dbType: 'mongodb',
+    storageAdapter: 's3Storage',
+  },
+  {
+    name: 'website + postgres + localDisk',
+    template: 'website',
+    dbType: 'postgres',
+    storageAdapter: 'localDisk',
+  },
+  {
+    name: 'ecommerce + mongodb + localDisk',
+    template: 'ecommerce',
+    dbType: 'mongodb',
+    storageAdapter: 'localDisk',
+  },
+  {
+    name: 'ecommerce + postgres + r2Storage',
+    template: 'ecommerce',
+    dbType: 'postgres',
+    storageAdapter: 'r2Storage',
+  },
+]
+
+describe('AST Integration Tests', () => {
+  let tempDir: string
+  const templatesRoot = path.resolve(__dirname, '../../..', 'templates')
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'payload-ast-integration-'))
+  })
+
+  afterEach(() => {
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true })
+    }
+  })
+
+  describe.each(TEST_CASES)('$name', ({ template, dbType, storageAdapter }) => {
+    it('successfully applies AST transformations', async () => {
+      // Setup: Copy template to temp directory
+      const templateDir = path.join(templatesRoot, template)
+      const testProjectDir = path.join(tempDir, template)
+
+      if (!fs.existsSync(templateDir)) {
+        throw new Error(`Template ${template} not found at ${templateDir}`)
+      }
+
+      fse.copySync(templateDir, testProjectDir)
+
+      const payloadConfigPath = path.join(testProjectDir, 'src', 'payload.config.ts')
+      const packageJsonPath = path.join(testProjectDir, 'package.json')
+
+      // Verify files exist before transformation
+      expect(fs.existsSync(payloadConfigPath)).toBe(true)
+      expect(fs.existsSync(packageJsonPath)).toBe(true)
+
+      // Apply transformations
+      await configurePayloadConfig({
+        dbType,
+        storageAdapter,
+        projectDirOrConfigPath: { projectDir: testProjectDir },
+      })
+
+      // Verify payload.config.ts transformations
+      const configContent = fs.readFileSync(payloadConfigPath, 'utf-8')
+
+      // Check database adapter import
+      const dbConfig = DB_ADAPTER_CONFIG[dbType]
+      expect(configContent).toContain(`from '${dbConfig.packageName}'`)
+      expect(configContent).toContain(`import { ${dbConfig.adapterName} }`)
+
+      // Check database adapter config
+      expect(configContent).toMatch(new RegExp(`db:\\s*${dbConfig.adapterName}\\(`))
+
+      // Check storage adapter if not localDisk
+      if (storageAdapter !== 'localDisk') {
+        const storageConfig = STORAGE_ADAPTER_CONFIG[storageAdapter]
+
+        if (storageConfig.packageName && storageConfig.adapterName) {
+          expect(configContent).toContain(`from '${storageConfig.packageName}'`)
+          expect(configContent).toContain(`import { ${storageConfig.adapterName} }`)
+          expect(configContent).toContain(`${storageConfig.adapterName}(`)
+        }
+      }
+
+      // Check that old mongodb adapter is removed if we switched to postgres
+      if (dbType === 'postgres') {
+        expect(configContent).not.toContain('@payloadcms/db-mongodb')
+        expect(configContent).not.toContain('mongooseAdapter')
+      }
+
+      // Check that plugins array exists if storage adapter was added
+      if (storageAdapter !== 'localDisk') {
+        expect(configContent).toContain('plugins:')
+      }
+
+      // Verify package.json transformations
+      const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'))
+
+      // Check that correct db adapter package is in dependencies
+      expect(packageJson.dependencies[dbConfig.packageName]).toBeDefined()
+
+      // Check that old db adapters are removed
+      Object.entries(DB_ADAPTER_CONFIG).forEach(([key, config]) => {
+        if (key !== dbType && config.packageName !== dbConfig.packageName) {
+          expect(packageJson.dependencies[config.packageName]).toBeUndefined()
+        }
+      })
+
+      // Note: Storage adapter dependencies are NOT automatically added to package.json
+      // by configurePayloadConfig - only the payload.config.ts is updated.
+      // This is expected behavior as storage adapters are typically installed separately.
+
+      // Verify file is valid TypeScript (basic syntax check)
+      expect(configContent).toContain('buildConfig')
+      expect(configContent).toContain('export default')
+
+      // Verify no placeholder comments remain
+      expect(configContent).not.toContain('database-adapter-import')
+      expect(configContent).not.toContain('database-adapter-config-start')
+      expect(configContent).not.toContain('storage-adapter-placeholder')
+    })
+  })
+})