@agility/create-next-app 1.0.0-beta.2

package/.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm pack:*)"
+    ]
+  }
+}

package/.claude/settings.local.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git log:*)",
+      "Bash(npm run build:*)",
+      "Bash(git clone:*)",
+      "Bash(npm view:*)",
+      "Bash(git mv:*)",
+      "Bash(grep:*)",
+      "Bash(tree:*)",
+      "Bash(git add:*)",
+      "Bash(npm install:*)",
+      "Bash(mkdir:*)",
+      "Bash(node -e:*)",
+      "Bash(ls:*)",
+      "Bash(comm -12:*)",
+      "Bash(for module in agility auth config templates)",
+      "Bash(do echo \"=== $module ===\" echo \"Barrel file exports:\" grep -E \"^\\(export|exports\\\\.\\)\" dist/$module.js)",
+      "Bash(done)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/FEATURE_ROADMAP.md

@@ -0,0 +1,343 @@
+# Feature Roadmap
+
+This document tracks planned enhancements for `create-next-agility-app`.
+
+## ✅ Completed (v1.0)
+
+- [x] Project name validation & directory checks
+- [x] Git initialization after project creation
+- [x] Enhanced error handling with recovery suggestions
+- [x] Success summary box with next steps
+- [x] Update notifier for CLI versions
+
+---
+
+## 📋 Should Have (v1.1)
+
+### 1. Template Selection
+**Priority:** High
+**Labels:** enhancement, good first issue
+
+Add the ability to choose from multiple starter templates during project creation.
+
+**Proposed Templates:**
+- **Basic** - Minimal setup (current default)
+- **Blog** - Pre-configured with posts, categories, pagination
+- **Marketing** - Hero sections, forms, CTAs
+- **E-commerce** - Products, cart, checkout
+
+**Implementation:**
+```typescript
+{
+  type: 'list',
+  name: 'template',
+  message: 'Choose a starter template:',
+  choices: [
+    { name: 'Basic (minimal setup)', value: 'basic' },
+    { name: 'Blog (posts, categories, authors)', value: 'blog' },
+    { name: 'Marketing (landing pages, forms, CTAs)', value: 'marketing' },
+    { name: 'E-commerce (products, cart, checkout)', value: 'ecommerce' }
+  ]
+}
+```
+
+---
+
+### 2. Better Progress Indicators
+**Priority:** Medium
+**Labels:** enhancement, good first issue
+
+Improve visual feedback with ora spinners for all long-running operations.
+
+**Operations to enhance:**
+- Creating Next.js base project
+- Installing Agility packages
+- Copying template files
+- Configuring environment
+- OAuth authentication flow
+- Fetching available instances
+
+**Example:**
+```typescript
+const spinner = ora('Creating Next.js project...').start();
+try {
+  await createNextApp(projectName, options);
+  spinner.succeed('Next.js project created');
+} catch (error) {
+  spinner.fail('Failed to create Next.js project');
+  throw error;
+}
+```
+
+---
+
+### 3. Post-Install Verification
+**Priority:** Medium
+**Labels:** enhancement
+
+Add verification checks after project creation to ensure everything is set up correctly.
+
+**Proposed Checks:**
+1. File structure validation
+2. Environment configuration
+3. Dependencies check
+4. Optional build verification (`--verify-build`)
+
+**Output:**
+```
+✓ Verifying project setup...
+  ✓ File structure
+  ✓ Environment configuration
+  ✓ Dependencies
+  ⚠ Build check skipped (use --verify-build)
+
+All checks passed! Your project is ready.
+```
+
+---
+
+### 4. VS Code Workspace Settings
+**Priority:** Medium
+**Labels:** enhancement, good first issue
+
+Include `.vscode/` folder with recommended extensions and settings.
+
+**Files:**
+- `extensions.json` - Recommended extensions (ESLint, Prettier, Tailwind, Claude Code, etc.)
+- `settings.json` - Workspace settings (format on save, etc.)
+- `launch.json` - Debug configurations
+
+**Benefits:**
+- Better DX out of the box
+- Consistent formatting
+- AI tools work better
+
+---
+
+### 5. --yes Flag for CI/CD
+**Priority:** High
+**Labels:** enhancement
+
+Add a `--yes` (or `-y`) flag to skip all prompts for CI/CD use.
+
+**Usage:**
+```bash
+npx create-next-agility-app my-app --yes
+```
+
+**Behavior:**
+- Use all default options
+- Skip Agility CMS connection
+- No interactive prompts
+- Perfect for CI/CD pipelines
+
+**Use Cases:**
+- Automated testing
+- CI/CD pipelines
+- Scripts & automation
+
+---
+
+## 🎨 Nice to Have (v1.2+)
+
+### 6. Example Content Seeding
+**Priority:** Low
+**Labels:** enhancement, nice-to-have
+
+Option to seed Agility CMS instance with example content.
+
+**Flow:**
+```typescript
+{
+  type: 'confirm',
+  name: 'seedContent',
+  message: 'Would you like to add example content to your Agility instance?',
+  default: true
+}
+```
+
+**Content:**
+- Sample pages (Home, About, Contact, Blog)
+- Sample blog posts with categories
+- Sample testimonials/team members
+- Navigation structure
+
+**Benefits:**
+- Instant preview of working site
+- Learn from examples
+- Faster time-to-value
+
+---
+
+### 7. Monorepo Support (Turborepo)
+**Priority:** Low
+**Labels:** enhancement, nice-to-have, advanced
+
+Add option to create project as a monorepo using Turborepo.
+
+**Structure:**
+```
+my-workspace/
+├── apps/
+│   └── web/                 # Next.js + Agility CMS
+├── packages/
+│   ├── ui/                  # Shared components
+│   ├── agility-config/      # Shared Agility config
+│   └── typescript-config/   # Shared TS config
+├── turbo.json
+└── package.json
+```
+
+**Use Cases:**
+- Multi-app projects
+- Shared component libraries
+- Multiple brands, same CMS
+
+---
+
+### 8. 'doctor' Command
+**Priority:** Low
+**Labels:** enhancement, nice-to-have
+
+Add health check command for existing projects.
+
+**Usage:**
+```bash
+npx create-next-agility-app doctor
+```
+
+**Checks:**
+- Environment variables validation
+- API key validation
+- File structure integrity
+- Dependencies status
+- Build health
+- Agility CMS connection
+
+**Output:**
+```
+🔍 Running diagnostics...
+
+Environment Configuration
+  ✓ .env.local exists
+  ✓ Required variables set
+
+Agility CMS Connection
+  ✓ Successfully connected
+  ✓ Instance: my-instance (prod-123)
+
+Summary: 12 checks passed, 3 warnings, 0 errors
+```
+
+---
+
+### 9. CI/CD Templates
+**Priority:** Low
+**Labels:** enhancement, nice-to-have, devops
+
+Include CI/CD workflow templates in generated projects.
+
+**Files:**
+- `.github/workflows/ci.yml` - Run tests on PR
+- `.github/workflows/deploy.yml` - Deploy to production
+- `vercel.json` - Vercel configuration
+
+**Platforms:**
+- GitHub Actions
+- Vercel
+- Future: Netlify, AWS Amplify, Cloudflare Pages
+
+---
+
+### 10. --dry-run Mode
+**Priority:** Low
+**Labels:** enhancement, nice-to-have
+
+Show what would be created without actually creating anything.
+
+**Usage:**
+```bash
+npx create-next-agility-app my-app --dry-run
+```
+
+**Output:**
+```
+🔍 Dry run mode - no files will be created
+
+Project Configuration:
+  Name: my-app
+  TypeScript: Yes
+  Tailwind CSS: Yes
+  ...
+
+Would create:
+  my-app/
+  ├── .env.local
+  ├── app/
+  └── ...
+
+Estimated size: ~350 MB
+Estimated time: 2-3 minutes
+```
+
+---
+
+### 11. --verbose Flag
+**Priority:** Low
+**Labels:** enhancement, nice-to-have
+
+Detailed logging of every operation.
+
+**Usage:**
+```bash
+npx create-next-agility-app my-app --verbose
+```
+
+**Output:**
+```
+[DEBUG] Validating Node.js version: v20.11.0 ✓
+[DEBUG] Checking if directory exists...
+[INFO] Starting Agility CMS authentication...
+[DEBUG] Opening browser for OAuth flow...
+```
+
+**Benefits:**
+- Easier debugging
+- Better issue reports
+- Educational for developers
+
+---
+
+## 📊 Priority Summary
+
+### Must Have (v1.0) - ✅ COMPLETED
+All 5 features implemented and working.
+
+### Should Have (v1.1)
+1. ⭐ Template selection
+2. ⭐ --yes flag (CI/CD critical)
+3. Better progress indicators
+4. Post-install verification
+5. VS Code settings
+
+### Nice to Have (v1.2+)
+- Example content seeding
+- Monorepo support
+- `doctor` command
+- CI/CD templates
+- --dry-run mode
+- --verbose flag
+
+---
+
+## 🤝 Contributing
+
+Want to work on any of these features? Check the labels:
+- `good first issue` - Great for new contributors
+- `enhancement` - New feature
+- `nice-to-have` - Lower priority
+- `advanced` - Requires deeper knowledge
+
+---
+
+**Last Updated:** 2026-01-06

