symfonia-ai-tools 1.0.0

package/templates/packs/vue3/_ai/instructions/vue.instructions.md

@@ -0,0 +1,339 @@
+---
+applyTo: "**/*.vue"
+---
+
+# Vue Component Instructions
+
+## Core Vue Component Principles
+
+### Architecture Rules
+- **Vue components (.vue files)**: Visual layer ONLY - NO business logic
+- **ALL business logic** must go in composables (`useXxx` pattern)
+
+### Component Structure Template
+```vue
+<template>
+  <!-- Use components from your component library -->
+  <Button
+    :disabled="loading"
+    :data-testid="dataTestId"
+    @click="handleClick"
+  >
+    {{ $t('button.save') }}
+  </Button>
+
+  <!-- Always use translation keys, never hardcoded text -->
+  <div>
+    {{ $t('component.description') }}
+  </div>
+</template>
+
+<script setup lang="ts">// Import components
+import { Button } from '{{COMPONENT_LIB_IMPORT}}'
+// 1. Import composables for ALL business logic
+import { useComponentLogic } from '@/composables/useComponentLogic'
+
+// 2. Define props with proper TypeScript interfaces (prefix with I)
+interface IComponentProps {
+  userId: string
+  isEditable: boolean
+  dataTestId?: string
+}
+
+// 3. Define emits with proper TypeScript interfaces
+interface IComponentEmits {
+  save: [data: IFormData]
+  cancel: []
+}
+
+const props = withDefaults(defineProps<IComponentProps>(), {
+  dataTestId: 'component'
+})
+
+const emit = defineEmits<IComponentEmits>()
+
+// 4. Use composables for ALL business logic - NO logic in component
+const {
+  loading,
+  handleSave,
+  handleCancel,
+  buttonVariant,
+  textVariant
+} = useComponentLogic(props, emit)
+
+// 5. Only simple event handlers that delegate to composables
+const handleClick = () => {
+  handleSave()
+}
+</script>
+
+<style scoped>
+/* Minimal styles only */
+/* DO NOT interfere with existing CSS */
+</style>
+```
+
+## Mandatory Requirements
+
+### 1. TypeScript Interfaces
+- **ALL props must have interfaces** prefixed with `I` (e.g., `IComponentProps`)
+- **ALL emits must be typed** with interfaces (e.g., `IComponentEmits`)
+- **NEVER use `any` type** - strict typing required
+- **Import types properly** with `import type { ... }`
+
+### 2. Business Logic Separation
+- **NO business logic in Vue components**
+- **ALL logic goes in composables** (`/src/composables/useXxxLogic.ts`)
+- **Components only handle**: rendering, props, emits, basic event delegation
+- **Use composables for**: API calls, state management, calculations, validations
+
+### 3. Component Library Usage
+- **ALWAYS use existing components** from your component library (Button, InputText, Loader, Alert, Modal, etc.)
+- **Check existing components** before creating new ones
+- **Follow existing patterns** as examples in the codebase
+- **NEVER recreate existing functionality**
+- Import components: `import { Button, InputText, Alert } from '{{COMPONENT_LIB_IMPORT}}'`
+
+### 4. Internationalization (i18n)
+- **ALL user-facing text MUST use `$t('key')`**
+- **NEVER hardcode strings** in templates
+- **Check existing translation keys** first
+- **Use descriptive, hierarchical keys**: `module.component.action`
+
+### 5. Data Test IDs
+- **ALWAYS add `data-testid`** for testing
+- **Pass `dataTestId` as prop** with default value
+- **Use camelCase for `dataTestId` values**: `'bellNotifications'`, `'userForm'`, `'saveButton'`
+- Correct: `dataTestId: 'bellNotifications'`
+- Wrong: `dataTestId: 'bell-notifications'`
+
+### 6. CSS Class Naming
+- **Use single dash `-` as separator** (NOT BEM double underscore `__`)
+- Correct: `.notification-item-content`, `.user-form-header`
+- Wrong: `.notification-item__content`, `.user-form__header`
+- **No CSS comments** - styles should be self-explanatory
+
+### 7. Console and Debugging
+- **NEVER use console methods** in production code
+- Use a centralized error handler utility for errors
+- Remove all debugging statements before committing
+
+## Component Development Guidelines
+
+### Props and Emits Best Practices
+```vue
+<script setup lang="ts">
+// Good: Proper interface definition
+interface IUserFormProps {
+  userId: string
+  initialData?: IUserData
+  isReadonly: boolean
+  dataTestId?: string
+}
+
+interface IUserFormEmits {
+  save: [userData: IUserData]
+  cancel: []
+  validation: [isValid: boolean]
+}
+
+// Good: Default values with camelCase
+const props = withDefaults(defineProps<IUserFormProps>(), {
+  dataTestId: 'userForm',
+  isReadonly: false
+})
+
+const emit = defineEmits<IUserFormEmits>()
+
+// Good: Delegate everything to composables
+const { formData, validation, handleSave } = useUserForm(props, emit)
+</script>
+```
+
+### Error Handling
+```vue
+<script setup lang="ts">
+// Good: Error handling in composables
+const { error, loading, clearError } = useUserManagement()
+
+// Good: Error display with components
+</script>
+
+<template>
+  <Alert
+    v-if="error"
+    type="error"
+    :data-testid="`${dataTestId}-error`"
+    @close="clearError"
+  >
+    {{ $t('error.generic') }}
+  </Alert>
+</template>
+```
+
+### Loading States
+```vue
+<template>
+  <!-- Good: Loading states with components -->
+  <Loader v-if="loading" :data-testid="`${dataTestId}-loader`" />
+
+  <Button
+    :disabled="loading"
+    :loading="loading"
+    :data-testid="`${dataTestId}-submit`"
+  >
+    {{ $t('form.submit') }}
+  </Button>
+</template>
+```
+
+## Common Mistakes to Avoid
+
+### Never Do This
+```vue
+<script setup lang="ts">
+// BAD: Business logic in component
+const saveUser = async () => {
+  try {
+    const response = await api.post('/users', userData)
+    // Complex business logic here
+  } catch (error) {
+    // Error handling here
+  }
+}
+
+// BAD: Hardcoded strings
+const title = 'User Profile'
+
+// BAD: Using any type
+const props = defineProps<{ data: any }>()
+
+</script>
+
+<template>
+  <!-- BAD: Hardcoded text -->
+  <h1>User Profile</h1>
+</template>
+```
+
+### Always Do This
+```vue
+<script setup lang="ts">
+// GOOD: Use composables for business logic
+const { saveUser, loading, error } = useUserManagement(props, emit)
+
+// GOOD: Proper TypeScript interfaces
+interface IUserProfileProps {
+  userId: string
+  dataTestId?: string
+}
+
+const props = withDefaults(defineProps<IUserProfileProps>(), {
+  dataTestId: 'user-profile'
+})
+</script>
+
+<template>
+  <!-- GOOD: Use translation keys -->
+  <h1 :data-testid="`${dataTestId}-title`">
+    {{ $t('user.profile.title') }}
+  </h1>
+
+  <!-- GOOD: Use components from your component library -->
+  <Button
+    :disabled="loading"
+    :data-testid="`${dataTestId}-save`"
+    @click="saveUser"
+  >
+    {{ $t('form.save') }}
+  </Button>
+</template>
+```
+
+## Testing Requirements
+
+### Component Testing with VITEST
+- **Test props and emits behavior**
+- **Test user interactions**
+- **Mock composables, not component internals**
+- **Use `data-testid` for element selection**
+
+```typescript
+// Example component test
+describe('UserForm Component', () => {
+  it('should emit save event when form is submitted', async () => {
+    const wrapper = mount(UserForm, {
+      props: { userId: '123', dataTestId: 'test-form' }
+    })
+
+    await wrapper.find('[data-testid="test-form-save"]').trigger('click')
+    expect(wrapper.emitted('save')).toBeTruthy()
+  })
+})
+```
+
+## Performance Optimization
+
+### Vue Performance Best Practices
+```vue
+<template>
+  <!-- Use v-memo for expensive renders -->
+  <div v-memo="[expensiveData]">
+    <!-- Complex list items -->
+  </div>
+
+  <!-- Proper key attributes in v-for -->
+  <div
+    v-for="item in items"
+    :key="item.id"
+    :data-testid="`item-${item.id}`"
+  >
+    {{ item.name }}
+  </div>
+</template>
+```
+
+## State Management Integration
+
+### Pinia Store Usage
+```vue
+<script setup lang="ts">
+// Good: Access stores through composables
+const { users, addUser } = useUserStore()
+
+// Good: Reactive computed properties
+const filteredUsers = computed(() =>
+  users.value.filter(user => user.isActive)
+)
+</script>
+```
+
+## File Organization
+
+### Component Location Rules
+- **Module-specific components**: `{{MODULE_PATH}}/components/`
+- **Shared components**: `{{COMPONENT_LIB_PATH}}`
+- **Component composables**: `{{MODULE_PATH}}/composables/`
+- **Component types**: `{{MODULE_PATH}}/types/`
+
+### Import Organization
+```vue
+<script setup lang="ts">
+// 1. Vue imports
+import { computed, ref } from 'vue'
+
+// 2. External library imports
+import { useI18n } from 'vue-i18n'
+
+// 3. Project components
+import { Button, InputText, Alert, Loader } from '{{COMPONENT_LIB_IMPORT}}'
+
+// 4. Internal composables
+import { useUserManagement } from '@/composables/useUserManagement'
+
+// 5. Types
+import type { IUser, IUserForm } from '@/types/user'
+</script>
+```
+
+Remember: Vue components are purely visual layers. All business logic, API calls, and complex state management must be handled by composables following the established architecture patterns.

