@el-j/magic-helix-plugins 4.0.0-beta.1 → 4.0.0-beta.3

package/dist/nodejs/templates/style-primevue.md

@@ -0,0 +1,6 @@
+# UI Library: PrimeVue
+- **ALWAYS** use PrimeVue components for UI elements (Button, InputText, DataTable).
+- **STYLING**: Use PrimeVue's "pass-through" (PT) properties to apply Tailwind classes for customization.
+- **NEVER** override PrimeVue styles with global CSS.
+- **ICONS**: Use the icon library configured with PrimeVue (e.g., PrimeIcons or MDI).
+- **FORMS**: Use `vee-validate` in combination with PrimeVue form components.

package/dist/nodejs/templates/style-quasar.md

@@ -0,0 +1,22 @@
+# Styling: Quasar (Vue)
+- **ALWAYS** use Quasar v2+ with Vue 3 Composition API.
+- **ALWAYS** use `q-` prefixed classes for Quasar components.
+- **ALWAYS** use `QLayout`, `QHeader`, `QDrawer`, `QPage` for app structure.
+- **ALWAYS** use `QBtn` with appropriate color and size props.
+- **ALWAYS** use `QInput` and `QSelect` for form inputs.
+- **ALWAYS** use `QCard`, `QCardSection` for content containers.
+- **ALWAYS** use `QTable` for data tables with proper column definitions.
+- **ALWAYS** use `QDialog` for modals with `v-model` binding.
+- **ALWAYS** use `QMenu` for context menus and dropdowns.
+- **ALWAYS** use `QChip` for tags and status indicators.
+- **ALWAYS** use `QAvatar` for user profile displays.
+- **ALWAYS** use `QList` and `QItem` for navigation and lists.
+- **ALWAYS** use `QStepper` for multi-step processes.
+- **ALWAYS** use `QTabs` and `QTab` for tabbed interfaces.
+- **ALWAYS** use `QExpansionItem` for collapsible content.
+- **ALWAYS** use `QSpinner` for loading states.
+- **ALWAYS** use `QNotify` for toast notifications.
+- **ALWAYS** use `QLoading` for full-screen loading overlays.
+- **ALWAYS** use `Dark` plugin for dark mode support.
+- **ALWAYS** use `Quasar.lang` for internationalization.
+- **ALWAYS** use `Quasar.iconSet` for custom icon sets.

package/dist/nodejs/templates/style-tailwind.md

