symfonia-ai-tools 1.0.0

package/templates/base/_gitignore

@@ -0,0 +1,22 @@
+# AI tool configs with tokens/secrets
+.claude/settings.local.json
+.cursor/mcp.json
+.mcp.json
+
+# GSD working files
+.planning/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo

package/templates/base/_junie/guidelines.md

@@ -0,0 +1 @@
+Read and follow .ai/guidelines.md as mandatory context.

package/templates/base/commit-instructions.md

@@ -0,0 +1,92 @@
+# Commit Instructions
+
+## Issue Number from Branch
+
+Extract the issue number from the current branch name and use it as prefix:
+
+```
+feature/{{JIRA_PREFIX}}-1234-feature-name  →  {{JIRA_PREFIX}}-1234: description
+bugfix/{{JIRA_PREFIX}}-567-fix-name        →  {{JIRA_PREFIX}}-567: description
+```
+
+## Format
+
+```
+{{JIRA_PREFIX}}-XXXX: <type>(<scope>): <short description>
+
+[optional longer description — explain WHY, not WHAT]
+```
+
+## Types
+
+- `feat` - new feature
+- `fix` - bug fix
+- `refactor` - code restructuring (no behavior change)
+- `test` - adding/changing tests
+- `docs` - documentation
+- `style` - formatting (no logic change)
+- `chore` - build/CI/tooling changes
+
+## Scope
+
+Module or component name: `auth`, `api`, `ui`, `store`, `config`, `db`
+
+## Rules
+
+1. **Explain WHY, not WHAT** — don't repeat what's visible in the diff
+2. **Max 72 chars** in the first line
+3. **One commit = one logical change** — split unrelated changes into separate commits
+4. **Never add `Co-Authored-By`, `Generated by`, or any AI attribution**
+5. **Do not commit without developer approval**
+6. **Language**: English
+
+## Examples
+
+### Good
+
+```
+{{JIRA_PREFIX}}-456: feat(auth): add JWT refresh token rotation
+
+Implement automatic token rotation on each refresh to prevent
+token replay attacks. Tokens are invalidated after single use.
+```
+
+```
+{{JIRA_PREFIX}}-789: fix(api): prevent race condition in concurrent updates
+
+Multiple simultaneous PATCH requests could overwrite each other.
+Added optimistic locking with version field comparison.
+```
+
+### Bad
+
+```
+# Too vague — no WHY
+fix(auth): fixed bug
+
+# Repeats the diff — no WHY
+feat(users): added email field to form and regex validation
+
+# Two unrelated changes in one commit
+feat(users): add validation and change form layout
+```
+
+## Branch Naming
+
+| Type | Pattern |
+|------|---------|
+| Feature | `feature/{{JIRA_PREFIX}}-XXXX-short-name` |
+| Bugfix | `bugfix/{{JIRA_PREFIX}}-XXXX-short-name` |
+| Hotfix | `hotfix/{{JIRA_PREFIX}}-XXXX-short-name` |
+| Release | `release/vX.Y.Z` |
+
+## Breaking Changes
+
+Add `BREAKING CHANGE:` in footer when breaking backward compatibility:
+
+```
+{{JIRA_PREFIX}}-321: refactor(api)!: change auth endpoint response format
+
+BREAKING CHANGE: /api/auth/login now returns { token, expiresAt }
+instead of { access_token, expires_in }. All clients must update.
+```

package/templates/packs/docker/_ai/instructions/docker.instructions.md

