plan-flow-skill 1.0.0

package/rules/patterns/jest-patterns.mdc

@@ -0,0 +1,492 @@
+---
+description: "Patterns and conventions for writing Jest tests in JavaScript/TypeScript"
+alwaysApply: false
+---
+
+# Jest Testing Patterns
+
+Patterns and conventions for writing Jest tests in JavaScript/TypeScript codebases, ensuring consistency, maintainability, and comprehensive coverage.
+
+---
+
+## File Naming Conventions
+
+Tests must follow specific naming conventions based on their execution environment:
+
+| Suffix | Environment | Purpose |
+| ------ | ----------- | ------- |
+| `*.client.test.ts` | Client-side (jsdom) | React hooks, components, client utilities |
+| `*.server.test.ts` | Server-side (node) | API routes, commands, server utilities |
+| `*.test.ts` | Default (node) | General utilities without specific environment needs |
+| `*.test.tsx` | JSX support | Components that need JSX in tests |
+
+**Examples**:
+
+```
+src/components/chat/MessageInput/useMessageInputLogic.client.test.ts
+src/commands/streamChatCommand.server.test.ts
+src/utils/linkRewriter.client.test.ts
+src/app/api/chat/stream/route.server.test.ts
+```
+
+---
+
+## Test File Location
+
+Place test files next to the code they test (co-location pattern):
+
+```
+src/
+├── components/
+│   └── chat/
+│       └── MessageInput/
+│           ├── index.tsx
+│           ├── useMessageInputLogic.internal.ts
+│           └── useMessageInputLogic.client.test.ts  # Co-located
+├── commands/
+│   ├── streamChatCommand.ts
+│   └── streamChatCommand.server.test.ts  # Co-located
+├── utils/
+│   ├── linkRewriter.ts
+│   └── linkRewriter.client.test.ts  # Co-located
+```
+
+**Why**: Co-location makes tests easy to find, encourages testing, and ensures tests are updated when code changes.
+
+---
+
+## Test Structure
+
+Use the **Arrange-Act-Assert** (AAA) pattern with descriptive `describe` and `it` blocks:
+
+```typescript
+describe('streamChatCommand', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  describe('chat validation', () => {
+    it('should throw BadRequestError if chat does not exist', async () => {
+      // Arrange
+      mockDatabase.findChatWithUsers.mockResolvedValue(null)
+
+      // Act & Assert
+      await expect(streamChatCommand(createValidInput())).rejects.toThrow(
+        new BadRequestError(BadRequestReason.NOT_FOUND, { chatId: 'chat-1' }),
+      )
+
+      expect(mockDatabase.findChatWithUsers).toHaveBeenCalledWith('chat-1')
+    })
+  })
+})
+```
+
+**Guidelines**:
+
+- Group related tests in `describe` blocks
+- Use descriptive test names that explain the expected behavior
+- Start test names with "should" for consistency
+- One assertion per test when possible (or related assertions)
+
+---
+
+## Server Test Setup
+
+For server-side tests, use the centralized mock setup:
+
+```typescript
+import { mockDatabase } from '@/test-utils/setup-server-test'  // MUST be first import
+import { streamChatCommand } from './streamChatCommand'
+import { JupiterEngineAPI } from '@/datasources/JupiterEngineAPI'
+import { BadRequestError, BadRequestReason } from '@/types/errors'
+
+// Mock external dependencies
+jest.mock('@/datasources/JupiterEngineAPI')
+
+const mockJupiterEngineAPI = JupiterEngineAPI as jest.MockedClass<
+  typeof JupiterEngineAPI
+>
+
+describe('streamChatCommand', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  // ... tests
+})
+```
+
+**Critical**: Import `@/test-utils/setup-server-test` **before** any other `@/` imports. This ensures the database mock is hoisted correctly.
+
+---
+
+## Client Test Setup
+
+For client-side tests, mock stores and providers explicitly:
+
+```typescript
+import { act, renderHook } from '@testing-library/react'
+import { useMessageInputLogic } from './useMessageInputLogic.internal'
+
+// Mock stores
+jest.mock('@/stores/chatStore', () => ({
+  useChatStore: jest.fn(),
+}))
+
+jest.mock('@/stores/selectedAgentStore', () => ({
+  useSelectedAgentStore: jest.fn(),
+}))
+
+// Get typed mocks
+const { useChatStore } = jest.requireMock('@/stores/chatStore')
+const { useSelectedAgentStore } = jest.requireMock('@/stores/selectedAgentStore')
+
+describe('useMessageInputLogic', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    
+    // Setup default mock implementations
+    useChatStore.mockImplementation((selector) => {
+      if (typeof selector === 'function') {
+        return selector(mockStoreState)
+      }
+      return mockStoreState
+    })
+  })
+
+  // ... tests
+})
+```
+
+---
+
+## Mock Factories
+
+Use type-safe mock factories from `@/types/mocks` for consistent test data:
+
+```typescript
+import {
+  createMockUser,
+  createMockChatWithUsers,
+  createMockMessageWithUser,
+  createMockAgent,
+} from '@/types/mocks'
+
+describe('chat feature', () => {
+  it('should handle user message', async () => {
+    const mockUser = createMockUser({ id: 'user-1', name: 'Test User' })
+    const mockChat = createMockChatWithUsers({ tenantId: 'tenant-1' })
+    const mockMessage = createMockMessageWithUser({ 
+      id: 'msg-1',
+      message: 'Hello, world!',
+    })
+
+    // ... test logic
+  })
+})
+```
+
+**Creating Mock Factories**:
+
+```typescript
+// In @/types/mocks.ts
+export const createMockEntity = (overrides?: Partial<Entity>): Entity => ({
+  id: 'entity-1',
+  name: 'Default Name',
+  createdAt: new Date('2024-01-01'),
+  // ... all required fields with sensible defaults
+  ...overrides,  // Allow overrides
+})
+```
+
+---
+
+## Testing Logic Hooks
+
+Test logic hooks in isolation using `renderHook`:
+
+```typescript
+import { renderHook, act } from '@testing-library/react'
+import { useMessageInputLogic } from './useMessageInputLogic.internal'
+
+describe('useMessageInputLogic', () => {
+  const createBaseProps = (overrides = {}) => ({
+    chatId: 'chat-1',
+    input: '',
+    handleChange: jest.fn(),
+    handleSubmit: jest.fn(),
+    ...overrides,
+  })
+
+  it('should update input value on change', () => {
+    const handleChange = jest.fn()
+    const { result } = renderHook(() =>
+      useMessageInputLogic(createBaseProps({ handleChange })),
+    )
+
+    act(() => {
+      result.current.handleChange({
+        target: { value: 'Hello' },
+      } as React.ChangeEvent<HTMLTextAreaElement>)
+    })
+
+    expect(handleChange).toHaveBeenCalled()
+  })
+})
+```
+
+---
+
+## Mocking Dependencies
+
+### Mocking Modules
+
+```typescript
+// Full module mock
+jest.mock('@/datasources/JupiterEngineAPI')
+
+// Partial module mock
+jest.mock('@/utils/streamProcessing', () => ({
+  processAssistantStream: jest.fn(),
+  toInputJson: jest.fn((data) => data),  // Keep some real implementation
+}))
+
+// Typed mock access
+const mockJupiterEngineAPI = JupiterEngineAPI as jest.MockedClass<
+  typeof JupiterEngineAPI
+>
+const mockProcessStream = processAssistantStream as jest.MockedFunction<
+  typeof processAssistantStream
+>
+```
+
+### Mocking Class Instances
+
+```typescript
+jest.mock('@/datasources/JupiterEngineAPI')
+
+const mockJupiterEngineAPI = JupiterEngineAPI as jest.MockedClass<
+  typeof JupiterEngineAPI
+>
+
+beforeEach(() => {
+  mockJupiterEngineAPI.prototype.streamAgentResponse = jest
+    .fn()
+    .mockResolvedValue({
+      body: {
+        tee: () => [mockStream, mockStream],
+      },
+    })
+})
+```
+
+### Mocking Zustand Stores
+
+```typescript
+jest.mock('@/stores/chatStore', () => ({
+  useChatStore: jest.fn(),
+}))
+
+const { useChatStore } = jest.requireMock('@/stores/chatStore')
+
+beforeEach(() => {
+  useChatStore.mockImplementation((selector) => {
+    if (typeof selector === 'function') {
+      return selector(mockStoreState)
+    }
+    return mockStoreState
+  })
+})
+```
+
+---
+
+## Testing Async Code
+
+```typescript
+describe('async operations', () => {
+  it('should handle successful async operation', async () => {
+    mockDatabase.findChatWithUsers.mockResolvedValue(mockChat)
+
+    const result = await streamChatCommand(createValidInput())
+
+    expect(result.stream).toBeDefined()
+  })
+
+  it('should handle async errors', async () => {
+    mockDatabase.findChatWithUsers.mockRejectedValue(new Error('DB Error'))
+
+    await expect(streamChatCommand(createValidInput())).rejects.toThrow('DB Error')
+  })
+})
+```
+
+---
+
+## Testing Error Cases
+
+```typescript
+import { BadRequestError, ForbiddenError, JupiterEngineError } from '@/types/errors'
+
+describe('error handling', () => {
+  it('should throw BadRequestError for missing chat', async () => {
+    mockDatabase.findChatWithUsers.mockResolvedValue(null)
+
+    await expect(streamChatCommand(createValidInput())).rejects.toThrow(
+      new BadRequestError(BadRequestReason.NOT_FOUND, { chatId: 'chat-1' }),
+    )
+  })
+
+  it('should throw ForbiddenError for tenant mismatch', async () => {
+    mockDatabase.findChatWithUsers.mockResolvedValue(
+      createMockChatWithUsers({ tenantId: 'different-tenant' }),
+    )
+
+    await expect(streamChatCommand(createValidInput())).rejects.toThrow(
+      new ForbiddenError(ForbiddenReason.INVALID_TENANT_MEMBERSHIP),
+    )
+  })
+})
+```
+
+---
+
+## Testing with Input Factories
+
+Create factory functions for valid inputs to reduce boilerplate:
+
+```typescript
+const createValidInput = (overrides = {}) => ({
+  messages: [
+    {
+      id: 'msg-1',
+      role: 'user' as const,
+      parts: [{ type: 'text' as const, text: 'Hello' }],
+    },
+  ],
+  chatId: 'chat-1',
+  internalTenantId: 'tenant-1',
+  accessToken: 'token-123',
+  userId: 'user-1',
+  ...overrides,
+})
+```
+
+---
+
+## Browser API Mocks
+
+For client tests requiring browser APIs:
+
+```typescript
+// ResizeObserver mock
+const installResizeObserver = () => {
+  const callbacks: ResizeObserverCallback[] = []
+
+  class MockObserver implements ResizeObserver {
+    private callback: ResizeObserverCallback
+    constructor(callback: ResizeObserverCallback) {
+      this.callback = callback
+      callbacks.push(callback)
+    }
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  }
+
+  globalThis.ResizeObserver = MockObserver as unknown as typeof ResizeObserver
+  return callbacks
+}
+
+// Storage mock (in jest.setup.ts)
+const createMockStorage = () => {
+  const storage: Record<string, string> = {}
+  return {
+    getItem: jest.fn((key) => storage[key] ?? null),
+    setItem: jest.fn((key, value) => { storage[key] = value }),
+    removeItem: jest.fn((key) => { delete storage[key] }),
+    clear: jest.fn(() => Object.keys(storage).forEach(k => delete storage[k])),
+  }
+}
+```
+
+---
+
+## Forbidden Patterns
+
+### DON'T Skip Test Cleanup
+
+```typescript
+// BAD - No cleanup
+it('should handle error', () => {
+  jest.spyOn(console, 'error').mockImplementation()
+  // Test runs, but spy is never restored
+})
+
+// GOOD - Proper cleanup
+it('should handle error', () => {
+  const spy = jest.spyOn(console, 'error').mockImplementation()
+  // ... test logic
+  spy.mockRestore()
+})
+```
+
+### DON'T Use Implementation Details in Tests
+
+```typescript
+// BAD - Testing implementation
+it('should set internal state', () => {
+  const component = render(<MyComponent />)
+  expect(component.instance().state.isLoading).toBe(true)
+})
+
+// GOOD - Testing behavior
+it('should show loading indicator', () => {
+  render(<MyComponent />)
+  expect(screen.getByRole('progressbar')).toBeInTheDocument()
+})
+```
+
+### DON'T Write Tests That Always Pass
+
+```typescript
+// BAD - No real assertion
+it('should work', async () => {
+  await someFunction()
+  expect(true).toBe(true)
+})
+
+// GOOD - Meaningful assertion
+it('should return processed data', async () => {
+  const result = await someFunction()
+  expect(result.data).toEqual(expectedData)
+})
+```
+
+### DON'T Ignore Async Behavior
+
+```typescript
+// BAD - Missing await
+it('should fetch data', () => {
+  const result = fetchData()  // Returns promise, not data!
+  expect(result).toBeDefined()  // Always passes
+})
+
+// GOOD - Proper async handling
+it('should fetch data', async () => {
+  const result = await fetchData()
+  expect(result.data).toBeDefined()
+})
+```
+
+---
+
+## Summary
+
+Following these testing patterns ensures:
+
+- **Consistency**: Same patterns across the codebase
+- **Maintainability**: Tests are easy to understand and update
+- **Reliability**: Tests are isolated and deterministic
+- **Coverage**: Edge cases and errors are tested
+- **Speed**: Tests run efficiently with proper mocking

