@nockdev/awf 6.2.0 → 6.2.1

package/.agent/skills/core/api-design/data/modern-api-patterns.yaml

@@ -0,0 +1,160 @@
+# =============================================================================
+# modern-api-patterns.yaml — Modern API Patterns (GraphQL, tRPC, gRPC)
+# =============================================================================
+
+version: "1.0.0"
+
+graphql:
+  overview:
+    description: "Query language for APIs — client specifies data shape"
+    best_for: "Frontend-driven APIs, mobile apps, aggregation"
+
+  approaches:
+    schema_first: |
+      # schema.graphql
+      type Query {
+        user(id: ID!): User
+        users(limit: Int = 10): [User!]!
+      }
+
+      type User {
+        id: ID!
+        name: String!
+        email: String!
+        posts: [Post!]!
+      }
+
+      type Mutation {
+        createUser(input: CreateUserInput!): User!
+      }
+
+    code_first: |
+      // TypeGraphQL (TypeScript)
+      @ObjectType()
+      class User {
+        @Field(() => ID)
+        id: string;
+
+        @Field()
+        name: string;
+
+        @Field(() => [Post])
+        posts: Post[];
+      }
+
+      @Resolver(User)
+      class UserResolver {
+        @Query(() => User)
+        async user(@Arg("id") id: string): Promise<User> {
+          return this.userService.findById(id);
+        }
+      }
+
+  federation:
+    description: "Compose multiple GraphQL services into a unified graph"
+    architecture: |
+      Gateway (Apollo Router)
+        ├── Users Subgraph → type User @key(fields: "id") { id, name, email }
+        ├── Orders Subgraph → type Order { id, user: User, total }
+        └── Reviews Subgraph → type Review { id, user: User, rating }
+
+  performance:
+    dataloader: |
+      // Solve N+1 problem
+      const userLoader = new DataLoader(async (ids: string[]) => {
+        const users = await db.users.findMany({ where: { id: { in: ids } } });
+        return ids.map(id => users.find(u => u.id === id));
+      });
+    pagination: "Cursor-based (Relay spec) for infinite scroll"
+    caching: "Persisted queries, CDN caching with @cacheControl"
+
+trpc:
+  overview:
+    description: "End-to-end typesafe APIs — no code generation needed"
+    best_for: "Full-stack TypeScript apps (Next.js, T3 Stack)"
+
+  server: |
+    // server/trpc.ts
+    import { initTRPC } from '@trpc/server';
+    import { z } from 'zod';
+
+    const t = initTRPC.create();
+    const router = t.router;
+    const publicProcedure = t.procedure;
+
+    export const appRouter = router({
+      user: router({
+        getById: publicProcedure
+          .input(z.object({ id: z.string() }))
+          .query(async ({ input }) => {
+            return db.user.findUnique({ where: { id: input.id } });
+          }),
+
+        create: publicProcedure
+          .input(z.object({
+            name: z.string().min(1),
+            email: z.string().email(),
+          }))
+          .mutation(async ({ input }) => {
+            return db.user.create({ data: input });
+          }),
+      }),
+    });
+
+  client: |
+    // Client usage (fully typed!)
+    const user = await trpc.user.getById.query({ id: '123' });
+    // ^? { id: string, name: string, email: string }
+
+    await trpc.user.create.mutate({
+      name: 'John',
+      email: 'john@example.com',
+    });
+
+  middleware: |
+    const isAuth = t.middleware(async ({ ctx, next }) => {
+      if (!ctx.session) throw new TRPCError({ code: 'UNAUTHORIZED' });
+      return next({ ctx: { ...ctx, user: ctx.session.user } });
+    });
+    const protectedProcedure = publicProcedure.use(isAuth);
+
+grpc:
+  overview:
+    description: "HTTP/2 + Protocol Buffers — high performance"
+    best_for: "Internal microservices, streaming, polyglot"
+
+  streaming_types:
+    - unary: "Single request → single response"
+    - server_streaming: "Single request → stream of responses"
+    - client_streaming: "Stream of requests → single response"
+    - bidirectional: "Stream of requests ↔ stream of responses"
+
+  interceptors: |
+    // Go gRPC interceptor (middleware)
+    func LoggingInterceptor(
+        ctx context.Context,
+        req interface{},
+        info *grpc.UnaryServerInfo,
+        handler grpc.UnaryHandler,
+    ) (interface{}, error) {
+        start := time.Now()
+        resp, err := handler(ctx, req)
+        log.Info("grpc call",
+            "method", info.FullMethod,
+            "duration", time.Since(start),
+            "error", err,
+        )
+        return resp, err
+    }
+
+decision_guide:
+  - scenario: "Full-stack TypeScript, same repo"
+    choice: "tRPC"
+  - scenario: "Multiple frontend clients, flexible queries"
+    choice: "GraphQL"
+  - scenario: "High-performance internal services"
+    choice: "gRPC"
+  - scenario: "Public API, broad compatibility"
+    choice: "REST"
+
+# _DOMYH Awesome Code • Modern API Patterns_

