Initial commit

skills/devops/react-project-scaffolder/modes/enterprise-mode.md

@@ -0,0 +1,922 @@
+# Enterprise Mode - Next.js + Full Tooling
+
+## Mode Overview
+
+**Purpose**: Production-ready web applications with comprehensive tooling and testing
+
+**Target Users**:
+- Building SaaS products
+- Enterprise dashboards and admin panels
+- Content-heavy websites with SEO needs
+- Applications requiring server-side rendering
+- Teams needing consistent standards
+
+**Setup Time**: ~60 seconds (after npm install)
+
+**Philosophy**: Production-ready from day one. Industry-standard tooling with Connor's quality standards built in.
+
+---
+
+## Tech Stack
+
+```yaml
+Framework:
+  - Next.js 14+ (App Router, React Server Components)
+  - React 18+
+  - TypeScript 5+ (strict mode)
+
+Testing:
+  - Vitest (Testing Trophy approach)
+  - React Testing Library
+  - jsdom (DOM simulation)
+  - 80% coverage threshold
+
+Code Quality:
+  - ESLint (Next.js config + strict rules)
+  - Prettier (consistent formatting)
+  - Husky (pre-commit hooks)
+  - lint-staged (staged files only)
+
+CI/CD:
+  - GitHub Actions
+  - Automated testing on PR
+  - Build validation
+  - Type checking
+
+Standards:
+  - Conventional Commits
+  - Branch naming conventions
+  - Comprehensive documentation
+```
+
+---
+
+## Workflow
+
+### Step 1: Validate Prerequisites
+
+```bash
+# Check Node.js version (>= 18)
+node --version
+
+# Check npm version (>= 9)
+npm --version
+
+# Check git is installed
+git --version
+```
+
+**If validation fails**: Provide clear upgrade instructions with links
+
+### Step 2: Ask Configuration Questions
+
+Only ask essential questions with smart defaults:
+
+**Question 1: Project Name**
+- "What should I name your project?"
+- Validation: kebab-case, 3-50 chars, no existing directory
+- Example: my-awesome-app
+
+**Question 2: Testing Setup**
+- "Include testing infrastructure? (Vitest + React Testing Library)"
+- Default: YES
+- Explain: "Recommended for production apps. Adds ~30s to setup."
+
+**Question 3: CI/CD Workflows**
+- "Include GitHub Actions CI/CD?"
+- Default: YES
+- Explain: "Automated testing on every PR. Requires GitHub repository."
+
+**Question 4: Source Directory**
+- "Use src/ directory for better organization?"
+- Default: YES
+- Explain: "Keeps root clean. Next.js best practice."
+
+### Step 3: Scaffold with Next.js
+
+```bash
+npx create-next-app@latest {project-name} \
+  --typescript \
+  --eslint \
+  --app \
+  --src-dir \
+  --import-alias "@/*" \
+  --no-tailwind
+
+cd {project-name}
+```
+
+**Why these flags?**
+- `--typescript`: Connor requires TypeScript
+- `--eslint`: Linting from start
+- `--app`: Use App Router (modern approach)
+- `--src-dir`: Clean project structure
+- `--import-alias`: Absolute imports with @/
+- `--no-tailwind`: Let user choose styling (can add later)
+
+### Step 4: Apply Connor's TypeScript Standards
+
+Update `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    },
+
+    /* Connor's Strict Mode Additions */
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+```
+
+### Step 5: Set Up Testing (if selected)
+
+**5.1 Install Dependencies**
+
+```bash
+npm install -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event @vitest/coverage-v8
+```
+
+**5.2 Create `vitest.config.ts`**
+
+```typescript
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: './src/__tests__/setup.ts',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html'],
+      exclude: [
+        'node_modules/',
+        'src/__tests__/',
+        '**/*.config.ts',
+        '**/*.config.js',
+        '.next/',
+      ],
+      // Connor's 80% threshold
+      lines: 80,
+      functions: 80,
+      branches: 80,
+      statements: 80,
+    },
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+});
+```
+
+**5.3 Create Test Setup File**
+
+`src/__tests__/setup.ts`:
+
+```typescript
+import '@testing-library/jest-dom';
+import { cleanup } from '@testing-library/react';
+import { afterEach } from 'vitest';
+
+// Cleanup after each test
+afterEach(() => {
+  cleanup();
+});
+```
+
+**5.4 Create Example Test**
+
+`src/__tests__/page.test.tsx`:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import Page from '@/app/page';
+
+describe('Home Page', () => {
+  it('should render welcome message when page loads', () => {
+    render(<Page />);
+
+    // Testing Trophy approach: Test user-visible behavior
+    const heading = screen.getByRole('heading', { level: 1 });
+    expect(heading).toBeInTheDocument();
+  });
+
+  it('should have semantic HTML structure for accessibility', () => {
+    const { container } = render(<Page />);
+
+    // Check for main landmark
+    const main = container.querySelector('main');
+    expect(main).toBeInTheDocument();
+  });
+});
+```
+
+**5.5 Update package.json Scripts**
+
+Add to `scripts`:
+
+```json
+{
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "type-check": "tsc --noEmit",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --coverage",
+    "test:low": "vitest --maxWorkers=2 --run",
+    "test:ui": "vitest --ui"
+  }
+}
+```
+
+### Step 6: Configure Code Quality Tools
+
+**6.1 Extend ESLint Configuration**
+
+Update `.eslintrc.json`:
+
+```json
+{
+  "extends": [
+    "next/core-web-vitals",
+    "plugin:@typescript-eslint/recommended"
+  ],
+  "rules": {
+    "no-console": "warn",
+    "no-var": "error",
+    "eqeqeq": ["error", "always"],
+    "prefer-const": "error",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      { "argsIgnorePattern": "^_" }
+    ],
+    "@typescript-eslint/no-explicit-any": "error"
+  }
+}
+```
+
+**6.2 Add Prettier**
+
+Create `.prettierrc`:
+
+```json
+{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false
+}
+```
+
+Create `.prettierignore`:
+
+```
+node_modules
+.next
+out
+build
+dist
+coverage
+*.lock
+```
+
+Install Prettier:
+
+```bash
+npm install -D prettier eslint-config-prettier
+```
+
+Update `.eslintrc.json` to include Prettier:
+
+```json
+{
+  "extends": [
+    "next/core-web-vitals",
+    "plugin:@typescript-eslint/recommended",
+    "prettier"
+  ]
+}
+```
+
+**6.3 Set Up Husky + lint-staged**
+
+```bash
+npx husky-init && npm install
+npm install -D lint-staged
+```
+
+Update `.husky/pre-commit`:
+
+```bash
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+npx lint-staged
+```
+
+Create `.lintstagedrc.js`:
+
+```javascript
+module.exports = {
+  '*.{ts,tsx}': [
+    'eslint --fix',
+    'prettier --write',
+    () => 'tsc --noEmit', // Type check
+  ],
+  '*.{json,md}': ['prettier --write'],
+};
+```
+
+Update `package.json`:
+
+```json
+{
+  "scripts": {
+    "prepare": "husky install"
+  }
+}
+```
+
+### Step 7: Set Up CI/CD (if selected)
+
+Create `.github/workflows/ci.yml`:
+
+```yaml
+name: CI
+
+on:
+  pull_request:
+    branches: [main, develop]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run linter
+        run: npm run lint
+
+      - name: Type check
+        run: npm run type-check
+
+      - name: Run tests
+        run: npm run test:coverage
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v3
+        if: matrix.node-version == '20.x'
+        with:
+          file: ./coverage/coverage-final.json
+          flags: unittests
+
+      - name: Build project
+        run: npm run build
+        env:
+          NODE_ENV: production
+```
+
+### Step 8: Create Project Documentation
+
+**8.1 Update README.md**
+
+```markdown
+# {project-name}
+
+Production-ready Next.js application with comprehensive testing and tooling.
+
+## Features
+
+- ⚡ Next.js 14+ with App Router
+- 🔷 TypeScript (strict mode)
+- 🧪 Testing Trophy approach (Vitest + RTL)
+- ✅ 80% test coverage threshold
+- 🎨 ESLint + Prettier
+- 🪝 Husky pre-commit hooks
+- 🔄 GitHub Actions CI/CD
+- 📝 Conventional Commits
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+
+### Installation
+
+\`\`\`bash
+npm install
+\`\`\`
+
+### Development
+
+\`\`\`bash
+npm run dev
+\`\`\`
+
+Visit [http://localhost:3000](http://localhost:3000)
+
+## Project Structure
+
+\`\`\`
+src/
+├── app/                    # Next.js App Router
+│   ├── page.tsx            # Home page
+│   ├── layout.tsx          # Root layout
+│   └── globals.css         # Global styles
+├── components/             # React components
+│   ├── ui/                 # UI components
+│   └── features/           # Feature components
+├── lib/                    # Utility functions
+│   └── utils.ts
+└── __tests__/              # Test files
+    ├── setup.ts            # Test configuration
+    └── page.test.tsx       # Example test
+\`\`\`
+
+## Available Commands
+
+### Development
+- \`npm run dev\` - Start dev server (http://localhost:3000)
+- \`npm run build\` - Build for production
+- \`npm run start\` - Start production server
+
+### Code Quality
+- \`npm run lint\` - Lint code with ESLint
+- \`npm run type-check\` - Check TypeScript types
+
+### Testing
+- \`npm run test\` - Run all tests
+- \`npm run test:watch\` - Run tests in watch mode
+- \`npm run test:coverage\` - Run tests with coverage report
+- \`npm run test:low\` - Run tests (low CPU usage)
+
+## Testing Strategy
+
+This project follows the **Testing Trophy** approach:
+
+- **70% Integration Tests**: User workflows and component interactions
+- **20% Unit Tests**: Complex business logic
+- **10% E2E Tests**: Critical user journeys
+
+### Writing Tests
+
+Test file naming: \`[component-name].test.tsx\`
+
+Test structure:
+\`\`\`typescript
+describe('Component Name', () => {
+  it('should [behavior] when [condition]', () => {
+    // Arrange, Act, Assert
+  });
+});
+\`\`\`
+
+Use semantic queries (React Testing Library):
+1. \`getByRole()\` - Most preferred
+2. \`getByLabelText()\` - Form elements
+3. \`getByText()\` - User-visible content
+4. \`getByTestId()\` - Last resort only
+
+### Coverage Requirements
+
+Minimum 80% coverage for:
+- Lines
+- Functions
+- Branches
+- Statements
+
+## Git Workflow
+
+### Branch Naming
+
+- \`feature/description\` - New features
+- \`bugfix/description\` - Bug fixes
+- \`chore/description\` - Maintenance tasks
+
+### Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+\`\`\`
+feat: add user authentication
+fix: resolve login redirect issue
+test: add tests for auth flow
+docs: update API documentation
+chore: update dependencies
+\`\`\`
+
+### Pre-commit Checks
+
+Husky automatically runs before each commit:
+- ESLint (auto-fix enabled)
+- Prettier (auto-format)
+- TypeScript type checking
+- Staged files only (fast)
+
+## Deployment
+
+### Vercel (Recommended)
+
+\`\`\`bash
+npm install -g vercel
+vercel
+\`\`\`
+
+### Docker
+
+\`\`\`bash
+docker build -t {project-name} .
+docker run -p 3000:3000 {project-name}
+\`\`\`
+
+## Environment Variables
+
+Create \`.env.local\`:
+
+\`\`\`env
+# Example variables
+NEXT_PUBLIC_API_URL=https://api.example.com
+DATABASE_URL=postgresql://...
+\`\`\`
+
+## CI/CD
+
+GitHub Actions runs on every PR:
+1. Install dependencies
+2. Lint code
+3. Type check
+4. Run tests with coverage
+5. Build project
+
+## Tech Stack Details
+
+### Why Next.js?
+- Server-side rendering for SEO
+- API routes for backend logic
+- Optimized image handling
+- Industry standard (Netflix, TikTok)
+
+### Why Vitest?
+- 10x faster than Jest
+- Compatible with Vite
+- Great TypeScript support
+- Modern testing features
+
+## Contributing
+
+1. Create a feature branch
+2. Make changes with tests
+3. Ensure all checks pass
+4. Submit PR with description
+
+## License
+
+MIT
+
+---
+
+Built with [react-project-scaffolder](https://github.com/yourusername/react-project-scaffolder)
+```
+
+**8.2 Create CONTRIBUTING.md**
+
+```markdown
+# Contributing Guidelines
+
+## Development Standards
+
+### Code Quality
+- TypeScript strict mode (all flags enabled)
+- No \`console.log\` in production code
+- No \`any\` types
+- Explicit return types for functions
+
+### Testing
+- Write tests for new features
+- Maintain 80% coverage minimum
+- Follow Testing Trophy approach
+- Use semantic queries in tests
+
+### Commits
+- Follow Conventional Commits format
+- Keep commits atomic and focused
+- Write descriptive commit messages
+
+## Development Workflow
+
+1. **Create branch**: \`git checkout -b feature/your-feature\`
+2. **Make changes**: Edit code + add tests
+3. **Run checks**: \`npm run lint && npm run test\`
+4. **Commit**: \`git commit -m "feat: your feature"\`
+5. **Push**: \`git push origin feature/your-feature\`
+6. **Create PR**: Submit for review
+
+## Pre-commit Checks
+
+Husky runs these automatically:
+- ESLint (fixes issues automatically)
+- Prettier (formats code)
+- TypeScript (type checking)
+
+If checks fail, fix issues before committing.
+
+## Testing Guidelines
+
+### What to Test
+- User-visible behavior
+- Business logic
+- Error handling
+- Edge cases
+
+### What NOT to Test
+- Implementation details
+- External libraries
+- Trivial functions
+
+### Example Test
+
+\`\`\`typescript
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { LoginForm } from './LoginForm';
+
+describe('LoginForm', () => {
+  it('should submit form when user enters valid credentials', async () => {
+    const user = userEvent.setup();
+    const onSubmit = vi.fn();
+
+    render(<LoginForm onSubmit={onSubmit} />);
+
+    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
+    await user.type(screen.getByLabelText(/password/i), 'password123');
+    await user.click(screen.getByRole('button', { name: /submit/i }));
+
+    expect(onSubmit).toHaveBeenCalledWith({
+      email: 'test@example.com',
+      password: 'password123',
+    });
+  });
+});
+\`\`\`
+
+## Questions?
+
+Open an issue or reach out to the maintainers.
+```
+
+### Step 9: Initialize Git
+
+```bash
+git init
+git add .
+git commit -m "feat: initial Next.js enterprise setup with testing and CI/CD
+
+- Next.js 14 with App Router
+- TypeScript strict mode
+- Vitest + React Testing Library (80% coverage)
+- ESLint + Prettier + Husky
+- GitHub Actions CI/CD
+- Comprehensive documentation"
+```
+
+### Step 10: Verify Setup
+
+```bash
+# Verify all files
+ls -la
+
+# Check dependencies installed
+npm list --depth=0
+
+# Verify TypeScript config
+cat tsconfig.json | grep "strict"
+
+# Verify tests can run
+npm run test
+
+# Verify build works
+npm run build
+```
+
+### Step 11: Provide User Instructions
+
+**Display to user**:
+
+```markdown
+✅ Enterprise project "{project-name}" created successfully!
+
+📁 Location: ./{project-name}
+
+🚀 Next steps:
+
+  1. cd {project-name}
+  2. npm install
+  3. npm run dev
+
+Your dev server will start at http://localhost:3000
+
+📚 What you have:
+  ✓ Next.js 14 with App Router
+  ✓ TypeScript strict mode
+  ✓ Vitest + React Testing Library (80% coverage)
+  ✓ ESLint + Prettier + Husky
+  ✓ GitHub Actions CI/CD
+  ✓ Testing Trophy approach
+  ✓ Comprehensive documentation
+
+🧪 Test your setup:
+  npm run test           # Run all tests
+  npm run lint           # Check code quality
+  npm run type-check     # Verify types
+
+📋 Pre-commit hooks active:
+  - Linting (auto-fix)
+  - Formatting (auto-format)
+  - Type checking
+
+🔄 CI/CD ready:
+  - Push to GitHub to activate workflows
+  - Automated testing on every PR
+
+💡 Tips:
+  - Follow Testing Trophy: 70% integration, 20% unit, 10% e2e
+  - Use semantic queries: getByRole() > getByLabelText() > getByText()
+  - Write tests alongside features (TDD approach)
+  - Keep commits following Conventional Commits format
+
+📖 Documentation:
+  - README.md - Project overview and commands
+  - CONTRIBUTING.md - Development guidelines
+
+🎯 Production-ready from day one!
+```
+
+---
+
+## File Structure Output
+
+```
+{project-name}/
+├── .github/
+│   └── workflows/
+│       └── ci.yml              # GitHub Actions CI/CD
+├── .husky/
+│   └── pre-commit              # Pre-commit hooks
+├── .vscode/ (optional)
+│   └── settings.json           # Editor config
+├── src/
+│   ├── app/
+│   │   ├── page.tsx            # Home page
+│   │   ├── layout.tsx          # Root layout
+│   │   ├── globals.css         # Global styles
+│   │   └── favicon.ico         # Favicon
+│   ├── components/
+│   │   ├── ui/                 # UI components
+│   │   └── features/           # Feature components
+│   ├── lib/
+│   │   └── utils.ts            # Utilities
+│   └── __tests__/
+│       ├── setup.ts            # Test setup
+│       └── page.test.tsx       # Example test
+├── public/                     # Static files
+├── .eslintrc.json              # ESLint config
+├── .prettierrc                 # Prettier config
+├── .prettierignore             # Prettier ignore
+├── .gitignore                  # Git ignore
+├── .lintstagedrc.js            # lint-staged config
+├── vitest.config.ts            # Vitest config
+├── tsconfig.json               # TypeScript config
+├── next.config.js              # Next.js config
+├── package.json                # Dependencies
+├── README.md                   # Documentation
+└── CONTRIBUTING.md             # Guidelines
+```
+
+---
+
+## Success Criteria
+
+- [ ] Next.js project scaffolded with App Router
+- [ ] TypeScript strict mode enabled (all flags)
+- [ ] Vitest + RTL configured with 80% threshold
+- [ ] Example test passes
+- [ ] ESLint + Prettier configured
+- [ ] Husky pre-commit hooks working
+- [ ] GitHub Actions workflow created
+- [ ] README and CONTRIBUTING.md generated
+- [ ] Git initialized with commit
+- [ ] `npm run dev` starts successfully
+- [ ] `npm run test` passes
+- [ ] `npm run build` completes
+- [ ] Setup time < 90 seconds (excluding npm install)
+
+---
+
+## Troubleshooting
+
+**Issue**: Husky pre-commit hook fails
+**Solution**: Run `npm run lint -- --fix` to auto-fix issues
+
+**Issue**: Tests fail with module resolution errors
+**Solution**: Check vitest.config.ts has correct path aliases
+
+**Issue**: Type errors in strict mode
+**Solution**: This shouldn't happen - review generated code
+
+**Issue**: Build fails
+**Solution**: Run `npm run type-check` to see TypeScript errors
+
+**Issue**: Coverage below 80%
+**Solution**: Add more tests or adjust threshold temporarily
+
+---
+
+## Why This Tech Stack?
+
+**Next.js over Vite**:
+- Server-side rendering for SEO
+- Built-in routing
+- API routes for backend
+- Image optimization
+- Battle-tested at scale (Netflix, Uber)
+
+**Vitest over Jest**:
+- 10x faster test execution
+- Better TypeScript support
+- Modern ESM support
+- Compatible with Vite ecosystem
+
+**Husky + lint-staged**:
+- Catch issues before commit
+- Fast (only staged files)
+- Team consistency
+- Industry standard
+
+**GitHub Actions**:
+- Free for public repos
+- Integrated with GitHub
+- Easy to configure
+- Extensive marketplace
+
+---
+
+**Remember**: This mode is production-ready. Every tool included is standard in industry and aligned with Connor's "production-ready from day one" philosophy.