skillstore-cli 1.0.0

package/data/shared/framework/skills/backend-development/assets/sample-output.md

@@ -0,0 +1,175 @@
+# Sample Output: Task Management API Design
+
+## Service Overview
+
+A REST API for managing tasks within projects. Supports CRUD operations, assignment, status transitions, and filtering.
+
+## Base URL
+
+```
+https://api.example.com/v1
+```
+
+## Authentication
+
+All endpoints require a Bearer JWT token in the `Authorization` header:
+```
+Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
+```
+
+## Endpoints
+
+### 1. List Tasks
+```
+GET /projects/{projectId}/tasks?status=open&assignee=user-123&sort=-priority,created_at&page=1&per_page=25
+```
+
+**Response: 200 OK**
+```json
+{
+  "data": [
+    {
+      "id": "task-456",
+      "title": "Implement user authentication",
+      "description": "Add JWT-based auth with refresh tokens",
+      "status": "in_progress",
+      "priority": "high",
+      "assignee": { "id": "user-123", "name": "Nguyen Van A" },
+      "due_date": "2026-04-01",
+      "created_at": "2026-03-15T08:00:00Z",
+      "updated_at": "2026-03-18T14:30:00Z"
+    }
+  ],
+  "meta": { "current_page": 1, "per_page": 25, "total_items": 42, "total_pages": 2 }
+}
+```
+
+### 2. Create Task
+```
+POST /projects/{projectId}/tasks
+Content-Type: application/json
+
+{
+  "title": "Implement user authentication",
+  "description": "Add JWT-based auth with refresh tokens",
+  "priority": "high",
+  "assignee_id": "user-123",
+  "due_date": "2026-04-01"
+}
+```
+
+**Response: 201 Created**
+```
+Location: /v1/projects/proj-789/tasks/task-456
+```
+Returns the created task object.
+
+**Validation Rules:**
+- `title`: required, 1–200 characters
+- `priority`: required, enum: `low`, `medium`, `high`, `critical`
+- `assignee_id`: optional, must be a valid project member
+- `due_date`: optional, must be today or future
+
+### 3. Get Task
+```
+GET /projects/{projectId}/tasks/{taskId}
+```
+
+**Response: 200 OK** — full task object with comments count and activity log.
+
+**Response: 404 Not Found**
+```json
+{
+  "type": "https://api.example.com/errors/not-found",
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Task 'task-999' not found in project 'proj-789'."
+}
+```
+
+### 4. Update Task
+```
+PATCH /projects/{projectId}/tasks/{taskId}
+Content-Type: application/json
+
+{
+  "status": "done",
+  "priority": "medium"
+}
+```
+
+**Response: 200 OK** — returns updated task.
+
+**Status Transition Rules:**
+```
+open → in_progress → in_review → done
+                   → blocked → in_progress
+done → open (reopen)
+```
+Invalid transitions return 422.
+
+### 5. Delete Task
+```
+DELETE /projects/{projectId}/tasks/{taskId}
+```
+
+**Response: 204 No Content**
+
+Only project admins can delete tasks. Returns 403 otherwise.
+
+## Error Handling
+
+### Validation Error (400)
+```json
+{
+  "type": "https://api.example.com/errors/validation-error",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "The request body contains invalid fields.",
+  "errors": [
+    { "field": "title", "message": "Title is required" },
+    { "field": "priority", "message": "Must be one of: low, medium, high, critical" }
+  ],
+  "trace_id": "req-abc-123"
+}
+```
+
+### Unauthorized (401)
+```json
+{
+  "type": "https://api.example.com/errors/unauthorized",
+  "title": "Unauthorized",
+  "status": 401,
+  "detail": "Access token is expired or invalid."
+}
+```
+
+### Business Rule Violation (422)
+```json
+{
+  "type": "https://api.example.com/errors/invalid-transition",
+  "title": "Invalid Status Transition",
+  "status": 422,
+  "detail": "Cannot transition from 'open' to 'done'. Task must go through 'in_progress' first."
+}
+```
+
+## Architecture
+
+```
+routes/tasks.ts          → Route definitions, auth middleware
+controllers/TaskCtrl.ts  → Input validation, HTTP response
+services/TaskService.ts  → Business logic, status transitions
+repos/TaskRepository.ts  → Database queries (Knex/Kysely)
+models/Task.ts           → TypeScript interfaces
+validators/task.ts       → Zod schemas for request validation
+```
+
+## Rate Limits
+
+| Endpoint | Limit |
+|----------|-------|
+| GET (list/read) | 100 req/min |
+| POST/PATCH/DELETE | 30 req/min |
+
+Returns `429` with `Retry-After` header when exceeded.

