@nockdev/awf 6.2.0 → 6.2.2

package/.agent/skills/tooling/api-protocols/META.yaml

@@ -0,0 +1,102 @@
+name: api-protocols
+version: "1.0.0"
+display: Modern API Protocols
+category: tooling
+tier: 1
+priority: 4
+
+desc: "Modern API protocols: GraphQL (federation, schema design, security), tRPC (end-to-end TypeScript), gRPC (high-performance polyglot). Complements core/api-design."
+
+  ### Data Files (3 domains, ~24 patterns)
+  - graphql-patterns.yaml: schema design, federation, security, performance (10)
+  - trpc-patterns.yaml: router, monorepo, Next.js integration (7)
+  - grpc-patterns.yaml: proto design, streaming, channel management (7)
+
+triggers:
+  file_patterns:
+    # GraphQL
+    - "*.graphql"
+    - "*.gql"
+    - "schema.graphql"
+    - "codegen.ts"
+    - "codegen.yml"
+    - "apollo.config.js"
+    - "apollo.config.ts"
+    # gRPC
+    - "*.proto"
+    - "buf.yaml"
+    - "buf.gen.yaml"
+    # tRPC
+    - "**/trpc/**"
+    - "**/trpc.ts"
+  keywords:
+    # GraphQL
+    - graphql
+    - GraphQL
+    - apollo server
+    - apollo client
+    - federation
+    - subgraph
+    - supergraph
+    - schema design
+    - resolver
+    - mutation
+    - subscription
+    - relay
+    - urql
+    - yoga
+    - DataLoader
+    - graphql codegen
+    - persisted queries
+    # tRPC
+    - tRPC
+    - trpc
+    - trpc router
+    - end-to-end type safety
+    - trpc procedure
+    - trpc middleware
+    # gRPC
+    - gRPC
+    - grpc
+    - protocol buffers
+    - protobuf
+    - proto file
+    - grpc streaming
+    - grpc-web
+    - grpc channel
+    - protoc
+
+caps:
+  # GraphQL
+  - Schema design patterns (client-centric, demand-driven)
+  - Federation (subgraphs, gateway, @key/@external/@requires directives)
+  - Security: depth limiting, persisted queries, cost analysis, auth directives
+  - Performance: DataLoader for N+1 prevention, cursor-based pagination
+  - Code generation (GraphQL Codegen, typed resolvers)
+  - Subscriptions (WebSocket transport)
+  # tRPC
+  - End-to-end TypeScript type safety (no codegen needed)
+  - Router/procedure/middleware architecture
+  - Monorepo integration patterns
+  - Next.js App Router integration
+  - React Query integration (automatic cache)
+  # gRPC
+  - Protocol Buffers (schema-first design)
+  - HTTP/2 multiplexed transport
+  - Streaming: client/server/bidirectional
+  - Channel reuse & connection pooling
+  - gRPC-Web for browser clients
+  - Load balancing strategies
+  # Cross-protocol
+  - Hybrid REST + GraphQL + gRPC architecture
+  - API Gateway protocol translation
+
+related_skills:
+  - api-design
+  - typescript
+  - microservices
+
+hsa_adapter:
+  enabled: true
+  data_dir: "skills/tooling/api-protocols/data"
+  preload_data: true

package/.agent/skills/tooling/api-protocols/SKILL.md