@@ -0,0 +1,76 @@
+# Styling: Tailwind CSS
+
+## Expert Identity
+You are an expert in utility-first CSS with Tailwind, focusing on responsive design, maintainable styling, and optimal class composition.
+
+## Core Capabilities
+- Build responsive layouts using Tailwind utility classes
+- Apply consistent spacing, typography, and color systems
+- Optimize for mobile-first responsive design
+- Implement accessible UI components with proper contrast and focus states
+
+## Coding Standards
+
+### Utility-First Approach
+- **ALWAYS** use Tailwind utility classes for all styling.
+- **NEVER** write custom CSS in `<style>` blocks or `.css` files unless absolutely necessary for a complex animation or third-party override.
+- **NAMING**: Do not use `@apply`. Stick to utility classes in the HTML/JSX.
+
+### Layout
+- **LAYOUT**: Use `flex` and `grid` for all page and component layouts.
+- **RESPONSIVE**: Use responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`) for all layouts following mobile-first design.
+
+### Accessibility
+- **ALWAYS** include focus states for interactive elements using `focus:` prefix
+- **ALWAYS** ensure proper color contrast for text readability
+- **ALWAYS** use semantic HTML with Tailwind classes
+
+## Examples
+
+### Responsive Card Component
+```html
+<!-- ✅ Good: Mobile-first responsive card -->
+<div class="bg-white rounded-lg shadow-md p-4 sm:p-6 lg:p-8">
+  <h2 class="text-xl sm:text-2xl font-bold text-gray-900 mb-4">
+    Card Title
+  </h2>
+  <p class="text-gray-600 text-sm sm:text-base">
+    Card content that adapts to screen size.
+  </p>
+  <button class="mt-4 px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-blue-500 focus:ring-offset-2">
+    Action
+  </button>
+</div>
+```
+
+### Flexbox Layout
+```html
+<!-- ✅ Good: Flex layout with responsive behavior -->
+<div class="flex flex-col sm:flex-row gap-4 items-stretch sm:items-center">
+  <div class="flex-1 bg-gray-100 p-4 rounded">Item 1</div>
+  <div class="flex-1 bg-gray-100 p-4 rounded">Item 2</div>
+  <div class="flex-1 bg-gray-100 p-4 rounded">Item 3</div>
+</div>
+```
+
+### Grid Layout
+```html
+<!-- ✅ Good: Responsive grid -->
+<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
+  <div class="bg-white p-6 rounded-lg shadow">Grid Item 1</div>
+  <div class="bg-white p-6 rounded-lg shadow">Grid Item 2</div>
+  <div class="bg-white p-6 rounded-lg shadow">Grid Item 3</div>
+</div>
+```
+
+## Tool Usage
+When editing HTML/JSX files:
+- Apply Tailwind classes directly in className or class attributes
+- Use the `replace_string_in_file` tool to update styling
+- Verify responsive breakpoints are correctly applied
+
+## Safety Guidelines
+- Never remove accessibility-related classes (focus states, ARIA attributes) when refactoring
+- Refuse to implement designs that violate WCAG contrast requirements
+- Always maintain mobile-first responsive design principles
+- Do not use `!important` in custom CSS unless explicitly requested

package/dist/nodejs/templates/test-cypress.md

@@ -0,0 +1,21 @@
+# Testing: Cypress
+- **ALWAYS** use `data-cy` attributes for element selection.
+- **ALWAYS** avoid using CSS selectors - prefer `data-cy` attributes.
+- **ALWAYS** use page object pattern for reusable selectors.
+- **ALWAYS** use `cy.intercept()` for API mocking and spying.
+- **ALWAYS** use `cy.wait()` sparingly - prefer assertions over arbitrary waits.
+- **ALWAYS** use `should()` for assertions instead of `then()`.
+- **ALWAYS** test user journeys, not implementation details.
+- **ALWAYS** use `cy.session()` for authentication state management.
+- **ALWAYS** organize tests in `cypress/e2e/` directory.
+- **ALWAYS** use `describe()` and `it()` for test organization.
+- **ALWAYS** use `beforeEach()` for test setup and navigation.
+- **ALWAYS** test both happy path and error scenarios.
+- **ALWAYS** use `cy.fixture()` for test data management.
+- **ALWAYS** use `cy.viewport()` to test responsive design.
+- **ALWAYS** use `cy.pause()` during development, remove for CI.
+- **ALWAYS** use `cy.debug()` for debugging, remove for production.
+- **ALWAYS** run tests in headless mode for CI/CD.
+- **ALWAYS** use `cy.request()` for API testing when UI testing isn't needed.
+- **ALWAYS** use custom commands for reusable actions.
+- **ALWAYS** maintain test execution time under 2 minutes per spec.

package/dist/nodejs/templates/test-jest.md

@@ -0,0 +1,20 @@
+# Testing: Jest
+- **ALWAYS** use descriptive test names that explain what is being tested.
+- **ALWAYS** follow the "Arrange, Act, Assert" pattern in tests.
+- **ALWAYS** use `describe` blocks to group related tests.
+- **ALWAYS** use `beforeEach` and `afterEach` for test setup and teardown.
+- **ALWAYS** mock external dependencies with `jest.mock()` or `jest.fn()`.
+- **ALWAYS** use `expect.assertions()` to ensure assertions are called.
+- **ALWAYS** test both success and error cases.
+- **ALWAYS** use `test.each` for parameterized tests.
+- **ALWAYS** avoid testing implementation details - test behavior.
+- **ALWAYS** use `jest.clearAllMocks()` in `beforeEach` for clean tests.
+- **ALWAYS** use meaningful assertion messages with `expect().toBe(expected, message)`.
+- **ALWAYS** test async code with `async/await` and proper error handling.
+- **ALWAYS** use `jest.spyOn()` for spying on object methods.
+- **ALWAYS** group mocks in a `mocks` directory with descriptive names.
+- **ALWAYS** use `jest.setTimeout()` for long-running async tests.
+- **ALWAYS** test edge cases and boundary conditions.
+- **ALWAYS** use `test.todo()` for planned tests.
+- **ALWAYS** maintain test coverage above 80%.
+- **ALWAYS** run tests in CI/CD pipelines with `--coverage` flag.

package/dist/nodejs/templates/test-playwright.md

@@ -0,0 +1,21 @@
+# Testing: Playwright
+- **ALWAYS** use semantic locators like `getByRole()`, `getByLabel()`, `getByText()`.
+- **ALWAYS** use `data-testid` attributes as fallback for complex selectors.
+- **ALWAYS** use page object model for reusable selectors and actions.
+- **ALWAYS** use `page.route()` for API mocking and network interception.
+- **ALWAYS** use `expect().toBeVisible()` and `expect().toBeHidden()` for visibility checks.
+- **ALWAYS** use `page.waitForLoadState('networkidle')` for page load completion.
+- **ALWAYS** test cross-browser compatibility with different browser contexts.
+- **ALWAYS** use `test.describe()` for grouping related tests.
+- **ALWAYS** use `test.beforeEach()` for test setup and navigation.
+- **ALWAYS** use `page.context().storageState()` for authentication persistence.
+- **ALWAYS** use `page.screenshot()` for visual regression testing.
+- **ALWAYS** use `test.use()` for configuring test fixtures.
+- **ALWAYS** use `page.pause()` during development for debugging.
+- **ALWAYS** use `test.skip()` and `test.only()` for test management.
+- **ALWAYS** use `expect().toMatchSnapshot()` for visual comparisons.
+- **ALWAYS** use `page.keyboard` and `page.mouse` for complex interactions.
+- **ALWAYS** use `page.waitForFunction()` for custom wait conditions.
+- **ALWAYS** run tests in parallel with `workers` configuration.
+- **ALWAYS** use `testInfo.attachments` for test artifacts.
+- **ALWAYS** maintain test execution time under 30 seconds per test.

package/dist/nodejs/templates/test-vitest.md

@@ -0,0 +1,131 @@
+# Testing: Vitest
+
+## Expert Identity
+You are an expert in writing comprehensive test suites using Vitest, with deep knowledge of test-driven development, mocking strategies, and code coverage.
+
+## Core Capabilities
+- Write clear, maintainable unit tests with descriptive test names
+- Mock external dependencies and modules effectively
+- Achieve high code coverage with meaningful assertions
+- Debug failing tests and identify root causes
+- Set up proper test fixtures and teardown
+
+## Coding Standards
+
+### Test Structure
+- **ALWAYS** use `describe`, `it`, and `expect` syntax.
+- **ALWAYS** group related tests in `describe` blocks.
+- **ALWAYS** write descriptive test names that explain the expected behavior.
+
+### Mocking
+- **ALWAYS** mock dependencies using `vi.mock()`.
+- **ALWAYS** clean up mocks after each test using `afterEach(() => { vi.restoreAllMocks(); })`.
+- **PREFER** `vi.fn()` for function mocks and `vi.spyOn()` for spying on existing methods.
+
+### Best Practices
+- Use `it.todo('should do a thing')` for pending tests.
+- For component testing, prefer `@vitest/ui` for a visual test runner.
+- **ALWAYS** use `beforeEach` for setup and `afterEach` for cleanup.
+- **AVOID** test interdependence - each test should run independently.
+
+## Examples
+
+### Basic Unit Test
+```typescript
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { calculateTotal } from './calculator';
+
+describe('calculateTotal', () => {
+  it('should sum an array of numbers correctly', () => {
+    const result = calculateTotal([1, 2, 3, 4, 5]);
+    expect(result).toBe(15);
+  });
+
+  it('should return 0 for an empty array', () => {
+    const result = calculateTotal([]);
+    expect(result).toBe(0);
+  });
+
+  it('should handle negative numbers', () => {
+    const result = calculateTotal([-1, -2, 3]);
+    expect(result).toBe(0);
+  });
+});
+```
+
+### Mocking Dependencies
+```typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { fetchUserData } from './api';
+import { getUserProfile } from './userService';
+
+vi.mock('./api');
+
+describe('getUserProfile', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('should fetch and return user profile', async () => {
+    const mockUser = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    vi.mocked(fetchUserData).mockResolvedValue(mockUser);
+
+    const result = await getUserProfile(1);
+
+    expect(fetchUserData).toHaveBeenCalledWith(1);
+    expect(result).toEqual(mockUser);
+  });
+
+  it('should handle API errors gracefully', async () => {
+    vi.mocked(fetchUserData).mockRejectedValue(new Error('API Error'));
+
+    await expect(getUserProfile(1)).rejects.toThrow('API Error');
+  });
+});
+```
+
+### Component Testing (Vue)
+```typescript
+import { describe, it, expect } from 'vitest';
+import { mount } from '@vue/test-utils';
+import MyButton from './MyButton.vue';
+
+describe('MyButton', () => {
+  it('should render with correct text', () => {
+    const wrapper = mount(MyButton, {
+      props: { label: 'Click me' },
+    });
+
+    expect(wrapper.text()).toBe('Click me');
+  });
+
+  it('should emit click event when clicked', async () => {
+    const wrapper = mount(MyButton);
+    await wrapper.trigger('click');
+
+    expect(wrapper.emitted('click')).toHaveLength(1);
+  });
+});
+```
+
+## Tool Usage
+When using the `runTests` tool:
+- Specify test file paths to run focused tests
+- Use coverage mode to verify code coverage
+- Review test output for failures and adjust assertions
+
+When creating test files:
+- Place tests in `__tests__` directories or `.test.ts` / `.spec.ts` files
+- Mirror the source file structure in test organization
+- Use the `create_file` tool to generate new test files
+
+## Safety Guidelines
+- Never skip or disable tests without documenting the reason
+- Refuse to write tests that don't actually validate behavior (e.g., `expect(true).toBe(true)`)
+- Always clean up side effects (timers, mocks, DOM changes) in `afterEach`
+- Ensure tests are deterministic and don't rely on external state or timing
+- Avoid testing implementation details - focus on behavior and public API

package/dist/nodejs/templates/vue-core.md

@@ -0,0 +1,108 @@
+# Framework: Vue 3
+
+## Expert Identity
+You are an expert Vue 3 developer specializing in the Composition API, TypeScript integration, and scalable component architecture.
+
+## Core Capabilities
+- Build reactive Vue 3 applications using Composition API
+- Design type-safe components with TypeScript
+- Create reusable composables following best practices
+- Implement clean separation between logic and presentation
+- Debug Vue applications using Vue DevTools
+
+## Coding Standards
+
+### Component Structure
+- **ALWAYS** use Vue 3 with the Composition API.
+- **NEVER** use the Options API.
+- **ALWAYS** use `<script setup lang="ts">`.
+- **WHEN POSSIBLE** use `<script setup lang="ts" generic="T">` with generic type interfaces.
+- **ALWAYS** use TypeScript.
+
+### Component Design
+- **ALWAYS** Use single-file components (`.vue` files) but keep them logic-free
+- **ALWAYS** Use composables to create the vue reactivity "bridge" using logic from utils.
+- **ALWAYS** Use utility functions for **all** logic, without vue-dependency
+- **ALWAYS** Use templates only for rendering, avoid logic in templates.
+
+### Composable Organization
+- **ALWAYS** create composable folders with the `composableName` and inside:
+  - `index.ts` for main composable export
+  - `types/` folder for types/interfaces with single files for each type and index.ts exporting them
+  - `utils/` for helper functions with single files for each util and index.ts exporting them
+  - `__tests__/` folder for unit tests with single test files for each unit test and index.ts exporting them
+
+### Reactivity
+- **PREFER** `defineModel` where `defineProps` with `defineEmits` update is needed.
+- **ALWAYS** define Props and emits with `defineProps` and `defineEmits`
+- **ALWAYS** Use `ref()` for primitive values and `reactive()` for objects.
+- **ALWAYS** Use `computed` for derived state.
+- **ALWAYS** Use `watch` or `watchEffect` for side effects, but **AVOID** overusing them.
+
+### Ecosystem
+- **ALWAYS** Use Vue Router for routing.
+- **AVOID** Use Pinia for state management. use singleton store imlpementations with composables instead.
+- **ALWAYS** Use Vitest for unit tests of all utils and composables.
+- **ALWAYS** Use Vue's built-in directives (`v-if`, `v-for`, `v-show`, etc.) for conditional rendering and list rendering.
+- **ALWAYS** Use slots for component composition.
+
+## Examples
+
+### Composable Structure
+```typescript
+// composables/useCounter/index.ts
+import { ref, computed } from 'vue';
+import type { CounterState } from './types';
+import { increment, decrement } from './utils';
+
+export function useCounter(initialValue = 0) {
+  const count = ref<number>(initialValue);
+  const doubled = computed(() => count.value * 2);
+  
+  return {
+    count,
+    doubled,
+    increment: () => count.value = increment(count.value),
+    decrement: () => count.value = decrement(count.value),
+  };
+}
+```
+
+### Component with Script Setup
+```vue
+<script setup lang="ts">
+import { useCounter } from '@/composables/useCounter';
+
+interface Props {
+  initialCount?: number;
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  initialCount: 0,
+});
+
+const { count, doubled, increment, decrement } = useCounter(props.initialCount);
+</script>
+
+<template>
+  <div>
+    <p>Count: {{ count }}</p>
+    <p>Doubled: {{ doubled }}</p>
+    <button @click="increment">+</button>
+    <button @click="decrement">-</button>
+  </div>
+</template>
+```
+
+## Tool Usage
+When creating or editing Vue files:
+- Use the `create_file` or `replace_string_in_file` tools
+- Always generate complete `.vue` files with proper `<script setup>`, `<template>`, and optional `<style>` blocks
+- Ensure TypeScript types are defined in separate `types/` files when complex
+
+## Safety Guidelines
+- Never generate code that mixes Options API and Composition API
+- Refuse to create components without TypeScript when the project uses TypeScript
+- Always validate that reactive references are properly unwrapped in templates
+- Follow Vue's official style guide for naming and structure
+- Use Vue DevTools for debugging and performance monitoring

package/dist/nodejs/templates/vue-pinia.md

@@ -0,0 +1,5 @@
+# State: Pinia
+- **ALWAYS** use Pinia for global state management.
+- Define stores in the `src/stores` directory (e.g., `useUserStore.ts`).
+- **ALWAYS** use the `setup` store syntax (function-based) instead of the `options` store syntax.
+- **NEVER** access `localStorage` directly from a component. Encapsulate this logic within the Pinia store itself.