diff --git a/.cursor/rules/unit-test.mdc b/.cursor/rules/unit-test.mdc deleted file mode 100644 index 2c6704f3e..000000000 --- a/.cursor/rules/unit-test.mdc +++ /dev/null @@ -1,21 +0,0 @@ ---- -description: Creating unit tests -globs: -alwaysApply: false ---- - -# Creating unit tests - -- This project uses `vitest` for unit testing -- Tests are stored in the `test/` directory -- Tests should be cross-platform compatible; able to run on Windows, macOS, and linux - - e.g. the use of `path.resolve`, or `path.join` and `path.sep` to ensure that tests work the same on all platforms -- Tests should be mocked properly - - Mocks should be cleanly written and easy to understand - - Mocks should be re-usable where possible - -## Unit test style - -- Prefer the use of `test.extend` over loose variables - - To achieve this, import `test as baseTest` from `vitest` -- Never use `it`; `test` should be used in place of this \ No newline at end of file diff --git a/.github/AGENTS.md b/.github/AGENTS.md new file mode 100644 index 000000000..0b64ac21b --- /dev/null +++ b/.github/AGENTS.md @@ -0,0 +1,14 @@ +# PR Review Context + +Context for automated PR review system. + +## Review Scope + +This automated review performs comprehensive analysis: +- Architecture and design patterns +- Security vulnerabilities +- Performance implications +- Code quality and maintainability +- Integration concerns + +For implementation details, see `.claude/commands/comprehensive-pr-review.md`. diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md index 9a95d8cd0..3c928db39 100644 --- a/.github/CLAUDE.md +++ b/.github/CLAUDE.md @@ -1,36 +1,3 @@ -# ComfyUI Frontend - Claude Review Context - -This file provides additional context for the automated PR review system. - -## Quick Reference - -### PrimeVue Component Migrations - -When reviewing, flag these deprecated components: -- `Dropdown` → Use `Select` from 'primevue/select' -- `OverlayPanel` → Use `Popover` from 'primevue/popover' -- `Calendar` → Use `DatePicker` from 'primevue/datepicker' -- `InputSwitch` → Use `ToggleSwitch` from 'primevue/toggleswitch' -- `Sidebar` → Use `Drawer` from 'primevue/drawer' -- `Chips` → Use `AutoComplete` with multiple enabled and typeahead disabled -- `TabMenu` → Use `Tabs` without panels -- `Steps` → Use `Stepper` without panels -- `InlineMessage` → Use `Message` component - -### API Utilities Reference - -- `api.apiURL()` - Backend API calls (/prompt, /queue, /view, etc.) -- `api.fileURL()` - Static file access (templates, extensions) -- `$t()` / `i18n.global.t()` - Internationalization -- `DOMPurify.sanitize()` - HTML sanitization - -## Review Scope - -This automated review performs comprehensive analysis including: -- Architecture and design patterns -- Security vulnerabilities -- Performance implications -- Code quality and maintainability -- Integration concerns - -For implementation details, see `.claude/commands/comprehensive-pr-review.md`. \ No newline at end of file + +@AGENTS.md diff --git a/.storybook/AGENTS.md b/.storybook/AGENTS.md new file mode 100644 index 000000000..5f6373f4b --- /dev/null +++ b/.storybook/AGENTS.md @@ -0,0 +1,17 @@ +# Storybook Guidelines + +See `@docs/guidance/storybook.md` for story patterns (auto-loaded for `*.stories.ts`). + +## Available Context + +Stories have access to: +- All ComfyUI stores +- PrimeVue with ComfyUI theming +- i18n system +- CSS variables and styling + +## Troubleshooting + +1. **Import Errors**: Verify `@/` alias works +2. **Missing Styles**: Check CSS imports in `preview.ts` +3. **Store Errors**: Check store initialization in setup diff --git a/.storybook/CLAUDE.md b/.storybook/CLAUDE.md index ca8248784..320b78815 100644 --- a/.storybook/CLAUDE.md +++ b/.storybook/CLAUDE.md @@ -1,197 +1,3 @@ -# Storybook Development Guidelines for Claude - -## Quick Commands - -- `pnpm storybook`: Start Storybook development server -- `pnpm build-storybook`: Build static Storybook -- `pnpm test:unit`: Run unit tests (includes Storybook components) - -## Development Workflow for Storybook - -1. **Creating New Stories**: - - Place `*.stories.ts` files alongside components - - Follow the naming pattern: `ComponentName.stories.ts` - - Use realistic mock data that matches ComfyUI schemas - -2. **Testing Stories**: - - Verify stories render correctly in Storybook UI - - Test different component states and edge cases - - Ensure proper theming and styling - -3. **Code Quality**: - - Run `pnpm typecheck` to verify TypeScript - - Run `pnpm lint` to check for linting issues - - Follow existing story patterns and conventions - -## Story Creation Guidelines - -### Basic Story Structure - -```typescript -import type { Meta, StoryObj } from '@storybook/vue3' -import ComponentName from './ComponentName.vue' - -const meta: Meta = { - title: 'Category/ComponentName', - component: ComponentName, - parameters: { - layout: 'centered' // or 'fullscreen', 'padded' - } -} - -export default meta -type Story = StoryObj - -export const Default: Story = { - args: { - // Component props - } -} -``` - -### Mock Data Patterns - -For ComfyUI components, use realistic mock data: - -```typescript -// Node definition mock -const mockNodeDef = { - input: { - required: { - prompt: ["STRING", { multiline: true }] - } - }, - output: ["CONDITIONING"], - output_is_list: [false], - category: "conditioning" -} - -// Component instance mock -const mockComponent = { - id: "1", - type: "CLIPTextEncode", - // ... other properties -} -``` - -### Common Story Variants - -Always include these story variants when applicable: - -- **Default**: Basic component with minimal props -- **WithData**: Component with realistic data -- **Loading**: Component in loading state -- **Error**: Component with error state -- **LongContent**: Component with edge case content -- **Empty**: Component with no data - -### Storybook-Specific Code Patterns - -#### Store Access -```typescript -// In stories, access stores through the setup function -export const WithStore: Story = { - render: () => ({ - setup() { - const store = useMyStore() - return { store } - }, - template: '' - }) -} -``` - -#### Event Testing -```typescript -export const WithEvents: Story = { - args: { - onUpdate: fn() // Use Storybook's fn() for action logging - } -} -``` - -## Configuration Notes - -### Vue App Setup -The Storybook preview is configured with: -- Pinia stores initialized -- PrimeVue with ComfyUI theme -- i18n internationalization -- All necessary CSS imports - -### Build Configuration -- Vite integration with proper alias resolution -- Manual chunking for better performance -- TypeScript support with strict checking -- CSS processing for Vue components - -## Troubleshooting - -### Common Issues - -1. **Import Errors**: Verify `@/` alias is working correctly -2. **Missing Styles**: Ensure CSS imports are in `preview.ts` -3. **Store Errors**: Check store initialization in setup -4. **Type Errors**: Use proper TypeScript types for story args - -### Debug Commands - -```bash -# Check TypeScript issues -pnpm typecheck - -# Lint Storybook files -pnpm lint .storybook/ - -# Build to check for production issues -pnpm build-storybook -``` - -## File Organization - -``` -.storybook/ -├── main.ts # Core configuration -├── preview.ts # Global setup and decorators -├── README.md # User documentation -└── CLAUDE.md # This file - Claude guidelines - -src/ -├── components/ -│ └── MyComponent/ -│ ├── MyComponent.vue -│ └── MyComponent.stories.ts -``` - -## Integration with ComfyUI - -### Available Context - -Stories have access to: -- All ComfyUI stores (widgetStore, colorPaletteStore, etc.) -- PrimeVue components with ComfyUI theming -- Internationalization system -- ComfyUI CSS variables and styling - -### Testing Components - -When testing ComfyUI-specific components: -1. Use realistic node definitions and data structures -2. Test with different node types (sampling, conditioning, etc.) -3. Verify proper CSS theming and dark/light modes -4. Check component behavior with various input combinations - -### Performance Considerations - -- Use manual chunking for large dependencies -- Minimize bundle size by avoiding unnecessary imports -- Leverage Storybook's lazy loading capabilities -- Profile build times and optimize as needed - -## Best Practices - -1. **Keep Stories Focused**: Each story should demonstrate one specific use case -2. **Use Descriptive Names**: Story names should clearly indicate what they show -3. **Document Complex Props**: Use JSDoc comments for complex prop types -4. **Test Edge Cases**: Create stories for unusual but valid use cases -5. **Maintain Consistency**: Follow established patterns in existing stories \ No newline at end of file + +@AGENTS.md diff --git a/AGENTS.md b/AGENTS.md index 743572be3..da2953783 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # Repository Guidelines +See @docs/guidance/*.md for file-type-specific conventions (auto-loaded by glob). + ## Project Structure & Module Organization - Source: `src/` @@ -46,6 +48,21 @@ The project uses **Nx** for build orchestration and task management - `pnpm lint` / `pnpm lint:fix`: Lint (ESLint) - `pnpm format` / `pnpm format:check`: Prettier - `pnpm typecheck`: Vue TSC type checking +- `pnpm storybook`: Start Storybook development server + +## Development Workflow + +1. Make code changes +2. Run relevant tests +3. Run `pnpm typecheck`, `pnpm lint`, `pnpm format` +4. Check if README updates are needed +5. Suggest docs.comfy.org updates for user-facing changes + +## Git Conventions + +- Use `prefix:` format: `feat:`, `fix:`, `test:` +- Add "Fixes #n" to PR descriptions +- Never mention Claude/AI in commits ## Coding Style & Naming Conventions diff --git a/CLAUDE.md b/CLAUDE.md index 7ceadf85c..43c994c2d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,30 +1 @@ -# Claude Code specific instructions - -@Agents.md - -## Repository Setup - -For first-time setup, use the Claude command: - -```sh -/setup_repo -``` - -This bootstraps the monorepo with dependencies, builds, tests, and dev server verification. - -**Prerequisites:** Node.js >= 24, Git repository, available ports for dev server, storybook, etc. - -## Development Workflow - -1. **First-time setup**: Run `/setup_repo` Claude command -2. Make code changes -3. Run tests (see subdirectory CLAUDE.md files) -4. Run typecheck, lint, format -5. Check README updates -6. Consider docs.comfy.org updates - -## Git Conventions - -- Use `prefix:` format: `feat:`, `fix:`, `test:` -- Add "Fixes #n" to PR descriptions -- Never mention Claude/AI in commits +@AGENTS.md diff --git a/browser_tests/AGENTS.md b/browser_tests/AGENTS.md new file mode 100644 index 000000000..177529ee1 --- /dev/null +++ b/browser_tests/AGENTS.md @@ -0,0 +1,8 @@ +# E2E Testing Guidelines + +See `@docs/guidance/playwright.md` for Playwright best practices (auto-loaded for `*.spec.ts`). + +## Directory Structure + +- `assets/` - Test data (JSON workflows, fixtures) +- Tests use premade JSON workflows to load desired graph state diff --git a/browser_tests/CLAUDE.md b/browser_tests/CLAUDE.md index cc42b392b..62a682148 100644 --- a/browser_tests/CLAUDE.md +++ b/browser_tests/CLAUDE.md @@ -1,17 +1,3 @@ -# E2E Testing Guidelines - -## Browser Tests -- Test user workflows -- Use Playwright fixtures -- Follow naming conventions - -## Best Practices -- Check assets/ for test data -- Prefer specific selectors -- Test across viewports - -## Testing Process -After code changes: -1. Create browser tests as appropriate -2. Run tests until passing -3. Then run typecheck, lint, format \ No newline at end of file + +@AGENTS.md diff --git a/docs/guidance/playwright.md b/docs/guidance/playwright.md new file mode 100644 index 000000000..f8ec8eabf --- /dev/null +++ b/docs/guidance/playwright.md @@ -0,0 +1,33 @@ +--- +globs: + - '**/*.spec.ts' +--- + +# Playwright E2E Test Conventions + +See `docs/testing/*.md` for detailed patterns. + +## Best Practices + +- Follow [Playwright Best Practices](https://playwright.dev/docs/best-practices) +- Do NOT use `waitForTimeout` - use Locator actions and retrying assertions +- Prefer specific selectors (role, label, test-id) +- Test across viewports + +## Test Tags + +Tags are respected by config: +- `@mobile` - Mobile viewport tests +- `@2x` - High DPI tests + +## Test Data + +- Check `browser_tests/assets/` for test data and fixtures +- Use realistic ComfyUI workflows for E2E tests + +## Running Tests + +```bash +pnpm test:browser # Run all E2E tests +pnpm test:browser -- --ui # Interactive UI mode +``` diff --git a/docs/guidance/storybook.md b/docs/guidance/storybook.md new file mode 100644 index 000000000..70bdb6c53 --- /dev/null +++ b/docs/guidance/storybook.md @@ -0,0 +1,55 @@ +--- +globs: + - '**/*.stories.ts' +--- + +# Storybook Conventions + +## File Placement + +Place `*.stories.ts` files alongside their components: +``` +src/components/MyComponent/ +├── MyComponent.vue +└── MyComponent.stories.ts +``` + +## Story Structure + +```typescript +import type { Meta, StoryObj } from '@storybook/vue3' +import ComponentName from './ComponentName.vue' + +const meta: Meta = { + title: 'Category/ComponentName', + component: ComponentName, + parameters: { layout: 'centered' } +} + +export default meta +type Story = StoryObj + +export const Default: Story = { + args: { /* props */ } +} +``` + +## Required Story Variants + +Include when applicable: +- **Default** - Minimal props +- **WithData** - Realistic data +- **Loading** - Loading state +- **Error** - Error state +- **Empty** - No data + +## Mock Data + +Use realistic ComfyUI schemas for mocks (node definitions, components). + +## Running Storybook + +```bash +pnpm storybook # Development server +pnpm build-storybook # Production build +``` diff --git a/docs/guidance/typescript.md b/docs/guidance/typescript.md new file mode 100644 index 000000000..9a6dd102b --- /dev/null +++ b/docs/guidance/typescript.md @@ -0,0 +1,37 @@ +--- +globs: + - '**/*.ts' + - '**/*.tsx' + - '**/*.vue' +--- + +# TypeScript Conventions + +## Type Safety + +- Never use `any` type - use proper TypeScript types +- Never use `as any` type assertions - fix the underlying type issue +- Type assertions are a last resort; they lead to brittle code +- Avoid `@ts-expect-error` - fix the underlying issue instead + +## Utility Libraries + +- Use `es-toolkit` for utility functions (not lodash) + +## API Utilities + +When making API calls in `src/`: + +```typescript +// ✅ Correct - use api helpers +const response = await api.get(api.apiURL('/prompt')) +const template = await fetch(api.fileURL('/templates/default.json')) + +// ❌ Wrong - direct URL construction +const response = await fetch('/api/prompt') +``` + +## Security + +- Sanitize HTML with `DOMPurify.sanitize()` +- Never log secrets or sensitive data diff --git a/docs/guidance/vitest.md b/docs/guidance/vitest.md new file mode 100644 index 000000000..90fe19673 --- /dev/null +++ b/docs/guidance/vitest.md @@ -0,0 +1,36 @@ +--- +globs: + - '**/*.test.ts' +--- + +# Vitest Unit Test Conventions + +See `docs/testing/*.md` for detailed patterns. + +## Test Quality + +- Do not write change detector tests (tests that just assert defaults) +- Do not write tests dependent on non-behavioral features (styles, classes) +- Do not write tests that just test mocks - ensure real code is exercised +- Be parsimonious; avoid redundant tests + +## Mocking + +- Use Vitest's mocking utilities (`vi.mock`, `vi.spyOn`) +- Keep module mocks contained - no global mutable state +- Use `vi.hoisted()` for per-test mock manipulation +- Don't mock what you don't own + +## Component Testing + +- Use Vue Test Utils for component tests +- Follow advice about making components easy to test +- Wait for reactivity with `await nextTick()` after state changes + +## Running Tests + +```bash +pnpm test:unit # Run all unit tests +pnpm test:unit -- path/to/file # Run specific test +pnpm test:unit -- --watch # Watch mode +``` diff --git a/docs/guidance/vue-components.md b/docs/guidance/vue-components.md new file mode 100644 index 000000000..24bcf22fe --- /dev/null +++ b/docs/guidance/vue-components.md @@ -0,0 +1,46 @@ +--- +globs: + - '**/*.vue' +--- + +# Vue Component Conventions + +Applies to all `.vue` files anywhere in the codebase. + +## Vue 3 Composition API + +- Use `