@@ -0,0 +1,145 @@
+# Modern API Protocols — GraphQL • tRPC • gRPC
+
+> GraphQL federation & schema design • tRPC end-to-end TypeScript • gRPC high-performance polyglot  
+> Complements `core/api-design` (REST patterns)
+
+---
+
+## Khi Nào Dùng
+
+- Thiết kế GraphQL API (schema, federation, subscriptions)
+- Dùng tRPC cho full-stack TypeScript monorepo
+- Dùng gRPC cho service-to-service high-performance
+- Chọn strategy: REST vs GraphQL vs tRPC vs gRPC
+
+## Protocol Selection Guide
+
+| Protocol    | Best For                 | Speed      | Type Safety     | Learning Curve |
+| ----------- | ------------------------ | ---------- | --------------- | -------------- |
+| **REST**    | Public APIs, CRUD        | ⭐⭐⭐     | Manual          | ⭐ Easy        |
+| **GraphQL** | Flexible queries, mobile | ⭐⭐⭐     | Schema-based    | ⭐⭐ Medium    |
+| **tRPC**    | TS monorepo, internal    | ⭐⭐⭐     | End-to-end auto | ⭐ Easy        |
+| **gRPC**    | Microservices, streaming | ⭐⭐⭐⭐⭐ | Proto-based     | ⭐⭐⭐ Hard    |
+
+## GraphQL Patterns
+
+### Schema Design (Client-Centric)
+
+```graphql
+# ✅ GOOD: Client-driven, meaningful types
+type User {
+  id: ID!
+  profile: UserProfile!
+  posts(first: Int!, after: String): PostConnection!
+}
+
+# Relay-style cursor pagination
+type PostConnection {
+  edges: [PostEdge!]!
+  pageInfo: PageInfo!
+}
+```
+
+### Federation (Apollo)
+
+```graphql
+# Subgraph: Users
+type User @key(fields: "id") {
+  id: ID!
+  name: String!
+}
+
+# Subgraph: Orders (extends User)
+extend type User @key(fields: "id") {
+  id: ID! @external
+  orders: [Order!]!
+}
+```
+
+### Security Checklist
+
+- ✅ Query depth limiting (max 10-15)
+- ✅ Persisted queries (whitelist, no arbitrary queries)
+- ✅ Cost analysis (complexity scoring)
+- ✅ Rate limiting per operation type
+- ✅ Field-level authorization
+
+### N+1 Prevention
+
+```typescript
+// ✅ Use DataLoader for batching
+const userLoader = new DataLoader(async (ids) => {
+  const users = await db.users.findMany({ where: { id: { in: ids } } });
+  return ids.map((id) => users.find((u) => u.id === id));
+});
+```
+
+## tRPC Patterns
+
+### Router Setup
+
+```typescript
+// server: define once
+const appRouter = router({
+  user: router({
+    getById: publicProcedure
+      .input(z.object({ id: z.string() }))
+      .query(({ input }) => db.user.findUnique({ where: { id: input.id } })),
+    create: protectedProcedure
+      .input(createUserSchema)
+      .mutation(({ input }) => db.user.create({ data: input })),
+  }),
+});
+
+// client: full type inference, zero codegen
+const user = await trpc.user.getById.query({ id: "123" }); // fully typed!
+```
+
+### Best Practices
+
+1. **Monorepo** — Share types between client/server (same TS codebase)
+2. **Middleware** — Auth, logging, rate limiting via procedure middleware
+3. **Split routers** — One router per domain (user, post, payment)
+4. **React Query** — Automatic cache invalidation via `trpc.useUtils()`
+
+## gRPC Patterns
+
+### Proto Design
+
+```protobuf
+syntax = "proto3";
+package user.v1;
+
+service UserService {
+  rpc GetUser(GetUserRequest) returns (User);
+  rpc ListUsers(ListUsersRequest) returns (stream User); // server streaming
+  rpc Chat(stream ChatMessage) returns (stream ChatMessage); // bidi
+}
+
+message User {
+  string id = 1;
+  string name = 2;
+  google.protobuf.Timestamp created_at = 3;
+}
+```
+
+### Performance Rules
+
+1. **Reuse channels** — Don't create new channel per request
+2. **Keep protos small** — Efficient serialization = faster
+3. **TLS always** — Encrypt all gRPC traffic
+4. **Load balancing** — Client-side or proxy-based (Envoy)
+
+## Common Traps
+
+| Trap            | Protocol | Fix                                                     |
+| --------------- | -------- | ------------------------------------------------------- |
+| N+1 queries     | GraphQL  | DataLoader batching                                     |
+| Over-fetching   | GraphQL  | Persisted queries, field selection                      |
+| Bundle size     | tRPC     | Split routers per API route                             |
+| Browser compat  | gRPC     | Use gRPC-Web with Envoy proxy                           |
+| Schema breaking | All      | Versioning (GraphQL deprecation, proto reserved fields) |
+
+---
+
+_DOMYH Awesome Code • API Protocols Skill v1.0.0_

package/.agent/skills/tooling/api-protocols/data/graphql-patterns.yaml

