symfonia-ai-tools 1.0.0

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

@@ -0,0 +1,163 @@
+---
+applyTo: "**/*Service*.ts,**/*service*.ts,**/api/**,**/composables/useApi*"
+---
+
+# API & Services - Instrukcje
+
+## Architektura warstwy API
+
+### Composable API (singleton)
+
+```typescript
+// composables/useApi.ts
+import axios, { type AxiosInstance, type AxiosError, type AxiosRequestConfig } from 'axios';
+
+let apiInstance: AxiosInstance | null = null;
+
+export function useApi() {
+  if (!apiInstance) {
+    apiInstance = axios.create({
+      baseURL: import.meta.env.VITE_API_URL || '{{API_BASE_URL}}',
+      timeout: Number(import.meta.env.VITE_API_TIMEOUT) || 30000,
+      headers: { 'Content-Type': 'application/json' },
+    });
+
+    setupInterceptors(apiInstance);
+  }
+
+  return {
+    get: <T>(url: string, config?: AxiosRequestConfig) => apiInstance!.get<T>(url, config),
+    post: <T>(url: string, data?: unknown, config?: AxiosRequestConfig) => apiInstance!.post<T>(url, data, config),
+    put: <T>(url: string, data?: unknown, config?: AxiosRequestConfig) => apiInstance!.put<T>(url, data, config),
+    patch: <T>(url: string, data?: unknown, config?: AxiosRequestConfig) => apiInstance!.patch<T>(url, data, config),
+    delete: <T>(url: string, config?: AxiosRequestConfig) => apiInstance!.delete<T>(url, config),
+    setAuthToken,
+  };
+}
+```
+
+### Serwisy modulowe (functional pattern)
+
+```typescript
+// modules/[feature]/services/Feature.service.ts
+import { useApi } from '@/composables/useApi';
+
+const api = useApi();
+const BASE = '/features';
+
+const FeatureService = {
+  getAll: () => api.get<IFeature[]>(BASE),
+  getById: (id: number) => api.get<IFeature>(`${BASE}/${id}`),
+  create: (data: IFeatureCreate) => api.post<IFeature>(BASE, data),
+  update: (id: number, data: IFeatureUpdate) => api.put<IFeature>(`${BASE}/${id}`, data),
+  delete: (id: number) => api.delete<void>(`${BASE}/${id}`),
+};
+
+export default FeatureService;
+```
+
+## Interceptory
+
+### Request interceptor
+
+```typescript
+function setupInterceptors(instance: AxiosInstance) {
+  instance.interceptors.request.use((config) => {
+    const token = getAuthToken();
+    if (token) {
+      config.headers.Authorization = `Bearer ${token}`;
+    }
+
+    // Accept-Language z i18n
+    const locale = getCurrentLocale();
+    if (locale) {
+      config.headers['Accept-Language'] = locale;
+    }
+
+    return config;
+  });
+
+  instance.interceptors.response.use(
+    (response) => response,
+    (error: AxiosError) => handleApiError(error),
+  );
+}
+```
+
+### Obsluga bledow
+
+```typescript
+function handleApiError(error: AxiosError): Promise<never> {
+  const status = error.response?.status;
+
+  switch (status) {
+    case 400: notify('error', 'Nieprawidlowe dane'); break;
+    case 401: redirectToLogin(); break;
+    case 403: notify('error', 'Brak uprawnien'); break;
+    case 404: notify('error', 'Nie znaleziono zasobu'); break;
+    case 409: notify('error', 'Konflikt danych'); break;
+    case 422: break; // Walidacja - obslugiwana przez formularz
+    case 500: notify('error', 'Blad serwera'); break;
+    default: notify('error', 'Wystapil nieoczekiwany blad');
+  }
+
+  return Promise.reject(error);
+}
+```
+
+## Opcja returnErrors
+
+Dla formularzy - zwraca bledy zamiast null:
+
+```typescript
+// W serwisie
+const FeatureService = {
+  create: (data: IFeatureCreate, returnErrors = false) => {
+    return api.post<IFeature>('/features', data)
+      .catch((error: AxiosError) => {
+        if (returnErrors) return error;
+        return null;
+      });
+  },
+};
+
+// W uzyciu
+const error = await FeatureService.create(formData, true);
+if (error instanceof AxiosError && error.response?.status === 422) {
+  validationErrors.value = error.response.data.errors;
+}
+```
+
+## Integracja z Pinia Store
+
+```typescript
+// stores/feature.store.ts
+export const useFeatureStore = defineStore('feature', () => {
+  const items = ref<IFeature[]>([]);
+  const loading = ref(false);
+
+  async function fetchAll() {
+    loading.value = true;
+    try {
+      const { data } = await FeatureService.getAll();
+      items.value = data;
+    } catch (error) {
+      printError(error);
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  return { items, loading, fetchAll };
+});
+```
+
+## Zasady
+
+1. **Jeden serwis per modul** - plik `ModuleName.service.ts`
+2. **Functional pattern** - obiekt z metodami, nie klasa
+3. **Typowanie** - kazda metoda typuje request i response
+4. **Nie wywoluj API bezposrednio z komponentu** - zawsze przez serwis
+5. **Error handling** - interceptor obsluguje globalne bledy, serwis moze dodac `returnErrors`
+6. **Zmienne srodowiskowe** - `VITE_API_URL`, `VITE_API_TIMEOUT` w `.env`
+7. **Brak console.log** - uzyj `printError()` dla bledow

