@nextsparkjs/ai-workflow 0.1.0-beta.86

package/claude/skills/plugins/references/plugin-testing.md

@@ -0,0 +1,353 @@
+# Plugin Testing Reference
+
+Testing patterns for plugins: unit tests, E2E tests, and Page Object Models.
+
+## Unit Tests (Jest)
+
+### Core Plugin Logic
+
+```typescript
+// contents/plugins/my-plugin/__tests__/my-plugin.test.ts
+import { MyPluginCore } from '../lib/core'
+
+describe('MyPluginCore', () => {
+  let core: MyPluginCore
+
+  beforeEach(() => {
+    core = new MyPluginCore({
+      apiKey: 'test-key',
+      timeout: 5000,
+      maxRetries: 3
+    })
+  })
+
+  describe('initialization', () => {
+    it('should initialize with valid config', async () => {
+      await expect(core.initialize()).resolves.not.toThrow()
+    })
+
+    it('should throw with invalid config', async () => {
+      const invalid = new MyPluginCore({ apiKey: '' })
+      await expect(invalid.initialize()).rejects.toThrow()
+    })
+  })
+
+  describe('processing', () => {
+    it('should process valid input', async () => {
+      await core.initialize()
+      const result = await core.process({ data: 'test' })
+      expect(result.success).toBe(true)
+    })
+
+    it('should handle errors gracefully', async () => {
+      await core.initialize()
+      const result = await core.process({ data: '' })
+      expect(result.success).toBe(false)
+      expect(result.error).toBeDefined()
+    })
+  })
+})
+```
+
+### Hook Testing
+
+```typescript
+// contents/plugins/my-plugin/__tests__/hooks.test.ts
+import { renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { useMyPlugin } from '../hooks/useMyPlugin'
+
+const createWrapper = () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } }
+  })
+  return ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  )
+}
+
+describe('useMyPlugin', () => {
+  beforeEach(() => {
+    global.fetch = jest.fn()
+  })
+
+  it('should fetch data successfully', async () => {
+    (global.fetch as jest.Mock).mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ data: 'test' })
+    })
+
+    const { result } = renderHook(() => useMyPlugin(), {
+      wrapper: createWrapper()
+    })
+
+    await waitFor(() => {
+      expect(result.current.isSuccess).toBe(true)
+    })
+
+    expect(result.current.data).toEqual({ data: 'test' })
+  })
+
+  it('should handle fetch error', async () => {
+    (global.fetch as jest.Mock).mockResolvedValueOnce({
+      ok: false
+    })
+
+    const { result } = renderHook(() => useMyPlugin(), {
+      wrapper: createWrapper()
+    })
+
+    await waitFor(() => {
+      expect(result.current.isError).toBe(true)
+    })
+  })
+})
+```
+
+### Component Testing
+
+```typescript
+// contents/plugins/my-plugin/__tests__/MyWidget.test.tsx
+import { render, screen, fireEvent } from '@testing-library/react'
+import { MyWidget } from '../components/MyWidget'
+
+// Mock the hook
+jest.mock('../hooks/useMyPlugin', () => ({
+  useMyPlugin: () => ({
+    data: { value: 'test data' },
+    isLoading: false,
+    error: null
+  })
+}))
+
+describe('MyWidget', () => {
+  it('should render widget with title', () => {
+    render(<MyWidget title="Test Title" />)
+    expect(screen.getByText('Test Title')).toBeInTheDocument()
+  })
+
+  it('should display content when data is loaded', () => {
+    render(<MyWidget title="Test" />)
+    expect(screen.getByTestId('my-plugin-content')).toBeInTheDocument()
+  })
+
+  it('should call onAction when button is clicked', () => {
+    const onAction = jest.fn()
+    render(<MyWidget title="Test" onAction={onAction} />)
+
+    fireEvent.click(screen.getByTestId('my-plugin-action-btn'))
+    expect(onAction).toHaveBeenCalledTimes(1)
+  })
+})
+```
+
+---
+
+## E2E Tests (Cypress)
+
+### Basic E2E Test
+
+```typescript
+// contents/themes/default/tests/cypress/e2e/uat/my-plugin.cy.ts
+import { MyPluginPOM } from '../../src/features/MyPluginPOM'
+
+describe('My Plugin E2E', {
+  tags: ['@uat', '@feat-my-plugin', '@smoke']
+}, () => {
+  let pom: MyPluginPOM
+
+  beforeEach(() => {
+    cy.session('plugin-test', () => {
+      cy.login('testuser@example.com', 'password123')
+    })
+    cy.visit('/dashboard')
+    pom = new MyPluginPOM()
+  })
+
+  it('should display plugin widget', () => {
+    pom.shouldBeVisible()
+    pom.shouldHaveTitle('My Plugin')
+  })
+
+  it('should complete full workflow', () => {
+    pom.shouldBeVisible()
+    pom.enterData('test data')
+    pom.clickProcessButton()
+    pom.shouldShowSuccess()
+  })
+
+  it('should handle errors gracefully', () => {
+    pom.enterData('')  // Invalid input
+    pom.clickProcessButton()
+    pom.shouldShowError('Validation error')
+  })
+})
+```
+
+### Page Object Model
+
+```typescript
+// contents/themes/default/tests/cypress/src/features/MyPluginPOM.ts
+import { BasePOM } from '../BasePOM'
+
+export class MyPluginPOM extends BasePOM {
+  private selectors = {
+    widget: '[data-cy="my-plugin-widget"]',
+    title: '[data-cy="my-plugin-title"]',
+    input: '[data-cy="my-plugin-input"]',
+    processBtn: '[data-cy="my-plugin-action-btn"]',
+    loading: '[data-cy="my-plugin-loading"]',
+    success: '[data-cy="my-plugin-success"]',
+    error: '[data-cy="my-plugin-error"]',
+    content: '[data-cy="my-plugin-content"]'
+  }
+
+  // Assertions
+  shouldBeVisible() {
+    cy.get(this.selectors.widget).should('be.visible')
+    return this
+  }
+
+  shouldHaveTitle(title: string) {
+    cy.get(this.selectors.title).should('contain', title)
+    return this
+  }
+
+  shouldShowSuccess() {
+    cy.get(this.selectors.success).should('be.visible')
+    return this
+  }
+
+  shouldShowError(message: string) {
+    cy.get(this.selectors.error)
+      .should('be.visible')
+      .and('contain', message)
+    return this
+  }
+
+  shouldShowLoading() {
+    cy.get(this.selectors.loading).should('be.visible')
+    return this
+  }
+
+  // Actions
+  enterData(data: string) {
+    cy.get(this.selectors.input).clear().type(data)
+    return this
+  }
+
+  clickProcessButton() {
+    cy.get(this.selectors.processBtn).click()
+    return this
+  }
+
+  // Waits
+  waitForLoading() {
+    cy.get(this.selectors.loading).should('not.exist')
+    return this
+  }
+
+  waitForContent() {
+    cy.get(this.selectors.content).should('be.visible')
+    return this
+  }
+}
+```
+
+---
+
+## API Tests (Cypress)
+
+```typescript
+// contents/themes/default/tests/cypress/e2e/api/my-plugin-api.cy.ts
+import { BaseAPIController } from '../../src/controllers/BaseAPIController'
+
+describe('My Plugin API', {
+  tags: ['@api', '@feat-my-plugin']
+}, () => {
+  const BASE_URL = Cypress.env('API_URL')
+  const API_KEY = Cypress.env('SUPERADMIN_API_KEY')
+  let api: BaseAPIController
+
+  before(() => {
+    api = new BaseAPIController(BASE_URL, API_KEY)
+  })
+
+  describe('POST /api/plugin/my-plugin/process', () => {
+    it('should process valid input', () => {
+      cy.request({
+        method: 'POST',
+        url: `${BASE_URL}/api/plugin/my-plugin/process`,
+        headers: {
+          'Authorization': `Bearer ${API_KEY}`,
+          'Content-Type': 'application/json'
+        },
+        body: {
+          data: 'test input'
+        }
+      }).then((response) => {
+        expect(response.status).to.eq(200)
+        expect(response.body.success).to.be.true
+        expect(response.body.data).to.exist
+      })
+    })
+
+    it('should reject invalid input', () => {
+      cy.request({
+        method: 'POST',
+        url: `${BASE_URL}/api/plugin/my-plugin/process`,
+        headers: {
+          'Authorization': `Bearer ${API_KEY}`,
+          'Content-Type': 'application/json'
+        },
+        body: {
+          data: ''  // Invalid
+        },
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(400)
+        expect(response.body.success).to.be.false
+      })
+    })
+
+    it('should require authentication', () => {
+      cy.request({
+        method: 'POST',
+        url: `${BASE_URL}/api/plugin/my-plugin/process`,
+        body: { data: 'test' },
+        failOnStatusCode: false
+      }).then((response) => {
+        expect(response.status).to.eq(401)
+      })
+    })
+  })
+})
+```
+
+---
+
+## Coverage Requirements
+
+| Test Type | Minimum Coverage | Target |
+|-----------|------------------|--------|
+| Unit Tests (Jest) | 80% | 90% |
+| E2E Tests (Cypress) | Critical paths | Happy + Error paths |
+| API Tests | All endpoints | All methods + auth |
+
+### Running Tests
+
+```bash
+# Unit tests
+pnpm test --filter=@nextsparkjs/plugin-my-plugin
+
+# E2E tests
+pnpm cypress:run --spec "**/my-plugin.cy.ts"
+
+# API tests
+pnpm cypress:run --spec "**/my-plugin-api.cy.ts"
+
+# All plugin tests
+pnpm test:plugin my-plugin
+```

