skillstore-cli 1.0.0

package/data/free-skills/devflow-agile/plugin/skills/developer/references/clean-architecture.md

@@ -0,0 +1,361 @@
+# Clean Architecture Reference
+
+## SOLID Principles with Real Code Examples
+
+### Single Responsibility Principle (SRP)
+
+Every module should have one — and only one — reason to change.
+
+**Bad** — One class handles validation, persistence, and notification:
+```typescript
+class OrderService {
+  async createOrder(data: CreateOrderDto) {
+    // Validation
+    if (!data.items?.length) throw new Error('No items');
+    if (data.total < 0) throw new Error('Invalid total');
+
+    // Persistence
+    const order = await this.db.orders.create({ data });
+
+    // Notification
+    await this.mailer.send(order.userEmail, 'Order created', orderTemplate(order));
+
+    return order;
+  }
+}
+```
+
+**Good** — Each concern is a separate class:
+```typescript
+class OrderValidator {
+  validate(data: CreateOrderDto): void {
+    if (!data.items?.length) throw new ValidationError('No items');
+    if (data.total < 0) throw new ValidationError('Invalid total');
+  }
+}
+
+class OrderRepository {
+  async create(data: CreateOrderDto): Promise<Order> {
+    return this.db.orders.create({ data });
+  }
+}
+
+class OrderNotifier {
+  async notifyCreated(order: Order): Promise<void> {
+    await this.mailer.send(order.userEmail, 'Order created', orderTemplate(order));
+  }
+}
+
+class CreateOrderUseCase {
+  constructor(
+    private validator: OrderValidator,
+    private repo: OrderRepository,
+    private notifier: OrderNotifier,
+  ) {}
+
+  async execute(data: CreateOrderDto): Promise<Order> {
+    this.validator.validate(data);
+    const order = await this.repo.create(data);
+    await this.notifier.notifyCreated(order);
+    return order;
+  }
+}
+```
+
+### Open/Closed Principle (OCP)
+
+Open for extension, closed for modification.
+
+**Bad** — Adding a new export format requires modifying existing code:
+```python
+class ReportExporter:
+    def export(self, report: Report, format: str) -> bytes:
+        if format == "pdf":
+            return self._to_pdf(report)
+        elif format == "csv":
+            return self._to_csv(report)
+        # Every new format = another elif
+```
+
+**Good** — New formats are added by creating new classes:
+```python
+class ReportExporter(Protocol):
+    def export(self, report: Report) -> bytes: ...
+
+class PdfExporter:
+    def export(self, report: Report) -> bytes:
+        # PDF generation logic
+        ...
+
+class CsvExporter:
+    def export(self, report: Report) -> bytes:
+        # CSV generation logic
+        ...
+
+# Registry pattern — no modification needed when adding new exporters
+EXPORTERS: dict[str, ReportExporter] = {
+    "pdf": PdfExporter(),
+    "csv": CsvExporter(),
+}
+```
+
+### Liskov Substitution Principle (LSP)
+
+Subtypes must be substitutable for their base types without breaking behavior.
+
+**Bad** — `ReadOnlyRepository` breaks the contract of `Repository`:
+```typescript
+class Repository<T> {
+  async findById(id: string): Promise<T> { /* ... */ }
+  async save(entity: T): Promise<void> { /* ... */ }
+}
+
+class ReadOnlyRepository<T> extends Repository<T> {
+  async save(entity: T): Promise<void> {
+    throw new Error('Cannot save to read-only repository'); // BREAKS LSP
+  }
+}
+```
+
+**Good** — Separate interfaces for read and write:
+```typescript
+interface ReadRepository<T> {
+  findById(id: string): Promise<T>;
+}
+
+interface WriteRepository<T> {
+  save(entity: T): Promise<void>;
+}
+
+interface Repository<T> extends ReadRepository<T>, WriteRepository<T> {}
+```
+
+### Interface Segregation Principle (ISP)
+
+Clients should not be forced to depend on interfaces they do not use.
+
+**Bad** — One fat interface forces all implementations to handle everything:
+```typescript
+interface Worker {
+  writeCode(): void;
+  reviewCode(): void;
+  attendMeeting(): void;
+  manageServer(): void;
+  designUI(): void;
+}
+```
+
+**Good** — Focused interfaces that clients opt into:
+```typescript
+interface Coder { writeCode(): void; }
+interface Reviewer { reviewCode(): void; }
+interface MeetingAttendee { attendMeeting(): void; }
+
+class Developer implements Coder, Reviewer, MeetingAttendee {
+  writeCode() { /* ... */ }
+  reviewCode() { /* ... */ }
+  attendMeeting() { /* ... */ }
+}
+```
+
+## Dependency Inversion: Interface-Based Design
+
+### Dependency Injection Pattern
+
+```typescript
+// 1. Define the port (interface)
+interface PaymentGateway {
+  charge(amount: number, currency: string): Promise<PaymentResult>;
+  refund(transactionId: string): Promise<RefundResult>;
+}
+
+// 2. Implement the adapter
+class StripeGateway implements PaymentGateway {
+  async charge(amount: number, currency: string): Promise<PaymentResult> {
+    return stripe.paymentIntents.create({ amount, currency });
+  }
+  async refund(transactionId: string): Promise<RefundResult> {
+    return stripe.refunds.create({ payment_intent: transactionId });
+  }
+}
+
+// 3. Inject via constructor
+class CheckoutService {
+  constructor(private gateway: PaymentGateway) {} // depends on interface
+
+  async checkout(cart: Cart): Promise<Order> {
+    const payment = await this.gateway.charge(cart.total, cart.currency);
+    // ...
+  }
+}
+
+// 4. Wire up in composition root (main / DI container)
+const gateway = new StripeGateway();
+const checkoutService = new CheckoutService(gateway);
+```
+
+**Benefits**: Swap StripeGateway for MockGateway in tests. Replace Stripe with another provider without changing CheckoutService.
+
+## Clean Architecture Layers
+
+```
+┌─────────────────────────────────────────────┐
+│            Frameworks & Drivers              │  Express, Prisma, React, AWS SDK
+│  (outermost — depends on everything below)  │
+├─────────────────────────────────────────────┤
+│           Interface Adapters                 │  Controllers, Presenters, Gateways
+│  (converts data between use cases and       │  Repository implementations
+│   external formats)                         │
+├─────────────────────────────────────────────┤
+│             Use Cases                        │  Application-specific business rules
+│  (orchestrates entities, enforces workflow)  │  CreateOrder, ProcessPayment
+├─────────────────────────────────────────────┤
+│              Entities                        │  Enterprise-wide business rules
+│  (innermost — depends on nothing)           │  Order, User, Invoice
+└─────────────────────────────────────────────┘
+```
+
+### Dependency Rule
+Dependencies always point **inward**. Inner layers never import from outer layers. Outer layers depend on inner layers through interfaces.
+
+### Practical Folder Structure
+```
+src/
+├── domain/           # Entities + value objects (no external dependencies)
+│   ├── order.ts
+│   └── user.ts
+├── application/      # Use cases + port interfaces
+│   ├── ports/
+│   │   ├── order-repository.port.ts
+│   │   └── payment-gateway.port.ts
+│   └── use-cases/
+│       ├── create-order.use-case.ts
+│       └── process-payment.use-case.ts
+├── infrastructure/   # Adapter implementations
+│   ├── database/
+│   │   └── prisma-order-repository.ts
+│   └── payment/
+│       └── stripe-gateway.ts
+└── presentation/     # Controllers, routes, CLI
+    ├── http/
+    │   └── order.controller.ts
+    └── cli/
+        └── seed.command.ts
+```
+
+## Tech Debt Management
+
+### Identification
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Deliberate** | Conscious shortcut taken with a plan to fix | "Ship without caching, add in next sprint" |
+| **Accidental** | Discovered after the fact | "This module has circular dependencies we didn't notice" |
+| **Bit rot** | Gradual degradation over time | Outdated dependencies, deprecated API usage |
+| **Design debt** | Architecture that no longer fits current needs | Monolith that should be split, wrong database choice |
+
+### Classification Matrix
+
+| | Low Effort to Fix | High Effort to Fix |
+|---|---|---|
+| **High Impact** | Fix now (current sprint) | Plan and schedule (next 1-2 sprints) |
+| **Low Impact** | Fix opportunistically (when touching that code) | Track but deprioritize (backlog) |
+
+### Payoff Strategies
+- **Boy Scout Rule**: Leave code cleaner than you found it — small improvements on every PR
+- **Tech debt budget**: Allocate 15-20% of sprint capacity to debt reduction
+- **Quarterly cleanup sprint**: One sprint per quarter focused entirely on tech debt
+- **Debt-driven refactoring**: When a feature is blocked or slowed by debt, fix the debt first
+
+## Refactoring Patterns
+
+### Extract Method
+**When**: A block of code inside a function does a distinct thing (often preceded by a comment).
+```typescript
+// Before
+function processOrder(order: Order) {
+  // validate inventory
+  for (const item of order.items) {
+    const stock = await getStock(item.productId);
+    if (stock < item.quantity) throw new InsufficientStockError(item.productId);
+  }
+  // ... rest of processing
+}
+
+// After
+function processOrder(order: Order) {
+  await validateInventory(order.items);
+  // ... rest of processing
+}
+
+async function validateInventory(items: OrderItem[]) {
+  for (const item of items) {
+    const stock = await getStock(item.productId);
+    if (stock < item.quantity) throw new InsufficientStockError(item.productId);
+  }
+}
+```
+
+### Replace Conditional with Polymorphism
+**When**: A switch/if-else chain selects behavior based on type.
+```typescript
+// Before
+function calculateShipping(type: string, weight: number): number {
+  if (type === 'standard') return weight * 0.5;
+  if (type === 'express') return weight * 1.5 + 10;
+  if (type === 'overnight') return weight * 3 + 25;
+  throw new Error(`Unknown type: ${type}`);
+}
+
+// After
+interface ShippingCalculator {
+  calculate(weight: number): number;
+}
+
+class StandardShipping implements ShippingCalculator {
+  calculate(weight: number) { return weight * 0.5; }
+}
+class ExpressShipping implements ShippingCalculator {
+  calculate(weight: number) { return weight * 1.5 + 10; }
+}
+class OvernightShipping implements ShippingCalculator {
+  calculate(weight: number) { return weight * 3 + 25; }
+}
+```
+
+### Introduce Parameter Object
+**When**: A function takes 4+ related parameters.
+```typescript
+// Before
+function searchProducts(query: string, minPrice: number, maxPrice: number,
+  category: string, sortBy: string, page: number, limit: number) { /* ... */ }
+
+// After
+interface ProductSearchCriteria {
+  query: string;
+  priceRange: { min: number; max: number };
+  category: string;
+  sort: { field: string; direction: 'asc' | 'desc' };
+  pagination: { page: number; limit: number };
+}
+
+function searchProducts(criteria: ProductSearchCriteria) { /* ... */ }
+```
+
+## Code Review from Developer Perspective
+
+### What to Look For (Priority Order)
+
+1. **Correctness**: Does it do what the ticket says? Are edge cases handled?
+2. **Security**: SQL injection, XSS, auth bypass, secrets in code?
+3. **Performance**: N+1 queries, unbounded loops, missing indexes, memory leaks?
+4. **Maintainability**: Can the next developer understand this in 6 months?
+5. **Test coverage**: Are the important paths tested? Are tests meaningful (not just line coverage)?
+6. **Style**: Consistent with codebase conventions? (Lowest priority — automate with linters)
+
+### How to Give Constructive Feedback
+- **Be specific**: "This query runs N+1 for each order item" not "This is slow"
+- **Suggest alternatives**: "Consider using `Promise.all()` here to parallelize" not just "Fix this"
+- **Distinguish must-fix from nice-to-have**: Use labels like `[blocking]` vs `[nit]` vs `[suggestion]`
+- **Ask questions instead of commanding**: "Would it be simpler to extract this into a helper?" vs "Extract this"
+- **Praise good code**: "Nice use of the builder pattern here" — positive feedback reinforces good practices