package/templates/packs/vue3/_ai/instructions/coding-conventions.instructions.md

@@ -0,0 +1,160 @@
+---
+applyTo: "**/*.vue,**/*.ts,**/*.scss"
+---
+
+# Coding Conventions - Instrukcje
+
+## Nazewnictwo
+
+### Pliki i katalogi
+
+| Element | Konwencja | Przyklad |
+|---------|-----------|----------|
+| Komponenty Vue | PascalCase | `UserProfile.vue` |
+| Composables | camelCase z prefixem `use` | `useUserForm.ts` |
+| Serwisy | PascalCase + `.service.ts` | `User.service.ts` |
+| Store | camelCase + `.store.ts` | `user.store.ts` |
+| Typy/Interfejsy | PascalCase + `.types.ts` | `User.types.ts` |
+| Testy | nazwa + `.test.ts` | `UserProfile.test.ts` |
+| Stale | camelCase + `consts.ts` | `userConsts.ts` |
+
+### Zmienne i funkcje
+
+```typescript
+// camelCase dla zmiennych i funkcji
+const userName = ref('');
+const isLoading = ref(false);
+function fetchUserData() { /* ... */ }
+
+// PascalCase dla komponentow i klas
+import UserProfile from './UserProfile.vue';
+
+// UPPERCASE dla stalych globalnych
+const MAX_RETRY_COUNT = 3;
+const API_TIMEOUT = 30000;
+```
+
+### TypeScript - prefixy typow
+
+```typescript
+// I - Interface
+interface IUser {
+  id: number;
+  name: string;
+}
+
+// E - Enum
+enum EUserRole {
+  ADMIN = 'admin',
+  USER = 'user',
+}
+
+// T - Type alias
+type TUserFilter = 'active' | 'inactive' | 'all';
+```
+
+### CSS klasy
+
+```scss
+// Single dash - NIE uzywaj BEM (__) ani double dash (--)
+.user-profile { }
+.user-profile-header { }
+.user-profile-avatar { }
+
+// ZLE:
+.user-profile__header { }  // BEM
+.user-profile--active { }  // BEM modifier
+```
+
+### data-testid
+
+```vue
+<!-- camelCase, opisowy -->
+<button :data-testid="'userProfileSaveButton'">Zapisz</button>
+<input :data-testid="'userProfileEmailInput'" />
+<div :data-testid="'userProfileCard'" />
+```
+
+## Komentarze i dokumentacja
+
+### Zasady komentowania
+
+1. **Kod ma byc samodokumentujacy** - nazwy zmiennych i funkcji powinny wyjasnic "co"
+2. **Komentarze tylko gdy "dlaczego"** - nie opisuj co robi kod, opisz dlaczego tak a nie inaczej
+3. **JSDoc** - tylko dla publicznego API i composables:
+
+```typescript
+/**
+ * Composable do zarzadzania formularzem uzytkownika.
+ * Obsluguje walidacje, submit i reset.
+ */
+export function useUserForm(userId?: number) {
+  // ...
+}
+```
+
+4. **Zakaz komentarzy HTML** w szablonach Vue (`<!-- -->`)
+5. **Zakaz komentarzy CSS** w stylach (`/* */`)
+
+## Console
+
+### BEZWZGLEDNY ZAKAZ console.log w kodzie produkcyjnym
+
+```typescript
+// ZLE - nigdy nie commituj console.log
+console.log('user:', user);
+console.warn('deprecated');
+
+// DOBRZE - uzywaj dedykowanej funkcji
+import { printError } from '@/composables/useShowError';
+printError(error);
+
+// LUB - jesli potrzebujesz debug info, usun przed commitem
+```
+
+## Struktura komponentu Vue
+
+Kolejnosc sekcji w pliku `.vue`:
+
+```vue
+<template>
+  <!-- 1. Template -->
+</template>
+
+<script setup lang="ts">
+// 2. Script setup
+// Kolejnosc wewnatrz:
+// a) importy
+// b) interface props/emits
+// c) defineProps / defineEmits
+// d) inject / provide
+// e) ref / reactive
+// f) computed
+// g) watch
+// h) metody
+// i) lifecycle hooks (onMounted, onUnmounted)
+// j) defineExpose (jesli potrzebny)
+</script>
+
+<style scoped lang="scss">
+// 3. Scoped styles
+</style>
+```
+
+## Code Review Checklist
+
+Przed kazdym commitem zweryfikuj:
+
+1. [ ] **TypeScript** - brak `any`, poprawne typy, interfejsy z prefixem `I`
+2. [ ] **Nazewnictwo** - camelCase zmienne, PascalCase komponenty, single-dash CSS
+3. [ ] **Console** - brak `console.log/warn/error` (uzyj `printError()`)
+4. [ ] **Komentarze** - brak zbednych, brak HTML/CSS komentarzy
+5. [ ] **data-testid** - camelCase, dodane do interaktywnych elementow
+6. [ ] **Props** - typowane przez interface, domyslne wartosci przez `withDefaults`
+7. [ ] **Emits** - typowane przez interface
+8. [ ] **Store** - plik `.store.ts`, `defineStore` z composition syntax
+9. [ ] **API** - przez serwis, nie bezposrednio z komponentu
+10. [ ] **Error handling** - `printError()`, nie `console.error()`
+11. [ ] **Cleanup** - `onUnmounted` czysci listenery, timery, subskrypcje
+12. [ ] **Testy** - nowy kod ma testy, istniejace testy przechodza
+13. [ ] **Style** - `scoped`, brak `font-family` (poza monospace), single-dash klasy

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