package/claude/skills/plugins/references/plugin-types.md

@@ -0,0 +1,198 @@
+# Plugin Types Reference
+
+Detailed structures and examples for each plugin type.
+
+## 1. Utility Plugin
+
+Simple utilities and helper functions. Minimal structure.
+
+```
+my-utility-plugin/
+├── package.json
+├── plugin.config.ts
+├── README.md
+├── .env.example
+├── lib/
+│   ├── utils.ts
+│   └── helpers.ts
+└── types/
+    └── utility.types.ts
+```
+
+### Example: String Utilities Plugin
+
+```typescript
+// plugin.config.ts
+export const stringUtilsConfig: PluginConfig = {
+  name: 'string-utils',
+  version: '1.0.0',
+  displayName: 'String Utilities',
+  description: 'Common string manipulation functions',
+  enabled: true,
+  dependencies: [],
+  services: {
+    capitalize: undefined,
+    slugify: undefined,
+    truncate: undefined
+  }
+}
+
+// lib/utils.ts
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+export function slugify(str: string): string {
+  return str.toLowerCase().replace(/\s+/g, '-').replace(/[^\w-]/g, '')
+}
+
+export function truncate(str: string, length: number): string {
+  return str.length > length ? str.slice(0, length) + '...' : str
+}
+```
+
+---
+
+## 2. Service Plugin
+
+Feature-rich plugins with full stack integration including components, hooks, API endpoints.
+
+```
+my-service-plugin/
+├── package.json
+├── plugin.config.ts
+├── README.md
+├── .env.example
+├── types/
+│   └── plugin.types.ts
+├── lib/
+│   ├── core.ts
+│   └── client.ts
+├── hooks/
+│   └── usePlugin.ts
+├── components/
+│   ├── PluginWidget.tsx
+│   └── PluginSettings.tsx
+├── providers/
+│   └── PluginProvider.tsx
+├── api/
+│   ├── data/route.ts
+│   └── process/route.ts
+├── entities/           # If plugin has its own entities
+│   └── my-entity/
+│       ├── messages/
+│       └── migrations/
+└── docs/
+    └── 01-getting-started/
+```
+
+### Example: AI Chat Plugin
+
+```typescript
+// plugin.config.ts
+export const aiChatConfig: PluginConfig = {
+  name: 'ai-chat',
+  version: '1.0.0',
+  displayName: 'AI Chat',
+  description: 'AI-powered chat functionality',
+  enabled: true,
+  dependencies: [],
+
+  components: {
+    ChatWidget: undefined,
+    ChatHistory: undefined,
+    ChatInput: undefined
+  },
+
+  services: {
+    useChat: undefined,
+    useChatHistory: undefined
+  },
+
+  hooks: {
+    async onLoad() {
+      console.log('[AI Chat] Validating API keys...')
+    },
+    async onActivate() {
+      console.log('[AI Chat] Initializing chat service...')
+    }
+  }
+}
+```
+
+---
+
+## 3. Configuration Plugin
+
+Settings and configuration management. Focuses on schema validation and persistence.
+
+```
+my-config-plugin/
+├── package.json
+├── plugin.config.ts
+├── README.md
+├── .env.example
+├── lib/
+│   ├── config-loader.ts
+│   └── config-validator.ts
+├── types/
+│   └── config.types.ts
+├── schemas/
+│   └── settings.schema.ts
+└── components/
+    └── SettingsForm.tsx
+```
+
+### Example: Theme Configuration Plugin
+
+```typescript
+// plugin.config.ts
+export const themeConfigPlugin: PluginConfig = {
+  name: 'theme-config',
+  version: '1.0.0',
+  displayName: 'Theme Configuration',
+  description: 'Manage theme colors, fonts, and styling',
+  enabled: true,
+  dependencies: [],
+
+  components: {
+    ThemeSettings: undefined,
+    ColorPicker: undefined,
+    FontSelector: undefined
+  },
+
+  services: {
+    useThemeConfig: undefined,
+    useUpdateTheme: undefined
+  }
+}
+
+// schemas/settings.schema.ts
+import { z } from 'zod'
+
+export const ThemeSettingsSchema = z.object({
+  primaryColor: z.string().regex(/^#[0-9A-F]{6}$/i),
+  secondaryColor: z.string().regex(/^#[0-9A-F]{6}$/i),
+  fontFamily: z.enum(['inter', 'roboto', 'poppins']),
+  fontSize: z.enum(['sm', 'md', 'lg']),
+  borderRadius: z.number().min(0).max(24)
+})
+
+export type ThemeSettings = z.infer<typeof ThemeSettingsSchema>
+```
+
+---
+
+## Choosing the Right Type
+
+| Requirement | Utility | Service | Configuration |
+|-------------|---------|---------|---------------|
+| Pure functions only | ✅ | ❌ | ❌ |
+| UI components | ❌ | ✅ | ✅ |
+| API endpoints | ❌ | ✅ | ⚠️ |
+| Database entities | ❌ | ✅ | ⚠️ |
+| User settings | ❌ | ⚠️ | ✅ |
+| External API integration | ⚠️ | ✅ | ❌ |
+| Real-time features | ❌ | ✅ | ❌ |
+
+Legend: ✅ Primary use case | ⚠️ Possible but not typical | ❌ Not appropriate