autoworkflow 3.1.5 → 3.5.0

package/.claude/skills/doctrine.md

@@ -0,0 +1,473 @@
+# Doctrine ORM Skill
+
+## Entity Definition
+\`\`\`php
+<?php
+
+namespace App\\Entity;
+
+use App\\Repository\\UserRepository;
+use Doctrine\\Common\\Collections\\ArrayCollection;
+use Doctrine\\Common\\Collections\\Collection;
+use Doctrine\\DBAL\\Types\\Types;
+use Doctrine\\ORM\\Mapping as ORM;
+use Symfony\\Component\\Serializer\\Attribute\\Groups;
+
+#[ORM\\Entity(repositoryClass: UserRepository::class)]
+#[ORM\\Table(name: 'users')]
+#[ORM\\Index(columns: ['email'], name: 'idx_users_email')]
+#[ORM\\HasLifecycleCallbacks]
+class User
+{
+    #[ORM\\Id]
+    #[ORM\\GeneratedValue(strategy: 'CUSTOM')]
+    #[ORM\\CustomIdGenerator(class: UuidGenerator::class)]
+    #[ORM\\Column(type: Types::GUID)]
+    #[Groups(['user:list', 'user:read'])]
+    private string $id;
+
+    #[ORM\\Column(type: Types::STRING, length: 255, unique: true)]
+    #[Groups(['user:list', 'user:read'])]
+    private string $email;
+
+    #[ORM\\Column(type: Types::STRING, length: 100)]
+    #[Groups(['user:list', 'user:read'])]
+    private string $name;
+
+    #[ORM\\Column(type: Types::STRING)]
+    private string $password;
+
+    #[ORM\\Column(type: Types::BOOLEAN)]
+    #[Groups(['user:read'])]
+    private bool $isActive = true;
+
+    #[ORM\\Column(type: Types::DATETIME_IMMUTABLE)]
+    #[Groups(['user:read'])]
+    private \\DateTimeImmutable $createdAt;
+
+    #[ORM\\Column(type: Types::DATETIME_IMMUTABLE, nullable: true)]
+    private ?\\DateTimeImmutable $updatedAt = null;
+
+    // Relationships
+    #[ORM\\OneToOne(targetEntity: Profile::class, mappedBy: 'user', cascade: ['persist', 'remove'])]
+    #[Groups(['user:read'])]
+    private ?Profile $profile = null;
+
+    #[ORM\\OneToMany(targetEntity: Post::class, mappedBy: 'author', cascade: ['persist'], orphanRemoval: true)]
+    #[ORM\\OrderBy(['createdAt' => 'DESC'])]
+    private Collection $posts;
+
+    #[ORM\\ManyToMany(targetEntity: Role::class, inversedBy: 'users')]
+    #[ORM\\JoinTable(name: 'user_roles')]
+    private Collection $roles;
+
+    public function __construct()
+    {
+        $this->posts = new ArrayCollection();
+        $this->roles = new ArrayCollection();
+    }
+
+    #[ORM\\PrePersist]
+    public function setCreatedAtValue(): void
+    {
+        $this->createdAt = new \\DateTimeImmutable();
+    }
+
+    #[ORM\\PreUpdate]
+    public function setUpdatedAtValue(): void
+    {
+        $this->updatedAt = new \\DateTimeImmutable();
+    }
+
+    // Relationship helpers
+    public function addPost(Post $post): self
+    {
+        if (!$this->posts->contains($post)) {
+            $this->posts->add($post);
+            $post->setAuthor($this);
+        }
+        return $this;
+    }
+
+    public function removePost(Post $post): self
+    {
+        if ($this->posts->removeElement($post)) {
+            if ($post->getAuthor() === $this) {
+                $post->setAuthor(null);
+            }
+        }
+        return $this;
+    }
+
+    public function addRole(Role $role): self
+    {
+        if (!$this->roles->contains($role)) {
+            $this->roles->add($role);
+        }
+        return $this;
+    }
+
+    // Getters and setters...
+    public function getId(): string { return $this->id; }
+    public function getEmail(): string { return $this->email; }
+    public function setEmail(string $email): self { $this->email = $email; return $this; }
+    // ... etc
+}
+\`\`\`
+
+## Repository with Query Builder
+\`\`\`php
+<?php
+
+namespace App\\Repository;
+
+use App\\Entity\\User;
+use Doctrine\\Bundle\\DoctrineBundle\\Repository\\ServiceEntityRepository;
+use Doctrine\\ORM\\QueryBuilder;
+use Doctrine\\Persistence\\ManagerRegistry;
+
+/**
+ * @extends ServiceEntityRepository<User>
+ */
+final class UserRepository extends ServiceEntityRepository
+{
+    public function __construct(ManagerRegistry $registry)
+    {
+        parent::__construct($registry, User::class);
+    }
+
+    public function findByEmail(string $email): ?User
+    {
+        return $this->findOneBy(['email' => $email]);
+    }
+
+    /**
+     * @return User[]
+     */
+    public function findActiveWithPosts(): array
+    {
+        return $this->createQueryBuilder('u')
+            ->leftJoin('u.posts', 'p')
+            ->addSelect('p')
+            ->where('u.isActive = :active')
+            ->setParameter('active', true)
+            ->orderBy('u.createdAt', 'DESC')
+            ->getQuery()
+            ->getResult();
+    }
+
+    /**
+     * @return User[]
+     */
+    public function findByRole(string $roleName): array
+    {
+        return $this->createQueryBuilder('u')
+            ->innerJoin('u.roles', 'r')
+            ->where('r.name = :role')
+            ->setParameter('role', $roleName)
+            ->getQuery()
+            ->getResult();
+    }
+
+    public function countByStatus(bool $isActive): int
+    {
+        return $this->createQueryBuilder('u')
+            ->select('COUNT(u.id)')
+            ->where('u.isActive = :active')
+            ->setParameter('active', $isActive)
+            ->getQuery()
+            ->getSingleScalarResult();
+    }
+
+    // Paginated query
+    public function createPaginatedQuery(): QueryBuilder
+    {
+        return $this->createQueryBuilder('u')
+            ->where('u.isActive = :active')
+            ->setParameter('active', true)
+            ->orderBy('u.createdAt', 'DESC');
+    }
+
+    // Search with multiple conditions
+    public function search(UserSearchCriteria $criteria): array
+    {
+        $qb = $this->createQueryBuilder('u');
+
+        if ($criteria->email !== null) {
+            $qb->andWhere('u.email LIKE :email')
+               ->setParameter('email', '%' . $criteria->email . '%');
+        }
+
+        if ($criteria->name !== null) {
+            $qb->andWhere('u.name LIKE :name')
+               ->setParameter('name', '%' . $criteria->name . '%');
+        }
+
+        if ($criteria->isActive !== null) {
+            $qb->andWhere('u.isActive = :active')
+               ->setParameter('active', $criteria->isActive);
+        }
+
+        if ($criteria->createdAfter !== null) {
+            $qb->andWhere('u.createdAt > :after')
+               ->setParameter('after', $criteria->createdAfter);
+        }
+
+        return $qb->setMaxResults($criteria->limit)
+                  ->setFirstResult($criteria->offset)
+                  ->getQuery()
+                  ->getResult();
+    }
+}
+\`\`\`
+
+## DQL (Doctrine Query Language)
+\`\`\`php
+<?php
+
+// Named queries in entity
+#[ORM\\Entity]
+#[ORM\\NamedQuery(
+    name: 'User.findActiveByRole',
+    query: 'SELECT u FROM App\\Entity\\User u JOIN u.roles r WHERE u.isActive = true AND r.name = :role'
+)]
+class User { }
+
+// Usage
+$users = $this->em
+    ->createNamedQuery('User.findActiveByRole')
+    ->setParameter('role', 'ADMIN')
+    ->getResult();
+
+// Direct DQL
+$users = $this->em->createQuery(
+    'SELECT u, p FROM App\\Entity\\User u
+     LEFT JOIN u.posts p
+     WHERE u.isActive = :active
+     ORDER BY u.createdAt DESC'
+)
+->setParameter('active', true)
+->getResult();
+
+// Aggregate queries
+$stats = $this->em->createQuery(
+    'SELECT r.name, COUNT(u.id) as userCount
+     FROM App\\Entity\\User u
+     JOIN u.roles r
+     WHERE u.isActive = :active
+     GROUP BY r.name'
+)
+->setParameter('active', true)
+->getResult();
+\`\`\`
+
+## Transactions
+\`\`\`php
+<?php
+
+namespace App\\Service;
+
+use Doctrine\\ORM\\EntityManagerInterface;
+
+final readonly class UserService
+{
+    public function __construct(
+        private EntityManagerInterface $em,
+    ) {}
+
+    public function createWithProfile(CreateUserData $data): User
+    {
+        return $this->em->wrapInTransaction(function () use ($data) {
+            $user = new User();
+            $user->setEmail($data->email);
+            $user->setName($data->name);
+            $this->em->persist($user);
+
+            $profile = new Profile();
+            $profile->setUser($user);
+            $profile->setBio($data->bio);
+            $this->em->persist($profile);
+
+            return $user;
+        });
+    }
+
+    // Manual transaction control
+    public function complexOperation(): void
+    {
+        $this->em->beginTransaction();
+
+        try {
+            // Multiple operations...
+            $this->em->flush();
+            $this->em->commit();
+        } catch (\\Exception $e) {
+            $this->em->rollback();
+            throw $e;
+        }
+    }
+}
+\`\`\`
+
+## Migrations
+\`\`\`bash
+# Create migration
+php bin/console make:migration
+
+# Run migrations
+php bin/console doctrine:migrations:migrate
+
+# Rollback last migration
+php bin/console doctrine:migrations:migrate prev
+
+# Generate migration from entity changes
+php bin/console doctrine:migrations:diff
+\`\`\`
+
+\`\`\`php
+<?php
+// migrations/Version20240115000000.php
+
+declare(strict_types=1);
+
+namespace DoctrineMigrations;
+
+use Doctrine\\DBAL\\Schema\\Schema;
+use Doctrine\\Migrations\\AbstractMigration;
+
+final class Version20240115000000 extends AbstractMigration
+{
+    public function up(Schema $schema): void
+    {
+        $this->addSql('CREATE TABLE users (
+            id UUID NOT NULL,
+            email VARCHAR(255) NOT NULL,
+            name VARCHAR(100) NOT NULL,
+            password VARCHAR(255) NOT NULL,
+            is_active BOOLEAN DEFAULT true NOT NULL,
+            created_at TIMESTAMP(0) WITHOUT TIME ZONE NOT NULL,
+            updated_at TIMESTAMP(0) WITHOUT TIME ZONE DEFAULT NULL,
+            PRIMARY KEY(id)
+        )');
+        $this->addSql('CREATE UNIQUE INDEX idx_users_email ON users (email)');
+    }
+
+    public function down(Schema $schema): void
+    {
+        $this->addSql('DROP TABLE users');
+    }
+}
+\`\`\`
+
+## Lifecycle Callbacks and Events
+\`\`\`php
+<?php
+
+// In entity
+#[ORM\\HasLifecycleCallbacks]
+class User
+{
+    #[ORM\\PrePersist]
+    public function onPrePersist(): void
+    {
+        $this->createdAt = new \\DateTimeImmutable();
+    }
+
+    #[ORM\\PreUpdate]
+    public function onPreUpdate(): void
+    {
+        $this->updatedAt = new \\DateTimeImmutable();
+    }
+
+    #[ORM\\PostPersist]
+    public function onPostPersist(): void
+    {
+        // After insert
+    }
+}
+
+// Event subscriber for complex logic
+namespace App\\EventSubscriber;
+
+use App\\Entity\\User;
+use Doctrine\\Bundle\\DoctrineBundle\\Attribute\\AsDoctrineListener;
+use Doctrine\\ORM\\Event\\PrePersistEventArgs;
+use Doctrine\\ORM\\Events;
+
+#[AsDoctrineListener(event: Events::prePersist)]
+final readonly class UserSubscriber
+{
+    public function __construct(
+        private PasswordHasherInterface $hasher,
+    ) {}
+
+    public function prePersist(PrePersistEventArgs $args): void
+    {
+        $entity = $args->getObject();
+
+        if (!$entity instanceof User) {
+            return;
+        }
+
+        // Hash password before insert
+        if ($entity->getPlainPassword() !== null) {
+            $entity->setPassword(
+                $this->hasher->hashPassword($entity, $entity->getPlainPassword())
+            );
+            $entity->eraseCredentials();
+        }
+    }
+}
+\`\`\`
+
+## Performance Optimization
+\`\`\`php
+<?php
+
+// Eager loading to avoid N+1
+$users = $this->createQueryBuilder('u')
+    ->leftJoin('u.posts', 'p')
+    ->addSelect('p')  // Must addSelect for eager loading
+    ->getQuery()
+    ->getResult();
+
+// Partial loading (only specific fields)
+$users = $this->createQueryBuilder('u')
+    ->select('partial u.{id, email, name}')
+    ->getQuery()
+    ->getResult();
+
+// DTO projection (best performance)
+$users = $this->createQueryBuilder('u')
+    ->select('NEW App\\DTO\\UserDTO(u.id, u.email, u.name)')
+    ->getQuery()
+    ->getResult();
+
+// Batch processing
+$batchSize = 100;
+$i = 0;
+foreach ($users as $user) {
+    $user->setIsActive(false);
+
+    if (++$i % $batchSize === 0) {
+        $this->em->flush();
+        $this->em->clear();  // Detach all entities
+    }
+}
+$this->em->flush();
+\`\`\`
+
+## ✅ DO
+- Use typed properties and return types
+- Use \`#[ORM\\HasLifecycleCallbacks]\` for entity hooks
+- Use QueryBuilder for complex queries
+- Use \`wrapInTransaction\` for multi-entity operations
+- Use \`addSelect\` with joins to avoid N+1
+- Use DTOs for read-only queries
+
+## ❌ DON'T
+- Don't forget \`addSelect\` when joining (causes N+1)
+- Don't use \`$em->find()\` in loops (use batch queries)
+- Don't forget \`$em->flush()\` after changes
+- Don't use \`EAGER\` fetch mode (query explicitly)
+- Don't put heavy logic in lifecycle callbacks

package/.claude/skills/documentation.md

@@ -0,0 +1,182 @@
+# Documentation Skill
+
+## README Structure
+\`\`\`markdown
+# Project Name
+
+Brief description of what it does.
+
+## Quick Start
+\\\`\\\`\\\`bash
+npm install && npm run dev
+\\\`\\\`\\\`
+
+## Features
+- Feature 1
+- Feature 2
+
+## Configuration
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT     | Server port | 3000    |
+
+## Architecture
+See [Architecture Decision Records](./docs/adr/)
+
+## API Reference
+See [API.md](./docs/API.md)
+
+## Contributing
+See [CONTRIBUTING.md](./CONTRIBUTING.md)
+\`\`\`
+
+## Architecture Decision Records (ADR)
+\`\`\`markdown
+# ADR-001: Use PostgreSQL for primary database
+
+## Status
+Accepted
+
+## Context
+We need a database that supports complex queries, transactions,
+and can scale to millions of records.
+
+## Decision
+Use PostgreSQL with Prisma ORM.
+
+## Consequences
+### Positive
+- Strong ACID compliance
+- Excellent query performance
+- Rich ecosystem
+
+### Negative
+- More complex than SQLite for development
+- Requires managed service for production
+\`\`\`
+
+## Changelog (Keep a Changelog format)
+\`\`\`markdown
+# Changelog
+
+## [Unreleased]
+### Added
+- User authentication with OAuth
+
+## [1.2.0] - 2024-01-15
+### Added
+- Dark mode support
+
+### Fixed
+- Memory leak in dashboard component
+
+### Changed
+- Upgraded to React 18
+\`\`\`
+
+## Code Documentation
+\`\`\`typescript
+/**
+ * Calculates the total price including tax and discounts.
+ *
+ * @param items - Array of cart items
+ * @param taxRate - Tax rate as decimal (e.g., 0.08 for 8%)
+ * @returns Total price in cents
+ * @throws {InvalidDiscountError} If discount code is invalid
+ *
+ * @example
+ * const total = calculateTotal(cartItems, 0.08);
+ * // Returns: 10800 (for $100 + 8% tax)
+ */
+function calculateTotal(items: CartItem[], taxRate: number): number { }
+\`\`\`
+
+## Inline Comments Best Practices
+\`\`\`typescript
+// ❌ BAD: Explains "what" (obvious from code)
+// Loop through users
+for (const user of users) { }
+
+// ✅ GOOD: Explains "why" (not obvious)
+// Skip inactive users to avoid sending emails to churned accounts
+for (const user of users.filter(u => u.isActive)) { }
+
+// ✅ GOOD: Explains business logic
+// Discount capped at 50% per legal requirement (see LEGAL-123)
+const finalDiscount = Math.min(discount, 0.5);
+
+// ✅ GOOD: Warns about non-obvious behavior
+// IMPORTANT: This must run before auth middleware initializes
+app.use(corsMiddleware);
+\`\`\`
+
+## Diagrams as Code (Mermaid)
+\`\`\`markdown
+\\\`\\\`\\\`mermaid
+flowchart TD
+    A[User Request] --> B{Authenticated?}
+    B -->|Yes| C[Process Request]
+    B -->|No| D[Return 401]
+    C --> E[Return Response]
+\\\`\\\`\\\`
+
+\\\`\\\`\\\`mermaid
+erDiagram
+    USER ||--o{ POST : creates
+    USER ||--o{ COMMENT : writes
+    POST ||--o{ COMMENT : has
+\\\`\\\`\\\`
+
+\\\`\\\`\\\`mermaid
+sequenceDiagram
+    Client->>+API: POST /login
+    API->>+DB: Verify credentials
+    DB-->>-API: User data
+    API-->>-Client: JWT token
+\\\`\\\`\\\`
+\`\`\`
+
+## API Documentation (OpenAPI)
+\`\`\`yaml
+paths:
+  /users/{id}:
+    get:
+      summary: Get user by ID
+      description: Returns a single user. Requires authentication.
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: User found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+              example:
+                id: "123e4567-e89b-12d3-a456-426614174000"
+                email: "user@example.com"
+                name: "John Doe"
+        '404':
+          description: User not found
+\`\`\`
+
+## ❌ DON'T
+- Document obvious code
+- Let docs become stale
+- Write docs with no examples
+- Use outdated screenshots
+- Write walls of text
+
+## ✅ DO
+- Document the "why", not the "what"
+- Include runnable examples
+- Keep docs near the code
+- Update docs with code changes
+- Use diagrams for complex flows
+- Write ADRs for architectural decisions
+- Keep a changelog for releases