@@ -0,0 +1,218 @@
+---
+applyTo: "**/composables/**,**/use*.ts"
+---
+
+# Composables - Instrukcje
+
+## Konwencje
+
+- Nazwa pliku: `use[Feature].ts` (camelCase z prefixem `use`)
+- Lokalizacja: `{{MODULE_PATH}}composables/` lub `/src/composables/` (globalne)
+- Eksport: named function `export function use[Feature]()`
+- Zwraca obiekt z reaktywnymi wartosciami i metodami
+
+## Wzorzec useAsyncDataLoader
+
+Uniwersalny composable do operacji asynchronicznych:
+
+```typescript
+// composables/useAsyncDataLoader.ts
+import { ref, type Ref } from 'vue';
+
+interface IAsyncDataLoaderOptions<T> {
+  onSuccess?: (data: T) => void;
+  onError?: (error: unknown) => void;
+  throwOnError?: boolean;
+}
+
+export function useAsyncDataLoader<T>(
+  fetchFn: () => Promise<T>,
+  options?: IAsyncDataLoaderOptions<T>,
+) {
+  const loading = ref(false);
+  const data: Ref<T | null> = ref(null);
+  const error: Ref<Error | null> = ref(null);
+
+  async function execute() {
+    loading.value = true;
+    error.value = null;
+    try {
+      const result = await fetchFn();
+      data.value = result;
+      options?.onSuccess?.(result);
+    } catch (err) {
+      error.value = err instanceof Error ? err : new Error(String(err));
+      options?.onError?.(err);
+      if (options?.throwOnError) throw err;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  function reset() {
+    data.value = null;
+    loading.value = false;
+    error.value = null;
+  }
+
+  return { loading, data, error, execute, reset };
+}
+```
+
+### Uzycie
+
+```typescript
+// W composable modulu
+export function useUsers() {
+  const { loading, data, execute } = useAsyncDataLoader(
+    () => UserService.getAll(),
+    {
+      onSuccess: (users) => store.setUsers(users),
+      onError: (err) => printError(err),
+    },
+  );
+
+  return { loading, users: data, fetchUsers: execute };
+}
+
+// W komponencie
+const { loading, users, fetchUsers } = useUsers();
+onMounted(() => fetchUsers());
+```
+
+## Wzorzec composable z formularzem
+
+```typescript
+// composables/useFeatureForm.ts
+export function useFeatureForm(itemId?: number) {
+  const form = reactive<IFeatureForm>({
+    name: '',
+    description: '',
+    status: 'draft',
+  });
+
+  const errors = ref<Record<string, string[]>>({});
+  const submitting = ref(false);
+
+  function resetForm() {
+    Object.assign(form, { name: '', description: '', status: 'draft' });
+    errors.value = {};
+  }
+
+  async function loadItem() {
+    if (!itemId) return;
+    const { data } = await FeatureService.getById(itemId);
+    Object.assign(form, data);
+  }
+
+  async function submitForm() {
+    submitting.value = true;
+    errors.value = {};
+    try {
+      if (itemId) {
+        await FeatureService.update(itemId, form);
+      } else {
+        await FeatureService.create(form);
+      }
+      return true;
+    } catch (error) {
+      if (error instanceof AxiosError && error.response?.status === 422) {
+        errors.value = error.response.data.errors;
+      }
+      return false;
+    } finally {
+      submitting.value = false;
+    }
+  }
+
+  return { form, errors, submitting, resetForm, loadItem, submitForm };
+}
+```
+
+## Wzorzec composable z filtrowaniem
+
+```typescript
+// composables/useFeatureFilters.ts
+export function useFeatureFilters(items: Ref<IFeature[]>) {
+  const searchQuery = ref('');
+  const statusFilter = ref<TStatus | null>(null);
+  const sortBy = ref<'name' | 'date'>('date');
+  const sortOrder = ref<'asc' | 'desc'>('desc');
+
+  const filtered = computed(() => {
+    let result = [...items.value];
+
+    if (searchQuery.value) {
+      const q = searchQuery.value.toLowerCase();
+      result = result.filter(item =>
+        item.name.toLowerCase().includes(q),
+      );
+    }
+
+    if (statusFilter.value) {
+      result = result.filter(item => item.status === statusFilter.value);
+    }
+
+    result.sort((a, b) => {
+      const modifier = sortOrder.value === 'asc' ? 1 : -1;
+      return a[sortBy.value] > b[sortBy.value] ? modifier : -modifier;
+    });
+
+    return result;
+  });
+
+  return { searchQuery, statusFilter, sortBy, sortOrder, filtered };
+}
+```
+
+## Wzorzec composable z localStorage
+
+```typescript
+// composables/useLocalStorage.ts
+export function useLocalStorage<T>(key: string, defaultValue: T) {
+  const stored = localStorage.getItem(key);
+  const data = ref<T>(stored ? JSON.parse(stored) : defaultValue) as Ref<T>;
+
+  watch(data, (newValue) => {
+    localStorage.setItem(key, JSON.stringify(newValue));
+  }, { deep: true });
+
+  function remove() {
+    localStorage.removeItem(key);
+    data.value = defaultValue;
+  }
+
+  return { data, remove };
+}
+```
+
+## Wzorzec composable z window events
+
+```typescript
+// composables/useWindowSize.ts
+export function useWindowSize() {
+  const width = ref(window.innerWidth);
+  const height = ref(window.innerHeight);
+
+  function onResize() {
+    width.value = window.innerWidth;
+    height.value = window.innerHeight;
+  }
+
+  onMounted(() => window.addEventListener('resize', onResize));
+  onUnmounted(() => window.removeEventListener('resize', onResize));
+
+  return { width, height };
+}
+```
+
+## Zasady
+
+1. **Zawsze czyszcz zasoby** - `onUnmounted` dla listenerow, timerow, subskrypcji
+2. **Zwracaj reaktywne wartosci** - `ref`, `computed`, nie surowe wartosci
+3. **Nie uzywaj `this`** - composables to funkcje, nie klasy
+4. **Jeden composable = jedna odpowiedzialnosc** - nie mieszaj filtrowania z API calls
+5. **Typuj parametry i return** - TypeScript musi wiedziec co zwracasz
+6. **Nie wywoluj side-effectow w konstruktorze** - uzytkownik composable decyduje kiedy `execute()`
+7. **`printError()` zamiast `console.error()`** - dla obslugi bledow
+8. **Testowalnosc** - composable powinien byc latwy do przetestowania w izolacji