package/templates/packs/vue3/_ai/skills/api-integration/SKILL.md

@@ -0,0 +1,195 @@
+# Skill: API Integration (Vue 3 + TypeScript)
+
+## Trigger
+Use when connecting frontend to a new or existing backend API endpoint.
+
+## Input
+- API endpoint (method + URL, e.g. `GET /api/users`)
+- Request payload (if any)
+- Response format (JSON structure)
+- Target module (where to add integration)
+
+## Steps
+
+### 1. Define types from API contract
+
+```typescript
+// types/[module].types.ts
+
+// Response type - matches API response exactly
+export interface I[Entity]Response {
+  id: number;
+  name: string;
+  status: T[Entity]Status;
+  // ... match API response fields
+  created_at: string;  // keep API casing in response type
+}
+
+// Frontend type - camelCase, parsed dates
+export interface I[Entity] {
+  id: number;
+  name: string;
+  status: T[Entity]Status;
+  createdAt: Date;
+}
+
+// Request payload type
+export interface I[Entity]CreatePayload {
+  name: string;
+  status: T[Entity]Status;
+}
+
+// Mapper
+export function map[Entity](raw: I[Entity]Response): I[Entity] {
+  return {
+    id: raw.id,
+    name: raw.name,
+    status: raw.status,
+    createdAt: new Date(raw.created_at),
+  };
+}
+```
+
+### 2. Add service method
+
+```typescript
+// services/[Module].service.ts
+import { useApi } from '@/composables/useApi';
+import type { I[Entity]Response, I[Entity]CreatePayload } from '../types/[module].types';
+
+const api = useApi();
+const BASE = '{{API_BASE_URL}}/[endpoint]';
+
+const [Module]Service = {
+  // ... existing methods
+
+  // New method
+  fetchItems: (params?: Record<string, unknown>) =>
+    api.get<I[Entity]Response[]>(BASE, { params }),
+
+  createItem: (data: I[Entity]CreatePayload) =>
+    api.post<I[Entity]Response>(BASE, data),
+};
+
+export default [Module]Service;
+```
+
+### 3. Update store
+
+```typescript
+// [module].store.ts - add to existing store
+
+import { map[Entity] } from './types/[module].types';
+
+// Inside defineStore:
+async function fetchItems() {
+  loading.value = true;
+  try {
+    const { data } = await [Module]Service.fetchItems();
+    items.value = data.map(map[Entity]);
+  } finally {
+    loading.value = false;
+  }
+}
+```
+
+### 4. Create/update composable
+
+If the integration needs form handling or complex logic, create a composable:
+
+```typescript
+// composables/use[Action].ts
+import { ref } from 'vue';
+import { use[Module]Store } from '../[module].store';
+import [Module]Service from '../services/[Module].service';
+import type { I[Entity]CreatePayload } from '../types/[module].types';
+
+export function use[Action]() {
+  const store = use[Module]Store();
+  const submitting = ref(false);
+  const error = ref<string | null>(null);
+
+  async function submit(payload: I[Entity]CreatePayload) {
+    submitting.value = true;
+    error.value = null;
+    try {
+      await [Module]Service.createItem(payload);
+      await store.fetchItems(); // refresh list
+    } catch (e) {
+      error.value = 'Operation failed';
+      throw e;
+    } finally {
+      submitting.value = false;
+    }
+  }
+
+  return { submitting, error, submit };
+}
+```
+
+### 5. Connect to view
+
+```vue
+<script setup lang="ts">
+import { use[Module]Store } from '../[module].store';
+import { use[Action] } from '../composables/use[Action]';
+
+const store = use[Module]Store();
+const { submitting, error, submit } = use[Action]();
+
+// Fetch on mount
+store.fetchItems();
+</script>
+```
+
+### 6. Handle errors
+
+Ensure error states are handled in the UI:
+- Loading state (spinner/skeleton)
+- Empty state (no results)
+- Error state (API failure message)
+- Validation errors (422 response → field-level errors)
+
+### 7. Write tests
+
+```typescript
+// Test service method (mock API)
+describe('[Module]Service', () => {
+  it('fetches items from API', async () => {
+    // mock useApi().get to return test data
+    // verify service calls correct URL
+    // verify response is returned
+  });
+});
+
+// Test store action
+describe('use[Module]Store', () => {
+  it('fetchItems maps response and updates state', async () => {
+    // mock service
+    // call store.fetchItems()
+    // verify items are mapped and stored
+  });
+});
+
+// Test composable
+describe('use[Action]', () => {
+  it('submits and refreshes list', async () => {
+    // mock service + store
+    // call submit()
+    // verify service called + store refreshed
+  });
+});
+```
+
+### 8. Verification checklist
+
+- [ ] Types match API contract exactly
+- [ ] Mapper converts API casing → frontend casing
+- [ ] Service method uses correct HTTP method + URL
+- [ ] Store action handles loading state
+- [ ] Error states handled in UI (loading, empty, error)
+- [ ] 422 validation errors mapped to form fields
+- [ ] Composable created if logic is non-trivial
+- [ ] Tests cover service, store, composable
+- [ ] No `any` types — everything strictly typed
+- [ ] No hardcoded API URLs (use base URL constant)