@@ -0,0 +1,193 @@
+---
+applyTo: "**/Dockerfile,**/docker-compose*,**/docker/**"
+---
+
+# Docker & Deployment - Instrukcje
+
+## Zasada nadrzedna
+
+**Wszystkie komendy PHP/Artisan/Composer uruchamiaj wewnatrz kontenera Docker.**
+
+```bash
+# DOBRZE
+docker exec {{DOCKER_CONTAINER}} php artisan migrate
+docker exec {{DOCKER_CONTAINER}} composer install
+docker exec {{DOCKER_CONTAINER}} php artisan test
+
+# ZLE - nigdy na hoscie
+php artisan migrate
+composer install
+```
+
+## Podstawowe komendy
+
+```bash
+# Start srodowiska
+docker compose up -d
+
+# Stop
+docker compose down
+
+# Rebuild
+docker compose up -d --build
+
+# Logi
+docker compose logs -f app
+
+# Shell wewnatrz kontenera
+docker exec -it {{DOCKER_CONTAINER}} bash
+
+# Lista kontenerow
+docker compose ps
+```
+
+## Artisan w Docker
+
+```bash
+# Migracje
+docker exec {{DOCKER_CONTAINER}} php artisan migrate
+docker exec {{DOCKER_CONTAINER}} php artisan migrate:rollback
+docker exec {{DOCKER_CONTAINER}} php artisan migrate:fresh --seed
+
+# Cache
+docker exec {{DOCKER_CONTAINER}} php artisan optimize:clear
+docker exec {{DOCKER_CONTAINER}} php artisan config:cache
+docker exec {{DOCKER_CONTAINER}} php artisan route:cache
+
+# Queue
+docker exec {{DOCKER_CONTAINER}} php artisan queue:work --tries=3
+docker exec {{DOCKER_CONTAINER}} php artisan horizon
+
+# Generowanie
+docker exec {{DOCKER_CONTAINER}} php artisan make:model Feature -mfcr
+docker exec {{DOCKER_CONTAINER}} php artisan make:test FeatureTest --unit
+docker exec {{DOCKER_CONTAINER}} php artisan make:request StoreFeatureRequest
+
+# Testy
+docker exec {{DOCKER_CONTAINER}} php artisan test
+docker exec {{DOCKER_CONTAINER}} php artisan test --filter=FeatureTest
+docker exec {{DOCKER_CONTAINER}} php artisan test --coverage
+```
+
+## docker-compose.yml - typowa struktura
+
+```yaml
+services:
+  app:
+    build:
+      context: .
+      dockerfile: docker/app/Dockerfile
+    volumes:
+      - ./:/var/www/html
+      - ./docker/php/local.ini:/usr/local/etc/php/conf.d/local.ini
+    ports:
+      - "${APP_PORT:-80}:80"
+    depends_on:
+      - postgres
+      - redis
+    environment:
+      PHP_IDE_CONFIG: "serverName=localhost"
+
+  horizon:
+    build:
+      context: .
+      dockerfile: docker/app/Dockerfile
+    command: php artisan horizon
+    depends_on:
+      - postgres
+      - redis
+    restart: unless-stopped
+
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: "${DB_DATABASE}"
+      POSTGRES_USER: "${DB_USERNAME}"
+      POSTGRES_PASSWORD: "${DB_PASSWORD}"
+    ports:
+      - "${DB_PORT:-5432}:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:alpine
+    ports:
+      - "${REDIS_PORT:-6379}:6379"
+
+  mailpit:
+    image: axllent/mailpit:latest
+    ports:
+      - "8025:8025"
+      - "1025:1025"
+
+volumes:
+  postgres-data:
+```
+
+## Dockerfile - multi-stage build
+
+```dockerfile
+# Stage 1: Frontend build
+FROM node:20-alpine AS frontend
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY resources/ resources/
+COPY vite.config.ts tsconfig.json ./
+RUN npm run build
+
+# Stage 2: PHP application
+FROM php:8.3-apache
+WORKDIR /var/www/html
+
+# System dependencies
+RUN apt-get update && apt-get install -y \
+    libpq-dev libzip-dev zip unzip git \
+    && docker-php-ext-install pdo_pgsql zip opcache
+
+# Composer
+COPY --from=composer:latest /usr/bin/composer /usr/bin/composer
+
+# Application
+COPY . .
+COPY --from=frontend /app/public/build public/build
+
+RUN composer install --optimize-autoloader --no-dev \
+    && php artisan storage:link \
+    && chown -R www-data:www-data storage bootstrap/cache
+
+EXPOSE 80
+CMD ["apache2-foreground"]
+```
+
+## Debugowanie
+
+```bash
+# Logi aplikacji (dzienne pliki!)
+docker exec {{DOCKER_CONTAINER}} tail -f storage/logs/laravel-$(date +%Y-%m-%d).log
+
+# Logi kontenera
+docker compose logs -f app
+
+# Status Horizon (kolejki)
+docker exec {{DOCKER_CONTAINER}} php artisan horizon:status
+
+# Sprawdz konfiguracje
+docker exec {{DOCKER_CONTAINER}} php artisan config:show database
+docker exec {{DOCKER_CONTAINER}} php artisan route:list --path=api/feature
+
+# Czyszczenie po zmianach
+docker exec {{DOCKER_CONTAINER}} php artisan optimize:clear
+docker exec {{DOCKER_CONTAINER}} composer dump-autoload
+```
+
+## Zasady
+
+1. **Zawsze Docker** - komendy PHP/Artisan/Composer w kontenerze, nigdy na hoscie
+2. **Pelna nazwa kontenera** - `{{DOCKER_CONTAINER}}`, nie `docker compose exec app`
+3. **Logi dzienne** - `laravel-YYYY-MM-DD.log`, nie `laravel.log`
+4. **`optimize:clear`** - po zmianach konfiguracji, routow, zmiennych
+5. **Multi-stage build** - frontend oddzielnie, PHP oddzielnie
+6. **Volumes** - kod montowany przez volume w dev, kopiowany w prod
+7. **Horizon** - oddzielny kontener dla kolejek, `restart: unless-stopped`
+8. **Env** - `${VAR:-default}` w docker-compose, `.env` dla Laravel