package/.agent/skills/core/api-design/data/pagination.yaml

@@ -1,121 +1,121 @@
 metadata:
   skill: api-design
   domain: pagination
-  version: 6.2.0
-  updated: '2026-02-05'
-  migrated_from: pagination.csv
+  version: 6.2.1
+  updated: "2026-02-05"
+  migrated_from: pagination.yaml
   patterns_count: 15
   columns:
-  - id
-  - pattern
-  - description
-  - example
-  - pros
-  - cons
-  - use_case
+    - id
+    - pattern
+    - description
+    - example
+    - pros
+    - cons
+    - use_case
 patterns:
-- id: PAG-01
-  pattern: Offset Pagination
-  description: Skip N records take M
-  example: ?offset=20&limit=10
-  pros: Simple random access
-  cons: Slow at large offsets
-  use_case: Small static data
-- id: PAG-02
-  pattern: Page Number
-  description: Page and size params
-  example: ?page=3&pageSize=10
-  pros: Intuitive for users
-  cons: Same issues as offset
-  use_case: Admin interfaces
-- id: PAG-03
-  pattern: Cursor Pagination
-  description: Opaque cursor for position
-  example: ?cursor=eyJpZCI6MTIz
-  pros: Efficient consistent
-  cons: No random access
-  use_case: Large dynamic data
-- id: PAG-04
-  pattern: Keyset Pagination
-  description: Last seen key values
-  example: ?after_id=123&limit=10
-  pros: Very efficient stable
-  cons: Sequential only
-  use_case: Ordered lists logs
-- id: PAG-05
-  pattern: Relay Connection
-  description: GraphQL connection spec
-  example: first after edges pageInfo
-  pros: Standard spec
-  cons: Complex implementation
-  use_case: GraphQL APIs
-- id: PAG-06
-  pattern: Total Count
-  description: Include total in response
-  example: '{total: 100 page: 1}'
-  pros: User knows position
-  cons: Expensive query
-  use_case: Small datasets
-- id: PAG-07
-  pattern: Has Next Page
-  description: Boolean for more data
-  example: '{hasNext: true data: []}'
-  pros: Avoids count query
-  cons: No total info
-  use_case: Large datasets
-- id: PAG-08
-  pattern: Link Headers
-  description: RFC 5988 pagination links
-  example: 'Link: <url>; rel="next"'
-  pros: Standard HTTP
-  cons: Header parsing
-  use_case: REST APIs
-- id: PAG-09
-  pattern: Envelope Links
-  description: Links in response body
-  example: '{_links: {next prev}}'
-  pros: Self-documenting
-  cons: Larger response
-  use_case: HATEOAS APIs
-- id: PAG-10
-  pattern: Default Page Size
-  description: Sensible default limit
-  example: 'Default: 20 Max: 100'
-  pros: Predictable behavior
-  cons: May not fit all
-  use_case: All APIs
-- id: PAG-11
-  pattern: Max Page Size
-  description: Cap maximum page size
-  example: Max 100 even if 1000 requested
-  pros: Prevents abuse
-  cons: Client limits
-  use_case: Public APIs
-- id: PAG-12
-  pattern: Consistent Ordering
-  description: Stable sort for pagination
-  example: ORDER BY created_at id
-  pros: Prevents duplicates
-  cons: Requires unique key
-  use_case: All pagination
-- id: PAG-13
-  pattern: Cursor Encoding
-  description: Encode cursor as base64
-  example: base64(JSON.stringify(pos))
-  pros: Opaque to client
-  cons: Decode overhead
-  use_case: Cursor pagination
-- id: PAG-14
-  pattern: Time-Based Cursor
-  description: Timestamp in cursor
-  example: ?since=2024-01-01T00:00:00Z
-  pros: Good for feeds
-  cons: Clock sync issues
-  use_case: Activity feeds
-- id: PAG-15
-  pattern: Seek Method
-  description: SQL SEEK instead of OFFSET
-  example: WHERE id > last_id
-  pros: Database efficient
-  cons: Requires indexed key
-  use_case: Large tables
+  - id: PAG-01
+    pattern: Offset Pagination
+    description: Skip N records take M
+    example: ?offset=20&limit=10
+    pros: Simple random access
+    cons: Slow at large offsets
+    use_case: Small static data
+  - id: PAG-02
+    pattern: Page Number
+    description: Page and size params
+    example: ?page=3&pageSize=10
+    pros: Intuitive for users
+    cons: Same issues as offset
+    use_case: Admin interfaces
+  - id: PAG-03
+    pattern: Cursor Pagination
+    description: Opaque cursor for position
+    example: ?cursor=eyJpZCI6MTIz
+    pros: Efficient consistent
+    cons: No random access
+    use_case: Large dynamic data
+  - id: PAG-04
+    pattern: Keyset Pagination
+    description: Last seen key values
+    example: ?after_id=123&limit=10
+    pros: Very efficient stable
+    cons: Sequential only
+    use_case: Ordered lists logs
+  - id: PAG-05
+    pattern: Relay Connection
+    description: GraphQL connection spec
+    example: first after edges pageInfo
+    pros: Standard spec
+    cons: Complex implementation
+    use_case: GraphQL APIs
+  - id: PAG-06
+    pattern: Total Count
+    description: Include total in response
+    example: "{total: 100 page: 1}"
+    pros: User knows position
+    cons: Expensive query
+    use_case: Small datasets
+  - id: PAG-07
+    pattern: Has Next Page
+    description: Boolean for more data
+    example: "{hasNext: true data: []}"
+    pros: Avoids count query
+    cons: No total info
+    use_case: Large datasets
+  - id: PAG-08
+    pattern: Link Headers
+    description: RFC 5988 pagination links
+    example: 'Link: <url>; rel="next"'
+    pros: Standard HTTP
+    cons: Header parsing
+    use_case: REST APIs
+  - id: PAG-09
+    pattern: Envelope Links
+    description: Links in response body
+    example: "{_links: {next prev}}"
+    pros: Self-documenting
+    cons: Larger response
+    use_case: HATEOAS APIs
+  - id: PAG-10
+    pattern: Default Page Size
+    description: Sensible default limit
+    example: "Default: 20 Max: 100"
+    pros: Predictable behavior
+    cons: May not fit all
+    use_case: All APIs
+  - id: PAG-11
+    pattern: Max Page Size
+    description: Cap maximum page size
+    example: Max 100 even if 1000 requested
+    pros: Prevents abuse
+    cons: Client limits
+    use_case: Public APIs
+  - id: PAG-12
+    pattern: Consistent Ordering
+    description: Stable sort for pagination
+    example: ORDER BY created_at id
+    pros: Prevents duplicates
+    cons: Requires unique key
+    use_case: All pagination
+  - id: PAG-13
+    pattern: Cursor Encoding
+    description: Encode cursor as base64
+    example: base64(JSON.stringify(pos))
+    pros: Opaque to client
+    cons: Decode overhead
+    use_case: Cursor pagination
+  - id: PAG-14
+    pattern: Time-Based Cursor
+    description: Timestamp in cursor
+    example: ?since=2024-01-01T00:00:00Z
+    pros: Good for feeds
+    cons: Clock sync issues
+    use_case: Activity feeds
+  - id: PAG-15
+    pattern: Seek Method
+    description: SQL SEEK instead of OFFSET
+    example: WHERE id > last_id
+    pros: Database efficient
+    cons: Requires indexed key
+    use_case: Large tables