package/templates/packs/vue3/_ai/skills/new-component/SKILL.md

@@ -0,0 +1,133 @@
+# Skill: New Component (Vue 3 + TypeScript)
+
+## Trigger
+Use when creating a new reusable Vue component.
+
+## Input
+- Component name (PascalCase, e.g. "UserCard")
+- Props specification
+- Events specification
+- Target directory
+
+## Steps
+
+### 1. Create files
+
+```
+[target-dir]/
+├── [ComponentName].vue
+├── [ComponentName].stories.ts
+└── [ComponentName].test.ts
+```
+
+### 2. Write component
+
+```vue
+<template>
+  <div class="[component-name]" :data-testid="dataTestId">
+    <!-- component template -->
+  </div>
+</template>
+
+<script setup lang="ts">
+interface I[ComponentName]Props {
+  /** Description of prop */
+  dataTestId?: string;
+  // ... props
+}
+
+interface I[ComponentName]Emits {
+  (e: 'update', value: unknown): void;
+  // ... events
+}
+
+const props = withDefaults(defineProps<I[ComponentName]Props>(), {
+  dataTestId: '[componentName]',
+});
+
+const emit = defineEmits<I[ComponentName]Emits>();
+</script>
+
+<style scoped lang="scss">
+.component-name {
+  // single-dash CSS classes only
+}
+</style>
+```
+
+Rules:
+- `<template>` → `<script setup>` → `<style scoped>` order
+- Interface props with `I` prefix
+- `withDefaults` for default values
+- JSDoc on props for Storybook autodocs
+- `data-testid` on root element
+- CSS: single-dash classes, no BEM
+
+### 3. Write Storybook story
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/vue3';
+import [ComponentName] from './[ComponentName].vue';
+
+const meta: Meta<typeof [ComponentName]> = {
+  title: 'Components/[Category]/[ComponentName]',
+  component: [ComponentName],
+  argTypes: {
+    // control for each prop
+  },
+  tags: ['autodocs'],
+};
+
+export default meta;
+type Story = StoryObj<typeof [ComponentName]>;
+
+export const Default: Story = {
+  args: {
+    // default props
+  },
+};
+
+// Add variants: Disabled, Loading, Error, etc.
+```
+
+### 4. Write test
+
+```typescript
+import { mount } from '@vue/test-utils';
+import { describe, expect, it } from 'vitest';
+import [ComponentName] from './[ComponentName].vue';
+
+describe('[ComponentName]', () => {
+  it('renders with default props', () => {
+    const wrapper = mount([ComponentName]);
+    expect(wrapper.find('.[component-name]').exists()).toBe(true);
+  });
+
+  it('emits events correctly', async () => {
+    const wrapper = mount([ComponentName]);
+    // trigger action
+    expect(wrapper.emitted('update')).toBeTruthy();
+  });
+
+  it('has correct data-testid', () => {
+    const wrapper = mount([ComponentName], {
+      props: { dataTestId: 'custom' },
+    });
+    expect(wrapper.attributes('data-testid')).toBe('custom');
+  });
+});
+```
+
+### 5. Verification checklist
+
+- [ ] Component renders correctly
+- [ ] Props typed with interface + `I` prefix
+- [ ] Emits typed with interface
+- [ ] `withDefaults` for optional props
+- [ ] JSDoc comments on props (for Storybook)
+- [ ] `data-testid` on root and interactive elements
+- [ ] Story with `tags: ['autodocs']` and argTypes
+- [ ] At least Default + 2 variant stories
+- [ ] Test covers render, props, events
+- [ ] CSS uses single-dash classes, scoped
+- [ ] No `console.log`