package/templates/packs/docker/_guidelines.md

@@ -0,0 +1,10 @@
+
+
+---
+
+## Docker
+
+- Container: `{{DOCKER_CONTAINER}}`
+- All commands run inside container: `docker exec {{DOCKER_CONTAINER}} ...`
+- List containers: `docker compose ps`
+- Logs: `docker compose logs -f [service]`

package/templates/packs/docker/pack.json

@@ -0,0 +1,8 @@
+{
+  "name": "Docker",
+  "description": "Docker Compose — komendy w kontenerze",
+  "default": false,
+  "placeholders": {
+    "DOCKER_CONTAINER": { "question": "Nazwa kontenera Docker", "default": "app" }
+  }
+}

package/templates/packs/laravel/_ai/instructions/api-resource.instructions.md

@@ -0,0 +1,251 @@
+---
+applyTo: "**/*Resource*.php,**/*Request*.php,**/*Policy*.php,**/*Filter*.php"
+---
+
+# API Resources, Form Requests, Policies, Filters - Instrukcje
+
+## API Resources (transformery)
+
+Formatuja odpowiedz API - nigdy nie zwracaj modelu bezposrednio:
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Http\Resources;
+
+use Illuminate\Http\Resources\Json\JsonResource;
+
+class FeatureResource extends JsonResource
+{
+    public function toArray($request): array
+    {
+        return [
+            'id' => $this->getId(),
+            'name' => $this->getName(),
+            'description' => $this->getDescription(),
+            'status' => $this->getStatus()->value,
+            'createdAt' => $this->getCreatedAt()->toIso8601String(),
+            'author' => UserResource::make($this->whenLoaded(self::RELATION_AUTHOR)),
+            'category' => CategoryResource::make($this->whenLoaded(self::RELATION_CATEGORY)),
+        ];
+    }
+}
+```
+
+### Collection Resource
+
+```php
+class FeatureCollection extends ResourceCollection
+{
+    public $collects = FeatureResource::class;
+
+    public function toArray($request): array
+    {
+        return [
+            'data' => $this->collection,
+            'meta' => [
+                'total' => $this->total(),
+                'perPage' => $this->perPage(),
+                'currentPage' => $this->currentPage(),
+            ],
+        ];
+    }
+}
+```
+
+## Form Requests (walidacja)
+
+Kazdy endpoint z danymi wejsciowymi ma Form Request:
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Http\Requests;
+
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class StoreFeatureRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return $this->user()->can('create', Feature::class);
+    }
+
+    public function rules(): array
+    {
+        return [
+            'name' => ['required', 'string', 'min:2', 'max:255'],
+            'description' => ['nullable', 'string', 'max:5000'],
+            'category_id' => ['nullable', 'integer', 'exists:categories,id'],
+            'status' => ['required', Rule::in(FeatureStatus::cases())],
+            'tags' => ['nullable', 'array'],
+            'tags.*' => ['string', 'max:50'],
+        ];
+    }
+
+    public function messages(): array
+    {
+        return [
+            'name.required' => __('feature.validation.name_required'),
+            'name.max' => __('feature.validation.name_max'),
+        ];
+    }
+}
+```
+
+### Index/List Request z filtrowaniem i sortowaniem
+
+```php
+class IndexFeatureRequest extends FormRequest
+{
+    public function rules(): array
+    {
+        return [
+            'filter' => ['nullable', 'array'],
+            'filter.name' => ['nullable', 'string'],
+            'filter.status' => ['nullable', Rule::in(FeatureStatus::cases())],
+            'filter.dateFrom' => ['nullable', 'date'],
+            'filter.dateTo' => ['nullable', 'date', 'after_or_equal:filter.dateFrom'],
+            'sort' => ['nullable', 'array'],
+            'sort.*' => ['string', Rule::in([
+                'name', '-name',
+                'createdAt', '-createdAt',
+                'status', '-status',
+            ])],
+            'page' => ['required', 'integer', 'min:1'],
+            'limit' => ['required', 'integer', 'min:1', 'max:100'],
+        ];
+    }
+}
+```
+
+## Policies (autoryzacja)
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Http\Policies;
+
+use App\Models\User;
+
+class FeaturePolicy extends BasePolicy
+{
+    public const MODULE_PERMISSION = Permission::FEATURES;
+
+    public function viewAny(User $user): bool
+    {
+        return $user->hasPermission(self::MODULE_PERMISSION);
+    }
+
+    public function view(User $user, Feature $feature): bool
+    {
+        return $this->viewAny($user)
+            && $feature->getUserId() === $user->getId();
+    }
+
+    public function create(User $user): bool
+    {
+        return $user->hasPermission(self::MODULE_PERMISSION);
+    }
+
+    public function update(User $user, Feature $feature): bool
+    {
+        return $this->admin($user)
+            || $feature->getUserId() === $user->getId();
+    }
+
+    public function delete(User $user, Feature $feature): bool
+    {
+        return $this->admin($user);
+    }
+
+    public function admin(User $user): bool
+    {
+        return $this->moduleAdmin($user);
+    }
+}
+```
+
+### Uzycie w kontrolerze
+
+```php
+// W kontrolerze - authorize przez can()
+public function update(UpdateFeatureRequest $request, int $featureId): JsonResponse
+{
+    $feature = $this->service->findOrFail($featureId);
+    $this->authorize('update', $feature);
+
+    // ...
+}
+
+// W routach
+Route::get('/features', [FeatureController::class, 'index'])
+    ->can('viewAny', Feature::class);
+```
+
+## Custom Query Filters (Spatie QueryBuilder)
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Database\Filters;
+
+use Spatie\QueryBuilder\Filters\Filter;
+use Illuminate\Database\Eloquent\Builder;
+
+class DateRangeFilter implements Filter
+{
+    public function __construct(
+        private readonly string $column,
+    ) {}
+
+    public function __invoke(Builder $query, $value, string $property): void
+    {
+        if (is_array($value)) {
+            if (isset($value['from'])) {
+                $query->where($this->column, '>=', Carbon::parse($value['from']));
+            }
+            if (isset($value['to'])) {
+                $query->where($this->column, '<=', Carbon::parse($value['to']));
+            }
+        }
+    }
+}
+```
+
+### Rejestracja w modelu
+
+```php
+class FeatureModel extends Model
+{
+    public static function allowedFilters(): array
+    {
+        return [
+            AllowedFilter::exact('status', self::COLUMN_STATUS),
+            AllowedFilter::partial('name', self::COLUMN_NAME),
+            AllowedFilter::custom('date', new DateRangeFilter(self::COLUMN_CREATED_AT)),
+            AllowedFilter::exact('category', self::RELATION_CATEGORY . '.id'),
+        ];
+    }
+
+    public static function allowedSorts(): array
+    {
+        return [
+            AllowedSort::field('name', self::COLUMN_NAME),
+            AllowedSort::field('createdAt', self::COLUMN_CREATED_AT),
+        ];
+    }
+}
+```
+
+## Zasady
+
+1. **Resource** - nigdy nie zwracaj modelu, zawsze Resource
+2. **`whenLoaded()`** - dla relacji w Resource, zapobiega N+1
+3. **Form Request** - `authorize()` + `rules()`, waliduj filtry i sortowania
+4. **Policy** - CRUD nazwy (`view`, `viewAny`, `create`, `update`, `delete`)
+5. **`->can()`** - uzyj w routach lub `$this->authorize()` w kontrolerze
+6. **Filters** - custom filtr implementuje `Spatie\QueryBuilder\Filters\Filter`
+7. **Kolumny jako stale** - `self::COLUMN_NAME`, nie magic strings
+8. **Tlumaczenia** - `messages()` w Form Request uzywaja `__('klucz')`