@@ -0,0 +1,115 @@
+# GraphQL Patterns - HSA API Protocols Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: api-protocols
+  domain: graphql
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 10
+
+patterns:
+  - id: gql001
+    name: schema_design
+    category: design
+    description: Client-centric schema design with meaningful types
+    text: schema design client centric demand driven type naming
+    example: |
+      type Query {
+        user(id: ID!): User
+        users(filter: UserFilter, pagination: PaginationInput): UserConnection!
+      }
+
+  - id: gql002
+    name: relay_pagination
+    category: design
+    description: Cursor-based pagination following Relay specification
+    text: relay pagination cursor connection edge pageInfo
+    example: |
+      type UserConnection {
+        edges: [UserEdge!]!
+        pageInfo: PageInfo!
+        totalCount: Int!
+      }
+      type UserEdge { cursor: String!; node: User! }
+      type PageInfo { hasNextPage: Boolean!; endCursor: String }
+
+  - id: gql003
+    name: federation_subgraph
+    category: architecture
+    description: Apollo Federation subgraph with @key directive
+    text: federation subgraph key directive entity reference
+    example: |
+      # Users subgraph
+      type User @key(fields: "id") { id: ID!; name: String! }
+      # Orders subgraph  
+      extend type User @key(fields: "id") {
+        id: ID! @external
+        orders: [Order!]!
+      }
+
+  - id: gql004
+    name: dataloader
+    category: performance
+    description: DataLoader for N+1 query prevention
+    text: dataloader batch n+1 prevention batch loading
+    example: |
+      const userLoader = new DataLoader(ids =>
+        db.users.findMany({ where: { id: { in: ids } } })
+          .then(users => ids.map(id => users.find(u => u.id === id)))
+      );
+
+  - id: gql005
+    name: depth_limiting
+    category: security
+    description: Query depth limiting to prevent abuse
+    text: depth limiting query complexity max depth protection
+    example: "depthLimit(10) // Max 10 levels of nesting"
+    severity: HIGH
+
+  - id: gql006
+    name: persisted_queries
+    category: security
+    description: Persisted queries whitelist for production
+    text: persisted queries whitelist automatic APQ hash
+    example: |
+      // Client sends hash instead of full query
+      { "extensions": { "persistedQuery": { "sha256Hash": "abc123" } } }
+
+  - id: gql007
+    name: codegen
+    category: tooling
+    description: Type-safe code generation with GraphQL Codegen
+    text: codegen code generation typed resolvers operations
+    example: "npx graphql-codegen --config codegen.ts"
+
+  - id: gql008
+    name: subscriptions
+    category: realtime
+    description: GraphQL subscriptions for real-time data
+    text: subscription websocket real-time pub/sub push
+    example: |
+      type Subscription {
+        messageAdded(channelId: ID!): Message!
+      }
+
+  - id: gql009
+    name: error_handling
+    category: design
+    description: Structured error handling with extensions
+    text: error handling extensions error code user facing
+    example: |
+      throw new GraphQLError("Not authorized", {
+        extensions: { code: "FORBIDDEN", http: { status: 403 } }
+      });
+
+  - id: gql010
+    name: cost_analysis
+    category: security
+    description: Query cost analysis to prevent expensive queries
+    text: cost analysis complexity scoring resource protection
+    example: |
+      // Assign cost per field
+      type Query {
+        users(first: Int!): [User!]! @cost(weight: 10, multiplier: "first")
+      }

package/.agent/skills/tooling/api-protocols/data/grpc-patterns.yaml

@@ -0,0 +1,101 @@
+# gRPC Patterns - HSA API Protocols Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: api-protocols
+  domain: grpc
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 7
+
+patterns:
+  - id: grpc001
+    name: proto_design
+    category: design
+    description: Protocol Buffer message and service design
+    text: proto design message service rpc protobuf schema
+    example: |
+      syntax = "proto3";
+      package user.v1;
+      service UserService {
+        rpc GetUser(GetUserRequest) returns (User);
+        rpc ListUsers(ListUsersRequest) returns (stream User);
+      }
+      message User {
+        string id = 1;
+        string name = 2;
+        google.protobuf.Timestamp created_at = 3;
+      }
+
+  - id: grpc002
+    name: streaming_patterns
+    category: architecture
+    description: gRPC streaming types (server, client, bidirectional)
+    text: streaming server client bidirectional stream rpc
+    types:
+      unary: "rpc GetUser(Request) returns (Response)"
+      server_stream: "rpc ListUsers(Request) returns (stream Response)"
+      client_stream: "rpc UploadFiles(stream Request) returns (Response)"
+      bidi_stream: "rpc Chat(stream Message) returns (stream Message)"
+
+  - id: grpc003
+    name: channel_reuse
+    category: performance
+    description: Reuse gRPC channels to avoid connection overhead
+    text: channel reuse connection pooling performance optimization
+    example: |
+      // ✅ GOOD: Create channel once, reuse
+      const channel = new grpc.Channel("localhost:50051", grpc.credentials.createInsecure());
+      const client = new UserServiceClient(channel);
+      // ❌ BAD: New channel per request
+    severity: HIGH
+
+  - id: grpc004
+    name: tls_security
+    category: security
+    description: TLS encryption for gRPC connections
+    text: tls ssl security encryption certificate mutual tls mTLS
+    example: |
+      const creds = grpc.credentials.createSsl(
+        fs.readFileSync("ca.pem"),
+        fs.readFileSync("client-key.pem"),
+        fs.readFileSync("client-cert.pem")
+      );
+    severity: CRITICAL
+
+  - id: grpc005
+    name: load_balancing
+    category: architecture
+    description: gRPC load balancing strategies
+    text: load balancing client side proxy envoy round robin
+    strategies:
+      client_side: "Built-in pick_first, round_robin"
+      proxy: "Envoy, NGINX, HAproxy for L7 gRPC"
+      service_mesh: "Istio, Linkerd for automatic load balancing"
+
+  - id: grpc006
+    name: error_handling
+    category: design
+    description: gRPC status codes and error details
+    text: error handling status code details metadata
+    status_codes:
+      OK: 0
+      CANCELLED: 1
+      INVALID_ARGUMENT: 3
+      NOT_FOUND: 5
+      PERMISSION_DENIED: 7
+      INTERNAL: 13
+      UNAVAILABLE: 14
+      UNAUTHENTICATED: 16
+
+  - id: grpc007
+    name: grpc_web
+    category: integration
+    description: gRPC-Web for browser clients via Envoy proxy
+    text: grpc-web browser client envoy proxy frontend
+    example: |
+      // Browser client via grpc-web
+      const client = new UserServiceClient("https://api.example.com", null, null);
+      const request = new GetUserRequest(); request.setId("123");
+      client.getUser(request, {}, (err, response) => { ... });
+    note: "Requires Envoy or similar proxy for protocol translation"

