Initial commit

2025-11-29 18:48:03 +08:00
commit 79a8dc71a5
14 changed files with 4403 additions and 0 deletions
--- a/commands/sng-add-route.md
+++ b/commands/sng-add-route.md
@@ -0,0 +1,83 @@
+# Add Route Command
+
+You are helping the user add a new route to their frontend application following Sngular's routing best practices.
+
+## Instructions
+
+1. **Detect the framework and routing setup**:
+   - Next.js (App Router or Pages Router)
+   - React Router
+   - Vue Router
+   - Other routing solution
+
+2. **Ask for route details**:
+   - Route path (e.g., `/dashboard`, `/users/:id`)
+   - Route name/title
+   - Whether it requires authentication
+   - Parent route (if nested)
+   - Any route parameters or query params
+
+3. **Determine route type**:
+   - Public route
+   - Protected route (requires authentication)
+   - Nested route
+   - Dynamic route with parameters
+   - Layout route
+
+## Implementation Tasks
+
+### For Next.js App Router:
+1. Create the route directory structure: `app/[route-path]/page.tsx`
+2. Add layout if needed: `app/[route-path]/layout.tsx`
+3. Add loading state: `app/[route-path]/loading.tsx`
+4. Add error boundary: `app/[route-path]/error.tsx`
+5. Add metadata for SEO
+6. Implement the page component
+
+### For Next.js Pages Router:
+1. Create page file in `pages/` directory
+2. Add getServerSideProps or getStaticProps if needed
+3. Configure route in middleware for protection
+
+### For React Router:
+1. Create the page component
+2. Add route configuration in router setup
+3. Add route to navigation
+4. Set up protected route wrapper if needed
+
+### For Vue Router:
+1. Create the view component
+2. Add route configuration in `router/index.ts`
+3. Add route guards if authentication required
+4. Update navigation menu
+
+## Files to Create/Update
+
+1. **Page/View Component**: Main component for the route
+2. **Route Configuration**: Add to routing setup
+3. **Navigation**: Update navigation menu/sidebar
+4. **Breadcrumbs**: Update breadcrumb configuration if used
+5. **Tests**: Add route testing
+6. **Types**: Add route-specific TypeScript types
+
+## Best Practices
+
+- Use proper SEO metadata (title, description, OG tags)
+- Implement loading states
+- Add error boundaries
+- Use code splitting for better performance
+- Add route guards for protected routes
+- Follow consistent naming conventions
+- Add proper TypeScript types for route params
+- Implement skeleton loaders for better UX
+- Add proper ARIA landmarks for accessibility
+
+## Example Outputs
+
+For a dashboard route in Next.js App Router:
+- `app/dashboard/page.tsx` - Main page component
+- `app/dashboard/layout.tsx` - Dashboard layout
+- `app/dashboard/loading.tsx` - Loading state
+- `app/dashboard/error.tsx` - Error boundary
+
+Ask the user: "What route would you like to add to your application?"
--- a/commands/sng-component.md
+++ b/commands/sng-component.md
@@ -0,0 +1,44 @@
+# Component Scaffolding Command
+
+You are helping the user create a new UI component following Sngular's best practices.
+
+## Instructions
+
+1. **Detect the framework**: Analyze the project to determine if it's using React, Next.js, Vue.js, or another framework
+2. **Ask for component details**: Get the component name and any specific requirements from the user
+3. **Determine component type**: Ask if this should be a functional component, class component (React), or composition API (Vue)
+4. **Check for TypeScript**: Verify if the project uses TypeScript
+5. **Create the component file** with:
+   - Proper imports and structure
+   - TypeScript interfaces/types if applicable
+   - Props validation
+   - Basic styling setup (CSS modules, Tailwind, styled-components, etc.)
+   - Accessibility attributes (ARIA labels, semantic HTML)
+   - JSDoc comments
+6. **Create associated files**:
+   - Test file (Jest, Vitest, or framework-specific testing library)
+   - Storybook file if Storybook is detected in the project
+   - CSS/SCSS module if using CSS modules
+7. **Export the component** in the appropriate index file
+
+## Best Practices to Follow
+
+- Use semantic HTML elements
+- Include proper TypeScript types
+- Add accessibility attributes
+- Follow atomic design principles when appropriate
+- Use component composition over inheritance
+- Implement proper error boundaries (React)
+- Add loading and error states when needed
+- Follow the existing naming conventions in the project
+
+## Example Output
+
+For a Button component in React with TypeScript:
+- `components/Button/Button.tsx` - Main component
+- `components/Button/Button.module.css` - Styles
+- `components/Button/Button.test.tsx` - Tests
+- `components/Button/Button.stories.tsx` - Storybook (if applicable)
+- `components/Button/index.ts` - Barrel export
+
+Ask the user: "What component would you like to create?"
--- a/commands/sng-e2e-test.md
+++ b/commands/sng-e2e-test.md
@@ -0,0 +1,388 @@
+# E2E Test Generator with Playwright
+
+You are helping the user create end-to-end tests using Playwright, leveraging the Playwright MCP server for browser automation capabilities.
+
+## Instructions
+
+1. **Detect the testing setup**: Check if Playwright is already configured in the project
+   - Look for `playwright.config.ts` or `playwright.config.js`
+   - Check `package.json` for Playwright dependencies
+   - If not found, offer to set up Playwright
+
+2. **Analyze the application**: Understand the project structure
+   - Detect framework (Next.js, React, Vue.js, etc.)
+   - Identify routes and pages to test
+   - Check for existing test patterns
+
+3. **Ask for test requirements**: Get specific details from the user
+   - What user flow should be tested?
+   - What pages/routes are involved?
+   - What are the critical interactions to verify?
+   - What data/state needs to be set up?
+
+4. **Leverage Playwright MCP tools**: Use the available MCP tools for:
+   - Browser automation
+   - Page navigation
+   - Element interaction
+   - Accessibility snapshot analysis
+   - Screenshot capture (if needed)
+
+5. **Generate comprehensive E2E tests** with:
+   - Proper test structure and organization
+   - Page Object Model (POM) pattern when appropriate
+   - Accessibility checks using Playwright's built-in tools
+   - Visual regression tests if applicable
+   - Mobile viewport testing
+   - Error handling and retry logic
+
+6. **Include test utilities**:
+   - Authentication helpers
+   - Data seeding/cleanup functions
+   - Custom fixtures
+   - Reusable test helpers
+
+## Best Practices to Follow
+
+### Test Organization
+- Group tests by feature or user flow
+- Use descriptive test names that explain the scenario
+- Implement Page Object Model for maintainable tests
+- Keep tests independent and isolated
+
+### Playwright Best Practices
+- Use locators wisely (prefer role-based and accessible selectors)
+- Wait for elements properly (avoid fixed timeouts)
+- Test across multiple browsers when critical
+- Use fixtures for setup/teardown
+- Leverage auto-waiting features
+- Take screenshots on failure
+
+### Accessibility Testing
+- Use Playwright's accessibility tree snapshots
+- Test keyboard navigation
+- Verify ARIA attributes
+- Check focus management
+- Test screen reader compatibility
+
+### Performance & Reliability
+- Run tests in parallel when possible
+- Use headless mode for CI/CD
+- Implement proper error handling
+- Add retry logic for flaky tests
+- Mock external API calls when appropriate
+
+## Example Test Structure
+
+### Basic E2E Test
+```typescript
+import { test, expect } from '@playwright/test'
+
+test.describe('User Authentication Flow', () => {
+  test('user can sign up with valid credentials', async ({ page }) => {
+    await page.goto('/signup')
+
+    // Fill form using accessible selectors
+    await page.getByRole('textbox', { name: /email/i }).fill('user@example.com')
+    await page.getByRole('textbox', { name: /password/i }).fill('SecurePass123!')
+    await page.getByRole('textbox', { name: /confirm password/i }).fill('SecurePass123!')
+
+    // Submit form
+    await page.getByRole('button', { name: /sign up/i }).click()
+
+    // Verify success
+    await expect(page).toHaveURL(/\/dashboard/)
+    await expect(page.getByRole('heading', { name: /welcome/i })).toBeVisible()
+  })
+
+  test('shows validation errors for invalid email', async ({ page }) => {
+    await page.goto('/signup')
+
+    await page.getByRole('textbox', { name: /email/i }).fill('invalid-email')
+    await page.getByRole('button', { name: /sign up/i }).click()
+
+    await expect(page.getByText(/valid email/i)).toBeVisible()
+  })
+})
+```
+
+### Page Object Model Example
+```typescript
+// pages/SignupPage.ts
+import { Page, Locator } from '@playwright/test'
+
+export class SignupPage {
+  readonly page: Page
+  readonly emailInput: Locator
+  readonly passwordInput: Locator
+  readonly confirmPasswordInput: Locator
+  readonly submitButton: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.emailInput = page.getByRole('textbox', { name: /email/i })
+    this.passwordInput = page.getByRole('textbox', { name: /^password$/i })
+    this.confirmPasswordInput = page.getByRole('textbox', { name: /confirm password/i })
+    this.submitButton = page.getByRole('button', { name: /sign up/i })
+  }
+
+  async goto() {
+    await this.page.goto('/signup')
+  }
+
+  async signup(email: string, password: string) {
+    await this.emailInput.fill(email)
+    await this.passwordInput.fill(password)
+    await this.confirmPasswordInput.fill(password)
+    await this.submitButton.click()
+  }
+}
+
+// Usage in test
+test('user can sign up', async ({ page }) => {
+  const signupPage = new SignupPage(page)
+  await signupPage.goto()
+  await signupPage.signup('user@example.com', 'SecurePass123!')
+
+  await expect(page).toHaveURL(/\/dashboard/)
+})
+```
+
+### Accessibility Testing
+```typescript
+import { test, expect } from '@playwright/test'
+import AxeBuilder from '@axe-core/playwright'
+
+test('checkout page should not have accessibility violations', async ({ page }) => {
+  await page.goto('/checkout')
+
+  const accessibilityScanResults = await new AxeBuilder({ page }).analyze()
+
+  expect(accessibilityScanResults.violations).toEqual([])
+})
+
+test('navigation works with keyboard only', async ({ page }) => {
+  await page.goto('/')
+
+  // Tab through navigation
+  await page.keyboard.press('Tab')
+  await expect(page.getByRole('link', { name: /home/i })).toBeFocused()
+
+  await page.keyboard.press('Tab')
+  await expect(page.getByRole('link', { name: /about/i })).toBeFocused()
+
+  // Activate link with Enter
+  await page.keyboard.press('Enter')
+  await expect(page).toHaveURL(/\/about/)
+})
+```
+
+### API Mocking
+```typescript
+test('displays products from API', async ({ page }) => {
+  // Mock API response
+  await page.route('**/api/products', async route => {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([
+        { id: 1, name: 'Product 1', price: 29.99 },
+        { id: 2, name: 'Product 2', price: 39.99 }
+      ])
+    })
+  })
+
+  await page.goto('/products')
+
+  await expect(page.getByText('Product 1')).toBeVisible()
+  await expect(page.getByText('Product 2')).toBeVisible()
+})
+```
+
+### Authentication Setup
+```typescript
+// auth.setup.ts
+import { test as setup } from '@playwright/test'
+
+const authFile = 'playwright/.auth/user.json'
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login')
+  await page.getByRole('textbox', { name: /email/i }).fill('user@example.com')
+  await page.getByRole('textbox', { name: /password/i }).fill('password123')
+  await page.getByRole('button', { name: /log in/i }).click()
+
+  await page.waitForURL('/dashboard')
+
+  // Save authentication state
+  await page.context().storageState({ path: authFile })
+})
+
+// Use in tests
+test.use({ storageState: authFile })
+```
+
+## File Structure
+
+```
+tests/
+├── e2e/
+│   ├── auth/
+│   │   ├── signup.spec.ts
+│   │   └── login.spec.ts
+│   ├── checkout/
+│   │   └── checkout-flow.spec.ts
+│   └── navigation/
+│       └── main-nav.spec.ts
+├── fixtures/
+│   ├── auth.ts
+│   └── data.ts
+├── pages/
+│   ├── SignupPage.ts
+│   ├── LoginPage.ts
+│   └── DashboardPage.ts
+└── utils/
+    ├── test-helpers.ts
+    └── mock-data.ts
+```
+
+## Playwright Configuration Example
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+
+  use: {
+    baseURL: 'http://localhost:3000',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+  },
+
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /.*\.setup\.ts/,
+    },
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'Mobile Chrome',
+      use: { ...devices['Pixel 5'] },
+      dependencies: ['setup'],
+    },
+  ],
+
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+  },
+})
+```
+
+## Test Checklist
+
+For each critical user flow, ensure tests cover:
+- [ ] Happy path (successful completion)
+- [ ] Error handling (validation, network errors)
+- [ ] Edge cases (empty states, long content)
+- [ ] Accessibility (keyboard navigation, ARIA)
+- [ ] Mobile responsiveness
+- [ ] Loading states
+- [ ] Authentication flows
+- [ ] Cross-browser compatibility
+
+## Common Test Scenarios
+
+1. **Authentication Flows**: Login, signup, logout, password reset
+2. **Forms**: Validation, submission, error handling
+3. **Navigation**: Links, routing, breadcrumbs
+4. **E-commerce**: Product browsing, cart, checkout
+5. **Data Tables**: Sorting, filtering, pagination
+6. **Modals/Dialogs**: Open, close, form submission
+7. **File Uploads**: Single/multiple files, drag-and-drop
+8. **Real-time Updates**: WebSocket connections, polling
+
+## Security Testing Considerations
+
+- Test authentication boundaries
+- Verify protected routes
+- Check XSS prevention
+- Test CSRF protection
+- Validate input sanitization
+- Test rate limiting (if applicable)
+
+## CI/CD Integration
+
+```yaml
+# Example GitHub Actions workflow
+name: Playwright Tests
+on:
+  push:
+    branches: [ main, dev ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - name: Install dependencies
+        run: npm ci
+      - name: Install Playwright Browsers
+        run: npx playwright install --with-deps
+      - name: Run Playwright tests
+        run: npx playwright test
+      - uses: actions/upload-artifact@v3
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+## Output Format
+
+When generating E2E tests, provide:
+1. Complete test files with proper imports
+2. Page Object Models if multiple tests use same pages
+3. Test fixtures and utilities as needed
+4. Playwright configuration if not present
+5. Clear comments explaining complex interactions
+6. Instructions for running the tests
+7. CI/CD integration suggestions
+
+## Getting Started
+
+Ask the user: "What user flow or feature would you like to create E2E tests for?"
+
+Once you understand the requirements, use the Playwright MCP tools to:
+1. Navigate to the relevant pages
+2. Analyze the page structure
+3. Generate appropriate test code
+4. Verify accessibility
+5. Create comprehensive test coverage
--- a/commands/sng-setup-frontend.md
+++ b/commands/sng-setup-frontend.md
@@ -0,0 +1,78 @@
+# Frontend Project Setup Command
+
+You are helping the user initialize or configure a frontend project with Sngular's best practices and standards.
+
+## Instructions
+
+1. **Detect existing setup**: Check if this is a new project or an existing one that needs configuration
+2. **Ask for framework choice**: If starting fresh, ask which framework to use:
+   - React with Vite
+   - Next.js (App Router or Pages Router)
+   - Vue.js 3 with Vite
+   - Other framework
+3. **Determine configuration needs**:
+   - TypeScript (strongly recommended)
+   - Linting (ESLint with Sngular config)
+   - Code formatting (Prettier)
+   - CSS approach (Tailwind, CSS Modules, Styled Components, SCSS)
+   - State management (Redux Toolkit, Zustand, Pinia for Vue)
+   - Testing setup (Vitest, Jest, React Testing Library)
+   - Git hooks (Husky with lint-staged)
+
+## Setup Tasks
+
+1. **Initialize the project** (if new):
+   - Run appropriate create command (create-next-app, create-vite, etc.)
+   - Set up TypeScript configuration
+
+2. **Install and configure tools**:
+   - ESLint with recommended rules
+   - Prettier with Sngular formatting standards
+   - Git hooks for pre-commit linting
+
+3. **Create project structure**:
+   ```
+   src/
+   ├── components/
+   │   ├── common/
+   │   ├── layout/
+   │   └── features/
+   ├── hooks/
+   ├── utils/
+   ├── types/
+   ├── styles/
+   ├── services/
+   └── constants/
+   ```
+
+4. **Add configuration files**:
+   - `.eslintrc.json` - Linting rules
+   - `.prettierrc` - Formatting rules
+   - `tsconfig.json` - TypeScript config
+   - `.gitignore` - Git ignore patterns
+   - `.env.example` - Environment variables template
+
+5. **Create base files**:
+   - Global styles
+   - Theme configuration
+   - Common types/interfaces
+   - Utility functions
+   - API client setup
+
+6. **Install recommended dependencies**:
+   - Utility libraries (clsx, date-fns)
+   - Form handling (react-hook-form, vee-validate for Vue)
+   - HTTP client (axios)
+   - Icons library
+
+## Best Practices
+
+- Always use TypeScript
+- Enable strict mode in TypeScript
+- Set up path aliases (@/ for src/)
+- Configure absolute imports
+- Add bundle analyzer for production builds
+- Set up environment-specific configurations
+- Include README with setup instructions
+
+Ask the user: "Are you setting up a new project or configuring an existing one?"