package/README.md

@@ -0,0 +1,205 @@
+# @agility/create-next-app
+
+> **⚠️ Beta**: This project is currently in beta. Features and APIs may change.
+
+Create a new Next.js project with Agility CMS integration for routing and page management.
+
+**✨ Built for AI-assisted development** - Includes comprehensive documentation optimized for Claude Code, Cursor, GitHub Copilot, and all AI coding tools.
+
+## Prerequisites
+
+You need an **Agility CMS instance** to use the generated project. Most users will already have an existing instance with content.
+
+- **Have an existing instance?** You're ready to go! The CLI can connect to your instance during setup.
+- **Need a blank instance?** Contact **support@agilitycms.com** to request one.
+
+## Quick Start
+
+```bash
+npx @agility/create-next-app my-app
+cd my-app
+npm run dev
+```
+
+That's it! The CLI will guide you through connecting to your Agility CMS instance.
+
+## Usage
+
+### Basic Usage
+
+```bash
+npx @agility/create-next-app my-app
+```
+
+This will:
+1. Create a new Next.js project with your specified options
+2. Prompt you: "Do you want to connect to an Agility CMS instance to pull settings?"
+   - If **Yes**: Opens browser for OAuth authentication, then prompts you to select an instance
+   - If **No**: Skips connection (you can configure manually later)
+3. Configure the project with Agility CMS integration
+4. Copy template files for Agility CMS integration
+5. Install Agility packages (`@agility/nextjs` and `@agility/content-fetch`)
+
+### Options
+
+All standard `create-next-app` options are supported:
+
+```bash
+# Create a TypeScript project with Tailwind CSS
+npx @agility/create-next-app my-app --typescript --tailwind
+
+# Create a JavaScript project with App Router
+npx @agility/create-next-app my-app --javascript --app
+
+# Create a project and skip package installation
+npx @agility/create-next-app my-app --skip-install
+```
+
+#### Available Flags
+
+- `--typescript, --ts` - Initialize as a TypeScript project
+- `--javascript, --js` - Initialize as a JavaScript project
+- `--tailwind` - Initialize with Tailwind CSS
+- `--no-tailwind` - Initialize without Tailwind CSS
+- `--eslint` - Initialize with ESLint
+- `--no-eslint` - Initialize without ESLint
+- `--app` - Initialize with App Router
+- `--src-dir` - Initialize with src/ directory
+- `--import-alias <alias>` - Specify import alias (default: @/*)
+- `--use-npm` - Use npm as package manager
+- `--use-pnpm` - Use pnpm as package manager
+- `--use-yarn` - Use yarn as package manager
+- `--use-bun` - Use bun as package manager
+- `--skip-install` - Skip package installation
+
+## What You Get
+
+The generated project includes:
+
+### Project Structure
+
+```
+my-app/
+├── src/
+│   ├── app/
+│   │   ├── api/                  # API routes for Agility CMS
+│   │   │   ├── preview/         # Preview mode endpoints
+│   │   │   ├── revalidate/      # Webhook for cache revalidation
+│   │   │   └── dynamic-redirect/ # Dynamic page redirects
+│   │   └── [locale]/[...slug]/   # Dynamic page routing
+│   ├── components/
+│   │   ├── agility-components/   # Your CMS components go here
+│   │   └── agility-pages/        # Page templates
+│   └── lib/cms/                  # CMS helper functions
+├── .env.local                    # Your Agility credentials
+└── package.json
+```
+
+### Features
+
+- **Next.js 15** with App Router and Server Components
+- **Agility CMS Integration** with type-safe helpers
+- **Multi-locale Support** built-in internationalization
+- **Preview Mode** for viewing draft content
+- **Cache Revalidation** via webhooks
+- **AI-Friendly Documentation** for Claude Code, Cursor, Copilot
+
+### Environment Variables
+
+The `.env.local` file is created with:
+
+```env
+AGILITY_GUID=your-instance-guid
+AGILITY_API_FETCH_KEY=your-fetch-api-key
+AGILITY_API_PREVIEW_KEY=your-preview-api-key
+AGILITY_SECURITY_KEY=your-security-key
+AGILITY_LOCALES=en-us
+AGILITY_SITEMAP=website
+```
+
+### API Routes
+
+- **`/api/preview`** - Enables preview/draft mode
+- **`/api/preview/exit`** - Exits preview mode
+- **`/api/revalidate`** - Webhook for cache revalidation (configure in Agility CMS: Settings > Webhooks)
+- **`/api/dynamic-redirect`** - Redirects dynamic pages by ContentID
+
+## After Project Creation
+
+1. **Start developing:**
+   ```bash
+   cd my-app
+   npm run dev
+   ```
+
+2. **Configure Agility CMS** (if you skipped during setup):
+   - Get your instance GUID from Agility CMS
+   - Generate API keys: Settings > API Keys
+   - Add credentials to `.env.local`
+
+3. **Build with AI assistance:**
+   The generated project includes documentation optimized for AI coding tools. Try prompts like:
+   - "Add a blog listing component with pagination"
+   - "Create a hero section with background image"
+   - "Add a contact form with validation"
+
+4. **Set up webhooks** for cache revalidation:
+   - Agility CMS > Settings > Webhooks
+   - Add webhook pointing to `https://yourdomain.com/api/revalidate`
+
+## Troubleshooting
+
+### Authentication Issues
+If OAuth authentication fails, choose "No" when prompted and manually configure `.env.local` with your Agility credentials.
+
+### Package Installation Fails
+Use `--skip-install` and install manually. Ensure Node.js >= 18.0.0.
+
+### Missing Environment Variables
+Check that `.env.local` exists and contains all required `AGILITY_*` variables.
+
+## Support
+
+- [Agility CMS Documentation](https://agilitycms.com/docs)
+- [Next.js Documentation](https://nextjs.org/docs)
+- [GitHub Issues](https://github.com/agility/create-next-agility-app/issues)
+
+---
+
+## Contributing / Development
+
+The following sections are for contributors to this CLI tool, not for users of the generated projects.
+
+### Local Development
+
+```bash
+git clone https://github.com/agility/create-next-agility-app.git
+cd create-next-agility-app
+npm install
+npm run build  # Compile TypeScript to JavaScript
+npm run dev    # Run with tsx (TypeScript execution)
+```
+
+The CLI is written in TypeScript and compiles to JavaScript in the `dist/` directory.
+
+### Authentication Flow
+
+The CLI uses OAuth 2.0 to authenticate with Agility CMS:
+
+1. Opens a browser window for authentication
+2. Uses these endpoints:
+   - Authorization URL: `https://mgmt.aglty.io/oauth/authorize`
+   - Token URL: `https://mgmt.aglty.io/oauth/token`
+   - Redirect URI: `http://localhost:3001/callback`
+
+### Publishing
+
+```bash
+npm run build
+npm publish --tag beta --access public  # For beta releases
+npm publish --access public             # For stable releases
+```
+
+## License
+
+MIT

package/TESTING.md

@@ -0,0 +1,131 @@
+# Testing Guide
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+npm install
+```
+
+### 2. Build TypeScript (Optional)
+
+If you want to test the compiled version:
+
+```bash
+npm run build
+```
+
+### 3. Test Locally
+
+You have several options:
+
+#### Option A: Use npm link (Recommended)
+
+This creates a global symlink so you can use `create-next-agility-app` from anywhere:
+
+```bash
+# From the project root
+npm link
+
+# Now you can test it from any directory
+cd /tmp
+create-next-agility-app test-app --skip-agility-setup
+```
+
+#### Option B: Run directly with tsx
+
+Run the TypeScript source directly without building:
+
+```bash
+npm run dev my-test-app --skip-agility-setup
+```
+
+Or with tsx directly:
+
+```bash
+npx tsx src/cli.ts my-test-app --skip-agility-setup
+```
+
+#### Option C: Use node with the bin script
+
+```bash
+node bin/create-next-agility-app.js my-test-app --skip-agility-setup
+```
+
+## Testing Scenarios
+
+### Test 1: Basic Project Creation (Skip Agility Setup)
+
+```bash
+create-next-agility-app test-basic --skip-agility-setup --typescript
+```
+
+This will:
+- Create a Next.js project
+- Skip all Agility CMS setup
+- Use TypeScript
+
+### Test 2: Full Flow (Without OAuth)
+
+```bash
+create-next-agility-app test-full --no-login
+```
+
+This will:
+- Create a Next.js project
+- Skip OAuth authentication
+- Prompt for manual API key entry
+- Set up Agility configuration
+
+### Test 3: With Existing Instance GUID
+
+```bash
+create-next-agility-app test-instance --instance-guid your-guid-here --no-login
+```
+
+### Test 4: All Next.js Options
+
+```bash
+create-next-agility-app test-options \
+  --typescript \
+  --tailwind \
+  --eslint \
+  --app \
+  --src-dir \
+  --skip-agility-setup
+```
+
+## Testing OAuth (If Configured)
+
+If you have OAuth credentials set up:
+
+```bash
+export AGILITY_OAUTH_CLIENT_ID=your-client-id
+export AGILITY_OAUTH_CLIENT_SECRET=your-client-secret
+
+create-next-agility-app test-oauth
+```
+
+## Debugging
+
+Run with debug output:
+
+```bash
+DEBUG=1 create-next-agility-app test-app --skip-agility-setup
+```
+
+## Cleaning Up Test Projects
+
+After testing, you can remove test projects:
+
+```bash
+rm -rf test-*
+```
+
+## Unlinking (if you used npm link)
+
+```bash
+npm unlink -g create-next-agility-app
+```
+