package/data/shared/framework/skills/backend-development/references/advanced-patterns.md

@@ -0,0 +1,180 @@
+# Advanced Backend Patterns
+
+## gRPC & Protocol Buffers
+
+### Protobuf Schema Design
+
+```protobuf
+syntax = "proto3";
+package orders.v1;
+
+message Order {
+  string order_id = 1;
+  string customer_id = 2;
+  repeated LineItem items = 3;
+  OrderStatus status = 4;
+}
+
+message LineItem {
+  string product_id = 1;
+  int32 quantity = 2;
+  int64 price_cents = 3;  // Integer cents, never float for money
+}
+
+enum OrderStatus {
+  ORDER_STATUS_UNSPECIFIED = 0;
+  ORDER_STATUS_PENDING = 1;
+  ORDER_STATUS_CONFIRMED = 2;
+}
+```
+
+**Schema rules:** Prefix enums with type name. Reserve removed field numbers (`reserved 6, 7;`). Use integers for money. Never reuse field numbers.
+
+### Service Definitions & Streaming
+
+```protobuf
+service OrderService {
+  rpc GetOrder(GetOrderRequest) returns (Order);                          // Unary
+  rpc WatchOrderStatus(WatchRequest) returns (stream OrderEvent);         // Server stream
+  rpc UploadLineItems(stream LineItem) returns (UploadSummary);           // Client stream
+  rpc LiveOrderChat(stream ChatMessage) returns (stream ChatMessage);     // Bidirectional
+}
+```
+
+- **Unary** — Standard CRUD, simple queries
+- **Server stream** — Real-time feeds, progress updates, large result sets
+- **Client stream** — File uploads, batch ingestion, telemetry
+- **Bidirectional** — Chat, collaborative editing, live dashboards
+
+---
+
+## Webhooks
+
+### Delivery with Retry & Idempotency
+
+```typescript
+interface WebhookDelivery {
+  id: string;           // Unique delivery ID
+  event_id: string;     // Idempotency key
+  event_type: string;
+  payload: unknown;
+  signature: string;    // HMAC-SHA256
+  timestamp: number;
+}
+
+async function deliverWebhook(delivery: WebhookDelivery, endpoint: string) {
+  for (let attempt = 0; attempt <= 5; attempt++) {
+    try {
+      const res = await fetch(endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-Webhook-Id': delivery.id,
+          'X-Webhook-Signature': delivery.signature,
+        },
+        body: JSON.stringify(delivery.payload),
+        signal: AbortSignal.timeout(10_000),
+      });
+      if (res.ok || (res.status >= 400 && res.status < 500)) return;
+    } catch { /* network error */ }
+    const delay = Math.pow(2, attempt) * 1000 + Math.random() * 500;
+    await new Promise(r => setTimeout(r, delay));
+  }
+  await moveToDeadLetterQueue(delivery);
+}
+```
+
+### Signature Verification
+
+```typescript
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+function verifySignature(payload: string, signature: string, secret: string): boolean {
+  const expected = createHmac('sha256', secret).update(payload).digest('hex');
+  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+}
+```
+
+Use `timingSafeEqual` to prevent timing attacks. Reject payloads older than 5 minutes. Deduplicate using `event_id`.
+
+---
+
+## Event Sourcing
+
+### Event Store Design
+
+```
+EventStore table:
+  stream_id    VARCHAR       -- aggregate ID (e.g. "order-123")
+  version      INTEGER       -- monotonically increasing per stream
+  event_type   VARCHAR       -- e.g. "OrderPlaced", "ItemAdded"
+  payload      JSONB         -- event data
+  metadata     JSONB         -- correlation_id, causation_id, user_id
+  created_at   TIMESTAMPTZ   -- append-only, never updated
+  UNIQUE(stream_id, version) -- optimistic concurrency control
+```
+
+- **Live projections** — Updated in real-time as events are appended
+- **Catch-up projections** — Rebuild from event stream position 0
+- **Snapshots** — Capture state every N events; on load, replay only events after snapshot
+- **Replay** — Rebuild read models, debug with exact state reproduction, create new projections
+
+---
+
+## CQRS
+
+**Command side:** Receives writes, validates business rules, emits domain events. Returns success/failure only.
+
+**Query side:** Maintains denormalized read models per use case. Updated async via event handlers.
+
+**Eventual consistency handling:**
+- Return `202 Accepted` with resource location for polling
+- Read-your-writes: briefly read from write model after a command
+- Include event version in responses so clients detect stale reads
+
+---
+
+## Message Queues
+
+### RabbitMQ vs Kafka
+
+| Criteria | RabbitMQ | Kafka |
+|---|---|---|
+| Pattern | Task queue, work distribution | Event log, stream processing |
+| Ordering | Per-queue FIFO | Per-partition ordering |
+| Retention | Removed after ack | Retained by time/size policy |
+| Throughput | ~50K msg/s | ~1M+ msg/s |
+| Replay | Not supported | From any offset |
+| Best for | Job queues, RPC, routing | Event sourcing, analytics, CDC |
+
+**Dead letter queues:** Messages failing N times move to DLQ. Monitor DLQ depth — growth signals a bug.
+
+**Consumer groups (Kafka):** Each group gets every message. Within a group, partitions distribute across consumers. Max parallelism = partition count.
+
+---
+
+## Saga Pattern (Distributed Transactions)
+
+### Orchestration
+
+A central coordinator directs steps and compensations:
+
+```
+OrderSaga:
+  1. ReserveInventory → success → 2 | fail → END
+  2. ProcessPayment  → success → 3 | fail → CompensateInventory → END
+  3. ShipOrder       → success → END | fail → RefundPayment → CompensateInventory → END
+```
+
+### Choreography
+
+Services react to events independently:
+
+```
+OrderService     → emits OrderPlaced
+InventoryService → listens OrderPlaced → emits InventoryReserved
+PaymentService   → listens InventoryReserved → emits PaymentProcessed
+ShippingService  → listens PaymentProcessed → emits OrderShipped
+```
+
+**Choose orchestration** for complex flows with many compensations. **Choose choreography** for simple flows (3-4 steps) with truly independent services.