package/.agent/skills/tooling/api-protocols/data/trpc-patterns.yaml

@@ -0,0 +1,97 @@
+# tRPC Patterns - HSA API Protocols Skill
+# Updated: 2026-02-12
+
+metadata:
+  skill: api-protocols
+  domain: trpc
+  version: "1.0.0"
+  updated: "2026-02-12"
+  patterns_count: 7
+
+patterns:
+  - id: trpc001
+    name: router_setup
+    category: architecture
+    description: tRPC router with procedures and middleware
+    text: router setup procedure query mutation middleware
+    example: |
+      const appRouter = router({
+        user: router({
+          getById: publicProcedure
+            .input(z.object({ id: z.string() }))
+            .query(({ input }) => db.user.findUnique({ where: { id: input.id } })),
+          create: protectedProcedure
+            .input(createUserSchema)
+            .mutation(({ input, ctx }) => db.user.create({ data: input })),
+        }),
+      });
+      export type AppRouter = typeof appRouter;
+
+  - id: trpc002
+    name: middleware
+    category: architecture
+    description: tRPC middleware for auth, logging, rate limiting
+    text: middleware auth logging rate limiting procedure context
+    example: |
+      const isAuthed = t.middleware(({ ctx, next }) => {
+        if (!ctx.session) throw new TRPCError({ code: "UNAUTHORIZED" });
+        return next({ ctx: { ...ctx, user: ctx.session.user } });
+      });
+      const protectedProcedure = t.procedure.use(isAuthed);
+
+  - id: trpc003
+    name: nextjs_integration
+    category: integration
+    description: tRPC with Next.js App Router
+    text: nextjs app router integration server client component
+    example: |
+      // app/api/trpc/[trpc]/route.ts
+      const handler = fetchRequestHandler({ router: appRouter, createContext });
+      export { handler as GET, handler as POST };
+
+  - id: trpc004
+    name: react_query
+    category: client
+    description: tRPC React Query integration with automatic cache
+    text: react query client hook cache invalidation optimistic
+    example: |
+      const { data } = trpc.user.getById.useQuery({ id: "123" });
+      const utils = trpc.useUtils();
+      // Invalidate cache after mutation
+      await utils.user.getById.invalidate({ id: "123" });
+
+  - id: trpc005
+    name: monorepo_setup
+    category: architecture
+    description: tRPC in monorepo with shared types
+    text: monorepo shared types package workspace turborepo
+    example: |
+      // packages/api/src/router.ts — define router
+      // apps/web/src/trpc.ts — import AppRouter type
+      // Result: full type inference across packages
+
+  - id: trpc006
+    name: error_handling
+    category: design
+    description: tRPC error handling with typed errors
+    text: error handling TRPCError code message cause
+    example: |
+      throw new TRPCError({
+        code: "NOT_FOUND",
+        message: "User not found",
+        cause: originalError
+      });
+
+  - id: trpc007
+    name: subscription
+    category: realtime
+    description: tRPC subscriptions for real-time data
+    text: subscription real-time websocket observable
+    example: |
+      subscription: t.procedure.subscription(() => {
+        return observable<Message>((emit) => {
+          const onMessage = (msg: Message) => emit.next(msg);
+          ee.on("message", onMessage);
+          return () => ee.off("message", onMessage);
+        });
+      })