package/data/free-skills/devflow-agile/plugin/skills/developer/references/clean-code-guide.md

@@ -0,0 +1,207 @@
+# Clean Code Guide
+
+## SOLID Principles with Practical Examples
+
+### Single Responsibility Principle (SRP)
+A class or function should have **one reason to change**.
+
+**Bad:**
+```typescript
+class UserService {
+  createUser(data: CreateUserDto) { /* creates user in DB */ }
+  sendWelcomeEmail(user: User) { /* sends email */ }
+  generateReport(users: User[]) { /* creates CSV report */ }
+}
+```
+
+**Good:**
+```typescript
+class UserService {
+  createUser(data: CreateUserDto): User { /* creates user in DB */ }
+}
+class EmailService {
+  sendWelcomeEmail(user: User) { /* sends email */ }
+}
+class UserReportService {
+  generateReport(users: User[]): Buffer { /* creates CSV report */ }
+}
+```
+
+### Open/Closed Principle (OCP)
+Open for extension, closed for modification. Use abstractions to add behavior.
+
+**Bad** — Adding a new payment method requires modifying existing code:
+```typescript
+function processPayment(method: string, amount: number) {
+  if (method === 'stripe') { /* stripe logic */ }
+  else if (method === 'paypal') { /* paypal logic */ }
+  // Every new method = another else-if
+}
+```
+
+**Good** — New payment methods are added without touching existing code:
+```typescript
+interface PaymentProcessor {
+  process(amount: number): PaymentResult;
+}
+class StripeProcessor implements PaymentProcessor { /* ... */ }
+class PaypalProcessor implements PaymentProcessor { /* ... */ }
+// Adding BankTransferProcessor requires zero changes to existing code
+```
+
+### Dependency Inversion Principle (DIP)
+Depend on abstractions, not concretions. High-level modules should not depend on low-level modules.
+
+**Bad:**
+```typescript
+class OrderService {
+  private db = new PostgresDatabase(); // tightly coupled to Postgres
+  private mailer = new SendGridMailer(); // tightly coupled to SendGrid
+}
+```
+
+**Good:**
+```typescript
+class OrderService {
+  constructor(
+    private db: DatabasePort,        // depends on interface
+    private mailer: MailerPort,      // depends on interface
+  ) {}
+}
+```
+
+## DRY, KISS, YAGNI Application
+
+| Principle | Meaning | Practical Rule |
+|-----------|---------|---------------|
+| **DRY** | Don't Repeat Yourself | If you copy-paste code a **third time**, extract it. Twice is OK — premature abstraction is worse than duplication |
+| **KISS** | Keep It Simple | Choose the simplest solution that works. A 10-line if/else is often better than a design pattern nobody understands |
+| **YAGNI** | You Aren't Gonna Need It | Do not build features, abstractions, or infrastructure "just in case." Build what the current ticket requires |
+
+### DRY Anti-Pattern: Wrong Abstraction
+Sharing code between two callers that happen to look similar today but have different reasons to change leads to **coupling that hurts more than the duplication**. When in doubt, duplicate for now and extract later when the pattern is clear.
+
+## Function Design
+
+### Rules
+| Rule | Guideline |
+|------|-----------|
+| Length | Aim for under 20 lines. Hard limit at 50 lines — extract subfunctions beyond that |
+| Parameters | 3 or fewer. If more, group into an options object / DTO |
+| Single abstraction level | A function should not mix high-level orchestration with low-level implementation details |
+| Return early | Validate inputs at the top, return/throw early. Avoid deep nesting |
+| Side effects | Minimize. If a function has side effects, make them obvious from the name (`saveUser`, not `getUser` that also saves) |
+
+### Example: Return Early Pattern
+**Bad** — Deeply nested:
+```typescript
+function processOrder(order: Order) {
+  if (order) {
+    if (order.items.length > 0) {
+      if (order.payment) {
+        // actual logic buried 3 levels deep
+      }
+    }
+  }
+}
+```
+
+**Good** — Guard clauses:
+```typescript
+function processOrder(order: Order) {
+  if (!order) throw new InvalidOrderError('Order is required');
+  if (order.items.length === 0) throw new InvalidOrderError('Order has no items');
+  if (!order.payment) throw new InvalidOrderError('Payment info missing');
+
+  // actual logic at top level, easy to read
+}
+```
+
+## Error Handling Patterns
+
+### Rules
+1. **Never swallow exceptions** — `catch (e) {}` is a bug waiting to happen
+2. **Catch at the right level** — catch where you can actually handle or translate the error
+3. **Use custom error classes** for business errors (not generic Error/Exception)
+4. **Include context** — error messages should help debugging without looking at code
+
+### Error Handling Strategy
+| Layer | Approach |
+|-------|---------|
+| Controller/Route | Catch and translate to HTTP status + user-friendly message |
+| Service | Throw domain-specific errors (`InsufficientBalanceError`, `UserNotFoundError`) |
+| Repository/DB | Translate database errors to domain errors (constraint violation → `DuplicateEmailError`) |
+| External API | Wrap and translate third-party errors, add retry for transient failures |
+
+### Example
+```typescript
+// BAD
+try {
+  await paymentGateway.charge(amount);
+} catch (e) {
+  console.log('error'); // No context, swallowed
+}
+
+// GOOD
+try {
+  await paymentGateway.charge(amount);
+} catch (error) {
+  logger.error('Payment charge failed', {
+    orderId: order.id,
+    amount,
+    gateway: 'stripe',
+    error: error.message,
+  });
+  throw new PaymentFailedError(order.id, error);
+}
+```
+
+## Logging Best Practices
+
+| Rule | Guideline |
+|------|-----------|
+| **Log context, not noise** | Include: requestId, userId, orderId. Skip: "entering function X" |
+| **Structured logging** | Use JSON format with consistent fields, not free-text strings |
+| **Log levels matter** | ERROR: needs attention. WARN: unusual but handled. INFO: business events. DEBUG: development only |
+| **Never log secrets** | Passwords, tokens, full credit card numbers, PII must never appear in logs |
+| **Log at boundaries** | Log incoming requests, outgoing API calls, and state transitions — not every line |
+
+## Code Documentation Standards
+
+### When to Comment
+- **Why**, not what — the code shows what, comments explain why
+- **Business rules** — "Discount applies only to orders over $50 per client contract section 3.2"
+- **Workarounds** — "Using setTimeout because library X has a race condition (see issue #234)"
+- **Public APIs** — JSDoc/docstring for every public function with params and return value
+
+### When NOT to Comment
+- `// increment counter` → `counter++` — the code is self-explanatory
+- `// TODO: fix this later` without a ticket number — create a ticket or fix it now
+- Commented-out code — delete it, git remembers
+
+## Common Refactoring Techniques
+
+| Technique | When to Use | How |
+|-----------|-------------|-----|
+| Extract Function | Block of code with a comment explaining what it does | Move the block to a named function — the name replaces the comment |
+| Introduce Parameter Object | Function with 4+ parameters | Group related params into a DTO/interface |
+| Replace Conditional with Polymorphism | Long if/else or switch on type | Create subclasses or strategy pattern implementations |
+| Decompose Conditional | Complex boolean expression | Extract to a named function: `isEligibleForDiscount()` |
+| Replace Magic Number | `if (status === 3)` | Define a constant or enum: `if (status === OrderStatus.SHIPPED)` |
+| Move to Caller/Callee | Responsibility in the wrong place | Move logic to where the data lives |
+
+## Code Complexity Management
+
+### Cyclomatic Complexity Targets
+| Complexity | Assessment | Action |
+|-----------|-----------|--------|
+| 1–5 | Simple, easy to test | No action needed |
+| 6–10 | Moderate, still manageable | Monitor, refactor if adding more branches |
+| 11–20 | High, hard to test thoroughly | Refactor: extract functions, simplify conditions |
+| 21+ | Very high, error-prone | Must refactor before adding any new logic |
+
+### Reducing Complexity
+1. **Extract early returns** — handle errors/edge cases upfront, reduce nesting
+2. **Use lookup tables** instead of switch/case for data mapping
+3. **Split decision from action** — one function decides, another executes
+4. **Limit function scope** — if a function handles 3 concerns, split into 3 functions