package/rules/patterns/plans-patterns.mdc

@@ -0,0 +1,237 @@
+---
+description: "Implementation planning patterns for feature development"
+alwaysApply: false
+---
+
+# Implementation Plan Patterns
+
+## Overview
+
+This document describes the patterns and rules for creating and executing implementation plans. Following these patterns ensures consistent, trackable, and maintainable feature development.
+
+---
+
+## Workflow Folder Structure
+
+```
+flow/
+├── archive/      # IGNORE - Completed/abandoned plans
+├── discovery/    # Research, spikes, and exploration
+├── plans/        # Active implementation plans
+└── references/   # Reference materials (API contracts, specs, designs)
+```
+
+| Folder              | Purpose                                    | When to Use                  |
+| ------------------- | ------------------------------------------ | ---------------------------- |
+| `flow/plans/`       | Active implementation plans                | Creating new feature plans   |
+| `flow/discovery/`   | Research, spikes, exploration documents    | Investigating before planning|
+| `flow/references/`  | Reference materials (API contracts, specs) | Storing documentation        |
+| `flow/archive/`     | Completed or abandoned plans               | After plan completion        |
+
+---
+
+## Critical Rule: Ignore Archived Plans
+
+**NEVER consider or reference files inside the `flow/archive/` folder.** These are outdated, superseded, or abandoned plans that should not influence current development.
+
+---
+
+## Allowed Patterns
+
+### 1. Store Plans with Snake Case Naming
+
+All implementation plans must be created inside `flow/plans/` using snake_case naming with incremental versioning.
+
+**Naming Convention**: `plan_<feature_name>_v<version>.md`
+
+---
+
+### 2. Use Discovery Folder for Research
+
+Before creating a plan for complex features, create discovery documents in `flow/discovery/`. See `.cursor/rules/patterns/discovery-patterns.mdc` for details.
+
+---
+
+### 3. Create Markdown Files with Required Sections
+
+Every plan must include:
+
+- **Overview**: Brief description
+- **Goals**: Main objectives
+- **Phases**: Implementation steps with complexity scores
+- **Key Changes**: Summary of modifications
+
+See `.cursor/rules/patterns/plans-templates.mdc` for the full template.
+
+---
+
+### 4. Include Key Changes Summary
+
+Every plan must end with a "Key Changes" section summarizing the most important modifications.
+
+---
+
+### 5. Follow All Cursor Rules During Execution
+
+On every execution of each phase, ensure compliance with all cursor rules:
+
+- `.cursor/rules/core/allowed-patterns.mdc` - Follow allowed patterns
+- `.cursor/rules/core/forbidden-patterns.mdc` - Avoid forbidden patterns
+
+---
+
+### 6. Structure Plans with Scoped Phases
+
+Every plan must be divided into implementation phases with clear scope boundaries:
+
+- **Scope**: What this phase covers
+- **Complexity**: Score from 0-10
+- **Tasks**: Checkboxes for tracking
+- **Build Verification**: Command to verify
+
+---
+
+### 7. Tests Must Be the Last Phase
+
+Always schedule testing as the final phase of implementation. Tests validate complete implementation and avoid rewriting during development.
+
+---
+
+### 8. Verify Build Success After Each Phase
+
+At the end of each phase, run `npm run build` to ensure no build errors.
+
+---
+
+### 9. Minimize Code in Plan Documents
+
+Plans should describe what to implement, not how to code it. Only include code when it serves as an important reference example.
+
+---
+
+### 10. Move Completed Plans to Archive
+
+When a plan is fully implemented or no longer relevant:
+
+```bash
+mv flow/plans/plan_feature_name_v1.md flow/archive/
+```
+
+---
+
+### 11. Assign Complexity Scores to Each Phase
+
+Every phase must include a **Complexity Score** from 0-10.
+
+See `.cursor/rules/core/complexity-scoring.mdc` for the complete scoring system.
+
+---
+
+### 12. Execute Phases Using Plan Mode
+
+When executing a plan, each phase must trigger **Plan mode** before implementation:
+
+1. Use the [Plan Mode Tool](.cursor/rules/tools/plan-mode-tool.mdc) to switch to Plan mode automatically
+2. Present phase details and approach
+3. Get user approval
+4. Implement
+5. Verify build
+6. Update progress in plan file
+
+**Reference**: See `.cursor/rules/tools/plan-mode-tool.mdc` for complete instructions on switching to Plan mode.
+
+---
+
+## Forbidden Patterns
+
+### 1. DON'T Read or Reference Archived Plans
+
+Only reference active plans in the `flow/plans/` folder.
+
+---
+
+### 2. DON'T Create Plans Outside the Workflow Folder
+
+Always create plans in the `flow/plans/` folder with proper naming.
+
+---
+
+### 3. DON'T Use Inconsistent Naming
+
+Use the pattern `plan_<feature_name>_v<version>.md`.
+
+---
+
+### 4. DON'T Skip the Key Changes Section
+
+Always include a "Key Changes" section at the end of the plan.
+
+---
+
+### 5. DON'T Ignore Cursor Rules During Implementation
+
+Review and follow all cursor rules during each phase.
+
+---
+
+### 6. DON'T Create Monolithic Plans Without Phases
+
+Break down plans into logical, scoped phases.
+
+---
+
+### 7. DON'T Write Tests Before Implementation
+
+Tests should always be the last phase.
+
+---
+
+### 8. DON'T Skip Build Verification
+
+Add `npm run build` verification at the end of each phase.
+
+---
+
+### 9. DON'T Include Full Implementation Code in Plans
+
+Describe what to implement; let the actual code live in source files.
+
+---
+
+### 10. DON'T Skip Complexity Scores
+
+Always include a complexity score for each phase.
+
+---
+
+### 11. DON'T Assign Arbitrary Complexity Scores
+
+Use the scoring criteria consistently. When in doubt, score higher.
+
+---
+
+### 12. DON'T Execute Phases Without Plan Mode
+
+Always switch to Plan mode before executing each phase group. Use the [Plan Mode Tool](.cursor/rules/tools/plan-mode-tool.mdc) to ensure proper switching.
+
+---
+
+### 13. DON'T Mix Discovery and Plans
+
+Keep discovery documents in `flow/discovery/` and plans in `flow/plans/`.
+
+---
+
+## Summary
+
+Following these planning patterns ensures:
+
+- **Discoverability**: All plans in `flow/plans/`, research in `flow/discovery/`
+- **Traceability**: Version history and key changes documentation
+- **Quality**: Cursor rules compliance verified at each phase
+- **Reliability**: Build verification prevents accumulation of errors
+- **Maintainability**: Scoped phases enable incremental, trackable progress
+- **Testability**: Tests as the final phase ensure complete coverage
+- **Clarity**: Archived plans are ignored, only active plans are referenced
+- **Intelligent Pacing**: Complexity scores guide execution strategy
+- **Collaborative Execution**: Plan mode ensures user approval before each phase