package/data/shared/framework/skills/backend-development/references/api-design-guide.md

@@ -0,0 +1,160 @@
+# API Design Guide
+
+## RESTful Design Principles
+
+### Resource Naming
+- Use nouns, not verbs: `/users` not `/getUsers`
+- Use plural: `/tasks` not `/task`
+- Nest for relationships: `/users/{id}/tasks`
+- Keep URLs max 3 levels deep — beyond that, use query params or separate endpoints
+- Use kebab-case: `/order-items` not `/orderItems`
+
+### HTTP Methods
+
+| Method | Purpose | Idempotent | Response |
+|--------|---------|------------|----------|
+| GET | Read resource(s) | Yes | 200 with body |
+| POST | Create resource | No | 201 with Location header |
+| PUT | Full replace | Yes | 200 with body |
+| PATCH | Partial update | No* | 200 with body |
+| DELETE | Remove resource | Yes | 204 no body |
+
+### Status Codes — Use These
+
+| Code | When |
+|------|------|
+| 200 | Successful read/update |
+| 201 | Resource created |
+| 204 | Successful delete (no body) |
+| 400 | Validation error, malformed request |
+| 401 | Not authenticated |
+| 403 | Authenticated but not authorized |
+| 404 | Resource not found |
+| 409 | Conflict (duplicate, state violation) |
+| 422 | Semantically invalid (understood but can't process) |
+| 429 | Rate limit exceeded |
+| 500 | Unhandled server error |
+
+## API Versioning
+
+| Strategy | Example | Pros | Cons |
+|----------|---------|------|------|
+| URL path | `/v1/users` | Simple, explicit, cacheable | URL pollution |
+| Header | `Accept: application/vnd.api.v1+json` | Clean URLs | Harder to test |
+| Query param | `/users?version=1` | Simple | Easy to forget |
+
+**Recommendation**: URL path versioning (`/v1/`) for external APIs. It's the most discoverable and cache-friendly approach.
+
+## Request/Response Patterns
+
+### Pagination
+```json
+GET /tasks?page=2&per_page=25
+
+{
+  "data": [...],
+  "meta": {
+    "current_page": 2,
+    "per_page": 25,
+    "total_items": 243,
+    "total_pages": 10
+  },
+  "links": {
+    "first": "/tasks?page=1&per_page=25",
+    "prev": "/tasks?page=1&per_page=25",
+    "next": "/tasks?page=3&per_page=25",
+    "last": "/tasks?page=10&per_page=25"
+  }
+}
+```
+
+For large datasets, prefer cursor-based pagination:
+```
+GET /tasks?cursor=eyJpZCI6MTAwfQ&limit=25
+```
+
+### Filtering and Sorting
+```
+GET /tasks?status=open&priority=high&sort=-created_at,title
+```
+- Prefix `-` for descending sort
+- Support multiple sort fields separated by commas
+- Validate all filter fields — reject unknown params with 400
+
+### Field Selection
+```
+GET /users/123?fields=id,name,email
+```
+Useful for mobile clients. Only implement if there's a real performance benefit.
+
+## Error Response Format (RFC 7807)
+
+```json
+{
+  "type": "https://api.example.com/errors/validation-error",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "The request body contains invalid fields.",
+  "instance": "/tasks/123",
+  "errors": [
+    { "field": "title", "message": "Title is required" },
+    { "field": "due_date", "message": "Due date must be in the future" }
+  ],
+  "trace_id": "abc-123-def"
+}
+```
+
+Key rules:
+- Always include `status`, `title`, and `detail`
+- Add `trace_id` for server errors (links to logs)
+- Add `errors` array for validation errors with field-level detail
+- Never expose stack traces or SQL in production
+
+## Authentication Patterns
+
+### JWT (JSON Web Tokens)
+- Best for: stateless APIs, microservices, mobile apps
+- Store access token in memory, refresh token in httpOnly cookie
+- Short-lived access tokens (15 min), longer refresh tokens (7 days)
+- Include minimal claims: `sub`, `role`, `exp` — NOT sensitive data
+
+### OAuth2
+- Best for: third-party integrations, SSO
+- Use Authorization Code flow with PKCE for SPAs and mobile
+- Never use Implicit flow (deprecated)
+
+### API Keys
+- Best for: server-to-server, webhooks, developer APIs
+- Pass in header (`X-API-Key`), never in URL
+- Implement key rotation without downtime
+
+### Session-Based
+- Best for: traditional web apps, server-rendered pages
+- Store session in Redis/database, not in-memory
+- Set `httpOnly`, `secure`, `sameSite=strict` on cookies
+
+## Rate Limiting
+
+- Return `429 Too Many Requests` with `Retry-After` header
+- Use sliding window algorithm for fairness
+- Different limits per tier: anonymous < authenticated < premium
+- Include rate limit headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
+
+## GraphQL Considerations
+
+### When to Use GraphQL
+- Clients need flexible data fetching (mobile vs. web)
+- Multiple data sources behind a single gateway
+- Rapidly evolving frontend requirements
+
+### When to Stick with REST
+- Simple CRUD operations
+- File upload/download heavy
+- Caching is critical (REST caching is simpler)
+- Team has no GraphQL experience
+
+### Schema Design Tips
+- Use `ID` type for identifiers, not `String` or `Int`
+- Implement connections (cursor-based pagination) for lists
+- Add `query complexity` limits to prevent abuse
+- Use DataLoader to batch and deduplicate N+1 queries

package/data/shared/framework/skills/backend-development/references/architecture-patterns.md

@@ -0,0 +1,183 @@
+# Backend Architecture Patterns
+
+## Layered Architecture
+
+Standard three-layer structure. Each layer only calls the layer below it.
+
+```
+Controller (HTTP layer)
+  → Validates input, calls service, returns HTTP response
+  → Knows about: Request, Response, HTTP status codes
+  → Does NOT contain business logic
+
+Service (Business logic layer)
+  → Implements business rules, orchestrates operations
+  → Knows about: domain models, business rules
+  → Does NOT know about HTTP or database implementation
+
+Repository (Data access layer)
+  → Handles database queries and persistence
+  → Knows about: database, ORM, SQL
+  → Returns domain models, not database rows
+```
+
+### Practical Example (Node.js/Express)
+```typescript
+// controller — HTTP concerns only
+router.post('/tasks', auth, async (req, res) => {
+  const dto = validateCreateTask(req.body); // throws 400 on invalid
+  const task = await taskService.create(dto, req.user.id);
+  res.status(201).json(task);
+});
+
+// service — business logic
+class TaskService {
+  async create(dto: CreateTaskDTO, userId: string): Promise<Task> {
+    const project = await this.projectRepo.findById(dto.projectId);
+    if (!project) throw new NotFoundError('Project');
+    if (!project.isActive) throw new BusinessError('Cannot add tasks to archived projects');
+    return this.taskRepo.create({ ...dto, createdBy: userId });
+  }
+}
+
+// repository — data access
+class TaskRepository {
+  async create(data: TaskCreateData): Promise<Task> {
+    const row = await db('tasks').insert(data).returning('*');
+    return this.toModel(row[0]);
+  }
+}
+```
+
+## Clean Architecture Principles
+
+- **Dependencies point inward**: outer layers depend on inner layers, never reverse
+- **Domain entities** have zero dependencies on frameworks or databases
+- **Use cases/services** contain application-specific business rules
+- **Interfaces/ports** define contracts; implementations (adapters) are in outer layers
+- **Practical tip**: You don't need full Clean Architecture for a CRUD API. Use it when business logic is complex enough to justify the abstraction.
+
+## Middleware Patterns
+
+Order matters. Apply middleware in this sequence:
+
+```
+1. Request ID / Correlation ID  → Generate or extract trace ID
+2. Logging                      → Log request start
+3. CORS                         → Handle preflight requests
+4. Security headers             → HSTS, CSP, X-Frame-Options
+5. Rate limiting                → Reject if over limit
+6. Authentication               → Verify token/session
+7. Body parsing                 → Parse JSON/form data
+8. Validation                   → Validate request body/params
+9. Authorization                → Check permissions
+10. Route handler               → Business logic
+11. Error handler               → Catch and format errors
+12. Response logging            → Log response status and duration
+```
+
+### Error Handling Middleware
+```typescript
+app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
+  if (err instanceof AppError) {
+    logger.warn({ err, traceId: req.traceId });
+    return res.status(err.statusCode).json(err.toResponse());
+  }
+  logger.error({ err, traceId: req.traceId });
+  res.status(500).json({ title: 'Internal Server Error', trace_id: req.traceId });
+});
+```
+
+## Dependency Injection
+
+### Why
+- Swap implementations (real DB → test mock)
+- Control lifecycle (singleton vs. per-request)
+- Make dependencies explicit (no hidden coupling)
+
+### Simple Manual DI (good for most projects)
+```typescript
+// Compose at startup
+const db = createDbConnection(config.database);
+const userRepo = new UserRepository(db);
+const authService = new AuthService(userRepo, config.jwt);
+const userController = new UserController(authService);
+```
+
+### DI Container (for large projects)
+Use a lightweight container like `tsyringe`, `awilix`, or `inversify` when you have 20+ services.
+
+## Database Access Patterns
+
+### Repository Pattern
+- Abstract database operations behind an interface
+- Each aggregate root gets its own repository
+- Methods return domain objects, not raw rows
+
+### Query Builder vs. ORM
+| Approach | When | Examples |
+|----------|------|----------|
+| Raw SQL | Complex queries, performance-critical | pg, mysql2 |
+| Query builder | Most CRUD apps, good balance | Knex, Kysely |
+| Full ORM | Rapid development, simple schemas | Prisma, TypeORM, Sequelize |
+
+**Recommendation**: Query builder (Knex/Kysely) for most ITO projects. Full control with less boilerplate than raw SQL.
+
+## Background Jobs and Queues
+
+### When to Use
+- Email/SMS sending
+- Report generation
+- Data processing/ETL
+- Webhook delivery with retries
+
+### Implementation
+- Use a job queue library (BullMQ for Node.js, Celery for Python, Sidekiq for Ruby)
+- Store jobs in Redis or database
+- Implement idempotency (same job processed twice = same result)
+- Set up dead-letter queues for failed jobs
+- Monitor queue depth and processing time
+
+## Caching Strategies
+
+| Strategy | Use Case | TTL |
+|----------|----------|-----|
+| In-memory (LRU) | Config, feature flags | App restart |
+| Redis | Session, rate limits, API cache | 5 min – 24 hrs |
+| CDN | Static assets, public API responses | 1 hr – 1 year |
+| HTTP cache | Browser caching of API responses | Varies |
+
+### Cache Invalidation Approaches
+- **Time-based (TTL)**: simplest, good enough for most cases
+- **Event-based**: invalidate on write (publish cache-clear event)
+- **Cache-aside**: application manages cache reads/writes explicitly
+
+**Rule of thumb**: Cache at the highest level possible (CDN > reverse proxy > application > database).
+
+## Logging and Observability
+
+### Structured Logging
+```typescript
+// Always use structured logging — never string concatenation
+logger.info({ userId, action: 'task.created', taskId: task.id, duration: 45 });
+// NOT: logger.info(`User ${userId} created task ${taskId}`);
+```
+
+### Correlation IDs
+- Generate a unique ID per request (UUID v4)
+- Pass it through all service calls (header: `X-Request-ID`)
+- Include in every log entry and error response
+- Enables tracing a request across services
+
+### What to Log
+| Level | When |
+|-------|------|
+| ERROR | Unhandled exceptions, failed external calls |
+| WARN | Business rule violations, rate limits hit |
+| INFO | Request start/end, key business events |
+| DEBUG | Detailed flow (disable in production) |
+
+### Health Checks
+- `/health` — basic liveness (returns 200 if process is running)
+- `/health/ready` — readiness (checks DB, Redis, external services)
+- Used by load balancers and container orchestrators