autoworkflow 3.1.4 → 3.5.0

package/.claude/skills/typeorm.md

@@ -0,0 +1,368 @@
+# TypeORM Skill
+
+## Data Source Configuration
+\`\`\`typescript
+// src/data-source.ts
+import { DataSource } from 'typeorm';
+import { User } from './entities/User';
+import { Post } from './entities/Post';
+
+export const AppDataSource = new DataSource({
+  type: 'postgres',
+  host: process.env.DB_HOST,
+  port: parseInt(process.env.DB_PORT || '5432'),
+  username: process.env.DB_USER,
+  password: process.env.DB_PASSWORD,
+  database: process.env.DB_NAME,
+  synchronize: false, // Use migrations in production!
+  logging: process.env.NODE_ENV === 'development',
+  entities: [User, Post],
+  migrations: ['src/migrations/*.ts'],
+  subscribers: ['src/subscribers/*.ts'],
+});
+
+// Initialize
+await AppDataSource.initialize();
+\`\`\`
+
+## Entity Definition
+\`\`\`typescript
+import {
+  Entity, PrimaryGeneratedColumn, Column, CreateDateColumn,
+  UpdateDateColumn, DeleteDateColumn, OneToMany, ManyToOne,
+  ManyToMany, JoinTable, Index, BeforeInsert, AfterLoad
+} from 'typeorm';
+
+@Entity('users')
+@Index(['email'])
+@Index(['createdAt'])
+export class User {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column({ unique: true })
+  email: string;
+
+  @Column()
+  name: string;
+
+  @Column({ select: false }) // Excluded from default selects
+  password: string;
+
+  @Column({ type: 'enum', enum: ['user', 'admin'], default: 'user' })
+  role: 'user' | 'admin';
+
+  @Column({ type: 'jsonb', nullable: true })
+  settings: Record<string, unknown>;
+
+  @OneToMany(() => Post, (post) => post.author)
+  posts: Post[];
+
+  @ManyToMany(() => Role, (role) => role.users)
+  @JoinTable({ name: 'user_roles' })
+  roles: Role[];
+
+  @CreateDateColumn()
+  createdAt: Date;
+
+  @UpdateDateColumn()
+  updatedAt: Date;
+
+  @DeleteDateColumn() // Soft delete
+  deletedAt: Date | null;
+
+  // Lifecycle hooks
+  @BeforeInsert()
+  async hashPassword() {
+    if (this.password) {
+      this.password = await bcrypt.hash(this.password, 10);
+    }
+  }
+
+  // Computed property (not persisted)
+  fullName: string;
+
+  @AfterLoad()
+  computeFullName() {
+    this.fullName = \`\${this.firstName} \${this.lastName}\`;
+  }
+}
+
+@Entity('posts')
+export class Post {
+  @PrimaryGeneratedColumn('uuid')
+  id: string;
+
+  @Column()
+  title: string;
+
+  @Column({ type: 'text', nullable: true })
+  content: string;
+
+  @Column({ default: false })
+  published: boolean;
+
+  @ManyToOne(() => User, (user) => user.posts, { onDelete: 'CASCADE' })
+  author: User;
+
+  @Column()
+  authorId: string;
+
+  @CreateDateColumn()
+  createdAt: Date;
+}
+\`\`\`
+
+## Repository Patterns
+\`\`\`typescript
+// Get repository
+const userRepository = AppDataSource.getRepository(User);
+
+// Find operations
+const user = await userRepository.findOne({
+  where: { id },
+  relations: ['posts', 'roles'],
+});
+
+const user = await userRepository.findOneOrFail({ where: { id } }); // Throws if not found
+
+const users = await userRepository.find({
+  where: { role: 'user' },
+  relations: ['posts'],
+  order: { createdAt: 'DESC' },
+  skip: 0,
+  take: 20,
+  select: ['id', 'email', 'name', 'createdAt'],
+});
+
+// Complex where conditions
+const users = await userRepository.find({
+  where: [
+    { role: 'admin' },
+    { email: Like('%@company.com') },
+  ], // OR condition
+});
+
+const users = await userRepository.find({
+  where: {
+    role: 'user',
+    createdAt: MoreThan(new Date('2024-01-01')),
+  }, // AND condition
+});
+
+// Create & Save
+const user = userRepository.create({
+  email: 'user@example.com',
+  name: 'John',
+});
+await userRepository.save(user);
+
+// Or in one step
+const user = await userRepository.save({
+  email: 'user@example.com',
+  name: 'John',
+});
+
+// Update
+await userRepository.update({ id }, { name: 'Jane' });
+
+// Soft delete (with @DeleteDateColumn)
+await userRepository.softDelete({ id });
+await userRepository.restore({ id }); // Restore soft-deleted
+
+// Hard delete
+await userRepository.delete({ id });
+\`\`\`
+
+## QueryBuilder
+\`\`\`typescript
+// Select query builder
+const users = await userRepository
+  .createQueryBuilder('user')
+  .leftJoinAndSelect('user.posts', 'post')
+  .where('user.role = :role', { role: 'user' })
+  .andWhere('post.published = :published', { published: true })
+  .orderBy('user.createdAt', 'DESC')
+  .skip(0)
+  .take(20)
+  .getMany();
+
+// With subquery
+const usersWithPostCount = await userRepository
+  .createQueryBuilder('user')
+  .loadRelationCountAndMap('user.postCount', 'user.posts')
+  .getMany();
+
+// Select specific fields
+const userEmails = await userRepository
+  .createQueryBuilder('user')
+  .select(['user.id', 'user.email'])
+  .where('user.role = :role', { role: 'admin' })
+  .getRawMany();
+
+// Aggregations
+const stats = await userRepository
+  .createQueryBuilder('user')
+  .select('user.role', 'role')
+  .addSelect('COUNT(*)', 'count')
+  .groupBy('user.role')
+  .getRawMany();
+
+// Update with query builder
+await userRepository
+  .createQueryBuilder()
+  .update(User)
+  .set({ lastLoginAt: new Date() })
+  .where('id = :id', { id })
+  .execute();
+
+// Delete with query builder
+await userRepository
+  .createQueryBuilder()
+  .delete()
+  .from(User)
+  .where('deletedAt IS NOT NULL')
+  .andWhere('deletedAt < :date', { date: thirtyDaysAgo })
+  .execute();
+\`\`\`
+
+## Transactions
+\`\`\`typescript
+// Using transaction manager
+await AppDataSource.transaction(async (manager) => {
+  const userRepo = manager.getRepository(User);
+  const postRepo = manager.getRepository(Post);
+
+  const user = await userRepo.save({
+    email: 'test@example.com',
+    name: 'Test',
+  });
+
+  await postRepo.save({
+    title: 'First Post',
+    authorId: user.id,
+  });
+
+  // If any operation fails, all are rolled back
+});
+
+// Using query runner (more control)
+const queryRunner = AppDataSource.createQueryRunner();
+await queryRunner.connect();
+await queryRunner.startTransaction();
+
+try {
+  await queryRunner.manager.save(User, userData);
+  await queryRunner.manager.save(Post, postData);
+  await queryRunner.commitTransaction();
+} catch (err) {
+  await queryRunner.rollbackTransaction();
+  throw err;
+} finally {
+  await queryRunner.release();
+}
+\`\`\`
+
+## Custom Repositories
+\`\`\`typescript
+// Custom repository with DataSource
+export const UserRepository = AppDataSource.getRepository(User).extend({
+  async findByEmail(email: string): Promise<User | null> {
+    return this.findOne({ where: { email } });
+  },
+
+  async findActiveWithPosts(): Promise<User[]> {
+    return this.find({
+      where: { deletedAt: IsNull() },
+      relations: ['posts'],
+      order: { createdAt: 'DESC' },
+    });
+  },
+
+  async softDeleteOldUsers(days: number): Promise<number> {
+    const date = new Date();
+    date.setDate(date.getDate() - days);
+
+    const result = await this.softDelete({
+      lastLoginAt: LessThan(date),
+    });
+
+    return result.affected || 0;
+  },
+});
+
+// Usage
+const user = await UserRepository.findByEmail('test@example.com');
+\`\`\`
+
+## Migrations
+\`\`\`bash
+# Generate migration from entity changes
+npx typeorm migration:generate src/migrations/AddUserRole -d src/data-source.ts
+
+# Create empty migration
+npx typeorm migration:create src/migrations/SeedData
+
+# Run migrations
+npx typeorm migration:run -d src/data-source.ts
+
+# Revert last migration
+npx typeorm migration:revert -d src/data-source.ts
+\`\`\`
+
+\`\`\`typescript
+// Migration file example
+export class AddUserRole1234567890 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(\`
+      ALTER TABLE "users" ADD "role" varchar DEFAULT 'user'
+    \`);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(\`
+      ALTER TABLE "users" DROP COLUMN "role"
+    \`);
+  }
+}
+\`\`\`
+
+## Entity Subscribers
+\`\`\`typescript
+@EventSubscriber()
+export class UserSubscriber implements EntitySubscriberInterface<User> {
+  listenTo() {
+    return User;
+  }
+
+  beforeInsert(event: InsertEvent<User>) {
+    console.log('Before insert:', event.entity);
+  }
+
+  afterInsert(event: InsertEvent<User>) {
+    // Send welcome email, log audit, etc.
+  }
+
+  afterUpdate(event: UpdateEvent<User>) {
+    if (event.updatedColumns.find(c => c.propertyName === 'email')) {
+      // Email changed, send verification
+    }
+  }
+}
+\`\`\`
+
+## ❌ DON'T
+- Use \`synchronize: true\` in production
+- Forget to handle N+1 queries (use relations or QueryBuilder joins)
+- Use \`find()\` without limits on large tables
+- Put business logic in entities
+- Use raw queries without parameter binding
+
+## ✅ DO
+- Use migrations for schema changes
+- Use QueryBuilder for complex queries
+- Use transactions for multi-step operations
+- Use soft deletes for important data
+- Use \`select: false\` for sensitive fields
+- Use entity subscribers for side effects
+- Create custom repository methods for reusable queries

package/.claude/skills/vitest.md

@@ -0,0 +1,330 @@
+# Vitest Skill
+
+## Test Structure
+\`\`\`typescript
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+
+describe('UserService', () => {
+  let service: UserService;
+  let mockDb: { findUser: ReturnType<typeof vi.fn> };
+
+  beforeEach(() => {
+    mockDb = { findUser: vi.fn() };
+    service = new UserService(mockDb);
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('getUser', () => {
+    it('should return user when found', async () => {
+      // Arrange
+      mockDb.findUser.mockResolvedValue({ id: '1', name: 'Test' });
+
+      // Act
+      const result = await service.getUser('1');
+
+      // Assert
+      expect(result).toEqual({ id: '1', name: 'Test' });
+      expect(mockDb.findUser).toHaveBeenCalledWith('1');
+    });
+
+    it('should throw when user not found', async () => {
+      mockDb.findUser.mockResolvedValue(null);
+
+      await expect(service.getUser('1')).rejects.toThrow('Not found');
+    });
+  });
+});
+\`\`\`
+
+## Mocking
+
+### Function Mocks
+\`\`\`typescript
+import { vi, expect } from 'vitest';
+
+// Basic mock
+const mockFn = vi.fn();
+mockFn.mockReturnValue('default');
+mockFn.mockReturnValueOnce('first call');
+
+// Async mocks
+const mockAsync = vi.fn();
+mockAsync.mockResolvedValue({ data: 'success' });
+mockAsync.mockRejectedValue(new Error('Failed'));
+
+// Implementation mock
+const mockImpl = vi.fn((x: number) => x * 2);
+
+// Assertions
+expect(mockFn).toHaveBeenCalled();
+expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
+expect(mockFn).toHaveBeenCalledTimes(2);
+expect(mockFn).toHaveBeenLastCalledWith('lastArg');
+expect(mockFn).toHaveReturnedWith('value');
+
+// Reset mock
+mockFn.mockClear();  // Clear call history
+mockFn.mockReset();  // Clear history + implementation
+mockFn.mockRestore(); // Restore original (for spies)
+\`\`\`
+
+### Module Mocks
+\`\`\`typescript
+// Mock entire module (hoisted to top)
+vi.mock('./userService', () => ({
+  UserService: vi.fn().mockImplementation(() => ({
+    getUser: vi.fn().mockResolvedValue({ id: '1' }),
+  })),
+}));
+
+// Mock with factory
+vi.mock('./api', () => ({
+  fetchUser: vi.fn().mockResolvedValue({ id: '1', name: 'Test' }),
+  fetchPosts: vi.fn(),
+}));
+
+// Partial mock (keep some real implementations)
+vi.mock('./utils', async () => {
+  const actual = await vi.importActual('./utils');
+  return {
+    ...actual,
+    formatDate: vi.fn().mockReturnValue('2024-01-01'),
+  };
+});
+
+// Auto-mock all exports
+vi.mock('./service'); // All exports become vi.fn()
+
+// Get mocked module
+import { fetchUser } from './api';
+const mockedFetchUser = vi.mocked(fetchUser);
+\`\`\`
+
+### Spy on Methods
+\`\`\`typescript
+// Spy on object method
+const spy = vi.spyOn(console, 'log');
+spy.mockImplementation(() => {}); // Suppress output
+
+// Spy on prototype
+const saveSpy = vi.spyOn(UserService.prototype, 'save');
+saveSpy.mockResolvedValue({ id: '1' });
+
+// Spy on getter/setter
+vi.spyOn(object, 'property', 'get').mockReturnValue('mocked');
+
+// Restore original
+spy.mockRestore();
+\`\`\`
+
+### Global Mocks
+\`\`\`typescript
+// Mock global function
+vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+  ok: true,
+  json: () => Promise.resolve({ data: 'test' }),
+}));
+
+// Mock global object
+vi.stubGlobal('localStorage', {
+  getItem: vi.fn(),
+  setItem: vi.fn(),
+  clear: vi.fn(),
+});
+
+// Mock environment variables
+vi.stubEnv('API_URL', 'http://test.com');
+
+// Unstub
+vi.unstubAllGlobals();
+vi.unstubAllEnvs();
+\`\`\`
+
+## Timer Mocks
+\`\`\`typescript
+import { vi, beforeEach, afterEach, it, expect } from 'vitest';
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.useRealTimers();
+});
+
+it('should debounce calls', () => {
+  const callback = vi.fn();
+  const debounced = debounce(callback, 1000);
+
+  debounced();
+  debounced();
+  debounced();
+
+  expect(callback).not.toHaveBeenCalled();
+
+  vi.advanceTimersByTime(1000);
+
+  expect(callback).toHaveBeenCalledTimes(1);
+});
+
+it('should handle async timers', async () => {
+  const callback = vi.fn();
+  setTimeout(callback, 1000);
+
+  await vi.advanceTimersByTimeAsync(1000);
+  expect(callback).toHaveBeenCalled();
+});
+
+// Mock Date
+vi.setSystemTime(new Date('2024-01-15'));
+expect(new Date().toISOString()).toBe('2024-01-15T00:00:00.000Z');
+
+// Run all timers
+vi.runAllTimers();
+vi.runOnlyPendingTimers(); // Avoid infinite loops with recursive timers
+\`\`\`
+
+## Snapshot Testing
+\`\`\`typescript
+import { expect, it } from 'vitest';
+
+// File snapshot
+it('should match snapshot', () => {
+  const result = formatUser({ name: 'John', email: 'john@example.com' });
+  expect(result).toMatchSnapshot();
+});
+
+// Inline snapshot
+it('should match inline snapshot', () => {
+  expect(formatUser(user)).toMatchInlineSnapshot(\`
+    {
+      "name": "John Doe",
+      "email": "john@example.com"
+    }
+  \`);
+});
+
+// Update snapshots: vitest --update or vitest -u
+\`\`\`
+
+## Test Utilities
+\`\`\`typescript
+// Parameterized tests
+import { describe, it, expect } from 'vitest';
+
+describe.each([
+  { input: 1, expected: 2 },
+  { input: 2, expected: 4 },
+  { input: 3, expected: 6 },
+])('double($input)', ({ input, expected }) => {
+  it(\`should return \${expected}\`, () => {
+    expect(double(input)).toBe(expected);
+  });
+});
+
+// Skip and focus
+describe.skip('skipped suite', () => {});
+it.skip('skipped test', () => {});
+describe.only('focused suite', () => {}); // Only run this
+it.only('focused test', () => {}); // Only run this
+
+// Todo tests
+it.todo('should implement this feature');
+
+// Concurrent tests (run in parallel)
+describe.concurrent('parallel tests', () => {
+  it('test 1', async () => {});
+  it('test 2', async () => {});
+});
+
+// Retry flaky tests
+it('flaky test', { retry: 3 }, async () => {});
+
+// Timeout
+it('slow test', { timeout: 10000 }, async () => {});
+\`\`\`
+
+## Type Testing
+\`\`\`typescript
+import { expectTypeOf, assertType } from 'vitest';
+
+it('should have correct types', () => {
+  // Check type equality
+  expectTypeOf(getUser).toBeFunction();
+  expectTypeOf(getUser).parameter(0).toBeString();
+  expectTypeOf(getUser).returns.resolves.toMatchTypeOf<User>();
+
+  // Check assignability
+  expectTypeOf<string>().toMatchTypeOf<string | number>();
+
+  // Assert type (compile-time only)
+  assertType<string>('hello');
+});
+\`\`\`
+
+## In-Source Testing
+\`\`\`typescript
+// src/utils.ts - tests in same file
+export function add(a: number, b: number): number {
+  return a + b;
+}
+
+// Only included when running tests
+if (import.meta.vitest) {
+  const { it, expect } = import.meta.vitest;
+
+  it('add', () => {
+    expect(add(1, 2)).toBe(3);
+  });
+}
+\`\`\`
+
+## Configuration (vitest.config.ts)
+\`\`\`typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true, // Use describe, it, expect without imports
+    environment: 'node', // or 'jsdom', 'happy-dom'
+    include: ['**/*.{test,spec}.{ts,tsx}'],
+    exclude: ['node_modules', 'dist'],
+    coverage: {
+      provider: 'v8', // or 'istanbul'
+      reporter: ['text', 'html', 'lcov'],
+      exclude: ['**/*.d.ts', '**/*.test.ts'],
+      thresholds: {
+        branches: 80,
+        functions: 80,
+        lines: 80,
+        statements: 80,
+      },
+    },
+    setupFiles: ['./vitest.setup.ts'],
+    alias: {
+      '@': './src',
+    },
+    mockReset: true, // Reset mocks between tests
+  },
+});
+\`\`\`
+
+## ❌ DON'T
+- Test implementation details
+- Share state between tests
+- Use \`.only\` in committed code
+- Write flaky tests (timing-dependent)
+- Forget to restore mocks
+- Mock everything (test integrations too)
+
+## ✅ DO
+- Use vi.mock for module mocking
+- Clear mocks between tests (mockReset: true)
+- Use vi.mocked() for type-safe mocked imports
+- Use fake timers for time-dependent code
+- Use concurrent tests for performance
+- Leverage in-source testing for utilities
+- Use type testing for public APIs