package/.agent/skills/core/api-design/data/rate-limiting.yaml

@@ -1,135 +1,135 @@
 metadata:
   skill: api-design
   domain: rate_limiting
-  version: 6.2.0
-  updated: '2026-02-05'
-  migrated_from: rate-limiting.csv
+  version: 6.2.1
+  updated: "2026-02-05"
+  migrated_from: rate-limiting.yaml
   patterns_count: 20
   columns:
-  - id
-  - pattern
-  - description
-  - example
-  - algorithm
-  - use_case
+    - id
+    - pattern
+    - description
+    - example
+    - algorithm
+    - use_case
 patterns:
-- id: RL-01
-  pattern: Token Bucket
-  description: Tokens added at fixed rate
-  example: 10 tokens/sec 100 burst
-  algorithm: Bucket fills refills on use
-  use_case: Handles bursts
-- id: RL-02
-  pattern: Leaky Bucket
-  description: Fixed rate output queue
-  example: Process 10 req/sec always
-  algorithm: Queue drains at constant rate
-  use_case: Smooth traffic
-- id: RL-03
-  pattern: Fixed Window
-  description: Count per time window
-  example: 100 req per minute window
-  algorithm: Reset count each window
-  use_case: Simple implementation
-- id: RL-04
-  pattern: Sliding Window Log
-  description: Track each request timestamp
-  example: Log all requests compute rate
-  algorithm: Precise but memory heavy
-  use_case: Accuracy needed
-- id: RL-05
-  pattern: Sliding Window Counter
-  description: Weighted window estimate
-  example: Weight previous + current
-  algorithm: Balance accuracy memory
-  use_case: Most APIs
-- id: RL-06
-  pattern: 429 Status
-  description: Return Too Many Requests
-  example: HTTP 429 Too Many Requests
-  algorithm: Standard HTTP
-  use_case: All rate limits
-- id: RL-07
-  pattern: Retry-After Header
-  description: Indicate wait time
-  example: 'Retry-After: 60'
-  algorithm: Seconds or HTTP-date
-  use_case: After 429
-- id: RL-08
-  pattern: X-RateLimit-Limit
-  description: Show limit value
-  example: 'X-RateLimit-Limit: 100'
-  algorithm: Custom header
-  use_case: Rate info
-- id: RL-09
-  pattern: X-RateLimit-Remaining
-  description: Show remaining requests
-  example: 'X-RateLimit-Remaining: 45'
-  algorithm: Custom header
-  use_case: Rate info
-- id: RL-10
-  pattern: X-RateLimit-Reset
-  description: Show reset timestamp
-  example: 'X-RateLimit-Reset: 1640000000'
-  algorithm: Unix timestamp
-  use_case: Rate info
-- id: RL-11
-  pattern: Per-User Limits
-  description: Rate limit by user ID
-  example: 100 req/min per user
-  algorithm: User identification
-  use_case: Authenticated APIs
-- id: RL-12
-  pattern: Per-IP Limits
-  description: Rate limit by IP address
-  example: 50 req/min per IP
-  algorithm: IP extraction
-  use_case: Public APIs
-- id: RL-13
-  pattern: Per-Endpoint Limits
-  description: Different limits per route
-  example: '/search: 10/min /users: 100/min'
-  algorithm: Endpoint config
-  use_case: Expensive endpoints
-- id: RL-14
-  pattern: Tiered Limits
-  description: Limits by subscription
-  example: 'Free: 100 Pro: 10000'
-  algorithm: Tier lookup
-  use_case: SaaS APIs
-- id: RL-15
-  pattern: Exponential Backoff
-  description: Client retry strategy
-  example: Wait 1s 2s 4s 8s...
-  algorithm: Client-side
-  use_case: When 429 received
-- id: RL-16
-  pattern: Jitter
-  description: Add randomness to retry
-  example: backoff + random(0 100ms)
-  algorithm: Prevents thundering herd
-  use_case: Distributed clients
-- id: RL-17
-  pattern: Circuit Breaker
-  description: Stop requests when failing
-  example: Open after 5 failures
-  algorithm: Client-side protection
-  use_case: Unreliable backends
-- id: RL-18
-  pattern: Quota Management
-  description: Track usage over period
-  example: 1000 calls/day quota
-  algorithm: Daily/monthly tracking
-  use_case: Metered APIs
-- id: RL-19
-  pattern: Rate Limit Bypass
-  description: Whitelist trusted clients
-  example: Skip limits for internal
-  algorithm: Secret header/IP
-  use_case: Internal services
-- id: RL-20
-  pattern: Distributed Rate Limit
-  description: Shared state across nodes
-  example: Redis counter cluster
-  algorithm: Centralized counter
-  use_case: Scaled APIs
+  - id: RL-01
+    pattern: Token Bucket
+    description: Tokens added at fixed rate
+    example: 10 tokens/sec 100 burst
+    algorithm: Bucket fills refills on use
+    use_case: Handles bursts
+  - id: RL-02
+    pattern: Leaky Bucket
+    description: Fixed rate output queue
+    example: Process 10 req/sec always
+    algorithm: Queue drains at constant rate
+    use_case: Smooth traffic
+  - id: RL-03
+    pattern: Fixed Window
+    description: Count per time window
+    example: 100 req per minute window
+    algorithm: Reset count each window
+    use_case: Simple implementation
+  - id: RL-04
+    pattern: Sliding Window Log
+    description: Track each request timestamp
+    example: Log all requests compute rate
+    algorithm: Precise but memory heavy
+    use_case: Accuracy needed
+  - id: RL-05
+    pattern: Sliding Window Counter
+    description: Weighted window estimate
+    example: Weight previous + current
+    algorithm: Balance accuracy memory
+    use_case: Most APIs
+  - id: RL-06
+    pattern: 429 Status
+    description: Return Too Many Requests
+    example: HTTP 429 Too Many Requests
+    algorithm: Standard HTTP
+    use_case: All rate limits
+  - id: RL-07
+    pattern: Retry-After Header
+    description: Indicate wait time
+    example: "Retry-After: 60"
+    algorithm: Seconds or HTTP-date
+    use_case: After 429
+  - id: RL-08
+    pattern: X-RateLimit-Limit
+    description: Show limit value
+    example: "X-RateLimit-Limit: 100"
+    algorithm: Custom header
+    use_case: Rate info
+  - id: RL-09
+    pattern: X-RateLimit-Remaining
+    description: Show remaining requests
+    example: "X-RateLimit-Remaining: 45"
+    algorithm: Custom header
+    use_case: Rate info
+  - id: RL-10
+    pattern: X-RateLimit-Reset
+    description: Show reset timestamp
+    example: "X-RateLimit-Reset: 1640000000"
+    algorithm: Unix timestamp
+    use_case: Rate info
+  - id: RL-11
+    pattern: Per-User Limits
+    description: Rate limit by user ID
+    example: 100 req/min per user
+    algorithm: User identification
+    use_case: Authenticated APIs
+  - id: RL-12
+    pattern: Per-IP Limits
+    description: Rate limit by IP address
+    example: 50 req/min per IP
+    algorithm: IP extraction
+    use_case: Public APIs
+  - id: RL-13
+    pattern: Per-Endpoint Limits
+    description: Different limits per route
+    example: "/search: 10/min /users: 100/min"
+    algorithm: Endpoint config
+    use_case: Expensive endpoints
+  - id: RL-14
+    pattern: Tiered Limits
+    description: Limits by subscription
+    example: "Free: 100 Pro: 10000"
+    algorithm: Tier lookup
+    use_case: SaaS APIs
+  - id: RL-15
+    pattern: Exponential Backoff
+    description: Client retry strategy
+    example: Wait 1s 2s 4s 8s...
+    algorithm: Client-side
+    use_case: When 429 received
+  - id: RL-16
+    pattern: Jitter
+    description: Add randomness to retry
+    example: backoff + random(0 100ms)
+    algorithm: Prevents thundering herd
+    use_case: Distributed clients
+  - id: RL-17
+    pattern: Circuit Breaker
+    description: Stop requests when failing
+    example: Open after 5 failures
+    algorithm: Client-side protection
+    use_case: Unreliable backends
+  - id: RL-18
+    pattern: Quota Management
+    description: Track usage over period
+    example: 1000 calls/day quota
+    algorithm: Daily/monthly tracking
+    use_case: Metered APIs
+  - id: RL-19
+    pattern: Rate Limit Bypass
+    description: Whitelist trusted clients
+    example: Skip limits for internal
+    algorithm: Secret header/IP
+    use_case: Internal services
+  - id: RL-20
+    pattern: Distributed Rate Limit
+    description: Shared state across nodes
+    example: Redis counter cluster
+    algorithm: Centralized counter
+    use_case: Scaled APIs