@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/gemini-cli/graphql-error-handling/SKILL.md

@@ -0,0 +1,167 @@
+# GraphQL Error Handling
+
+> Handle errors in GraphQL APIs with structured error types, result unions, and server-side error formatting
+
+## When to Use
+
+- Designing error responses for a GraphQL API
+- Choosing between top-level errors and typed error payloads
+- Implementing validation errors for mutations
+- Sanitizing error details before sending to clients
+- Building error handling patterns that work across client and server
+
+## Instructions
+
+1. **Distinguish between two error categories.** GraphQL has two channels for errors — treat them differently:
+   - **Top-level `errors` array:** For unexpected system errors (database down, null in non-null field, resolver throws). These are infrastructure problems the client cannot fix.
+   - **Typed error fields in payloads:** For expected domain errors (validation failures, business rule violations, not found). These are user-actionable.
+
+2. **Use a `UserError` type in mutation payloads.** This is the standard pattern for returning actionable errors alongside successful results.
+
+```graphql
+type UserError {
+  field: [String!]
+  message: String!
+  code: ErrorCode!
+}
+
+enum ErrorCode {
+  VALIDATION_FAILED
+  NOT_FOUND
+  FORBIDDEN
+  CONFLICT
+  RATE_LIMITED
+}
+
+type CreateOrderPayload {
+  order: Order
+  errors: [UserError!]!
+}
+```
+
+3. **Use union result types for operations with distinct error states.** When different error types carry different data, model them as a union.
+
+```graphql
+union CreateOrderResult = CreateOrderSuccess | ValidationError | InsufficientStockError
+
+type CreateOrderSuccess {
+  order: Order!
+}
+
+type ValidationError {
+  field: String!
+  message: String!
+}
+
+type InsufficientStockError {
+  productId: ID!
+  available: Int!
+  requested: Int!
+}
+```
+
+Clients use `__typename` to discriminate:
+
+```typescript
+const { data } = useMutation(CREATE_ORDER);
+if (data.createOrder.__typename === 'CreateOrderSuccess') {
+  // handle success
+} else if (data.createOrder.__typename === 'InsufficientStockError') {
+  // show "Only X available"
+}
+```
+
+4. **Throw `GraphQLError` with extensions for system errors.** When something genuinely fails, throw a `GraphQLError` with a code in `extensions` to help clients categorize the error.
+
+```typescript
+import { GraphQLError } from 'graphql';
+
+throw new GraphQLError('Not authorized to view this resource', {
+  extensions: {
+    code: 'FORBIDDEN',
+    http: { status: 403 },
+  },
+});
+```
+
+5. **Use `formatError` on the server to sanitize outgoing errors.** Strip stack traces, internal messages, and sensitive details in production. Log the full error server-side.
+
+```typescript
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  formatError: (formattedError, error) => {
+    // Log the raw error for debugging
+    logger.error(error);
+
+    // Strip internal details in production
+    if (process.env.NODE_ENV === 'production') {
+      if (formattedError.extensions?.code === 'INTERNAL_SERVER_ERROR') {
+        return {
+          message: 'An unexpected error occurred',
+          extensions: { code: 'INTERNAL_SERVER_ERROR' },
+        };
+      }
+      delete formattedError.extensions?.stacktrace;
+    }
+    return formattedError;
+  },
+});
+```
+
+6. **Never expose database errors, stack traces, or file paths to clients.** These leak implementation details and aid attackers. Always map internal errors to generic messages.
+
+7. **Implement error boundary resolvers for non-null fields.** If a non-null field resolver fails, the error propagates up to the nearest nullable parent, potentially nullifying large portions of the response. Place nullable "firewalls" at strategic points.
+
+```graphql
+type Query {
+  # If user resolver fails, only this field is null — not the entire response
+  user(id: ID!): User
+  # If feed fails, the entire Query becomes an error (bad)
+  feed: [Post!]!
+}
+```
+
+8. **On the client, handle both error channels.** Check `error` from the hook for network/system errors, and check the response payload for domain errors.
+
+```typescript
+const [createOrder, { error: networkError }] = useMutation(CREATE_ORDER);
+
+const result = await createOrder({ variables: { input } });
+if (networkError) {
+  // System error — show generic message
+}
+if (result.data?.createOrder.errors.length) {
+  // Domain error — show field-specific validation messages
+}
+```
+
+## Details
+
+**Partial data with errors:** GraphQL can return both `data` and `errors` in the same response. A query requesting three fields may return data for two and an error for one. Clients must handle this — do not treat any error as a total failure.
+
+**Error codes convention:** Apollo defines standard codes: `GRAPHQL_PARSE_FAILED`, `GRAPHQL_VALIDATION_FAILED`, `BAD_USER_INPUT`, `UNAUTHENTICATED`, `FORBIDDEN`, `INTERNAL_SERVER_ERROR`. Use these for consistency, and add custom codes for domain-specific errors.
+
+**Errors in lists:** If a list field is `[User!]!` and one user resolver fails, the entire list becomes null (bubbling up from the non-null item). Use `[User]!` if individual items can fail without destroying the whole list.
+
+**Testing error paths:** Write tests that specifically verify error responses — both the structure (correct code, field paths) and the absence of sensitive data (no stack traces in production mode).
+
+## Source
+
+https://www.apollographql.com/docs/apollo-server/data/errors/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/graphql-error-handling/skill.yaml

@@ -0,0 +1,39 @@
+name: graphql-error-handling
+version: '1.0.0'
+description: Handle errors in GraphQL with structured error types, union results, and formatError
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.graphql'
+  - '**/resolvers/**'
+  - '**/errors/**'
+related_skills:
+  - graphql-resolver-pattern
+  - graphql-schema-design
+  - graphql-apollo-server
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - errors
+  - error-handling
+  - graphql-error
+  - union-errors
+  - format-error
+metadata:
+  author: community
+  upstream: graphql.org/learn/validation
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/graphql-federation-pattern/SKILL.md

@@ -0,0 +1,137 @@
+# GraphQL Federation Pattern
+
+> Compose a unified GraphQL API from independently deployed subgraph services using Apollo Federation
+
+## When to Use
+
+- Multiple teams own different domains and need independent deployment
+- A monolithic GraphQL schema has grown too large for one service
+- You need to extend types across service boundaries (e.g., adding `orders` to `User` from the orders service)
+- Migrating from schema stitching to a standards-based composition model
+
+## Instructions
+
+1. **Each subgraph owns its domain types.** The users service defines `User`, the orders service defines `Order`. No type is defined in two places — types are extended across boundaries.
+
+```graphql
+# users subgraph
+type User @key(fields: "id") {
+  id: ID!
+  name: String!
+  email: String!
+}
+
+type Query {
+  user(id: ID!): User
+}
+```
+
+2. **Use `@key` to mark entity types.** An entity is a type that can be referenced and extended by other subgraphs. The `@key` directive specifies which fields uniquely identify the entity.
+
+3. **Extend entities in other subgraphs with stub types.** The orders service references `User` without redefining it — it provides only the key field and adds new fields.
+
+```graphql
+# orders subgraph
+type User @key(fields: "id") {
+  id: ID!
+  orders: [Order!]!
+}
+
+type Order @key(fields: "id") {
+  id: ID!
+  total: Money!
+  status: OrderStatus!
+  customer: User!
+}
+```
+
+4. **Implement `__resolveReference` for each entity.** This resolver is called by the gateway when it needs to hydrate a stub entity. It receives the key fields and returns the full object.
+
+```typescript
+const resolvers = {
+  User: {
+    __resolveReference: (ref: { id: string }, { dataSources }) => {
+      return dataSources.users.findById(ref.id);
+    },
+  },
+};
+```
+
+5. **Use the Apollo Router (or Gateway) to compose subgraphs.** The router fetches schemas from each subgraph, composes them into a supergraph, and routes incoming queries to the appropriate subgraphs.
+
+```yaml
+# supergraph-config.yaml
+subgraphs:
+  users:
+    routing_url: http://users-service:4001/graphql
+    schema:
+      subgraph_url: http://users-service:4001/graphql
+  orders:
+    routing_url: http://orders-service:4002/graphql
+    schema:
+      subgraph_url: http://orders-service:4002/graphql
+```
+
+6. **Use `@shareable` for fields that multiple subgraphs can resolve.** In Federation v2, fields are exclusive by default. Mark fields `@shareable` when multiple subgraphs need to return the same field.
+
+7. **Use `@override` to migrate fields between subgraphs.** When moving a field from one subgraph to another, the new owner uses `@override(from: "old-subgraph")` to claim resolution without a breaking change.
+
+8. **Use `@external`, `@provides`, and `@requires` for computed fields.** `@requires` tells the gateway to fetch specified fields from the owning subgraph before calling the current resolver.
+
+```graphql
+# shipping subgraph
+type Order @key(fields: "id") {
+  id: ID!
+  weight: Float @external
+  shippingCost: Float @requires(fields: "weight")
+}
+```
+
+9. **Run composition checks in CI.** Use `rover subgraph check` to validate that schema changes in one subgraph do not break the composed supergraph before deploying.
+
+10. **Keep the gateway stateless.** The router/gateway should not contain business logic — it composes and routes. All business logic lives in subgraphs.
+
+## Details
+
+**Federation v1 vs. v2:** Federation v2 (current) uses `@link` to import federation directives, supports `@shareable`, `@override`, `@inaccessible`, and progressive `@override` for safe migrations. Prefer v2 for new projects.
+
+**Query planning:** The gateway decomposes incoming queries into subgraph fetches. A query for `user { name orders { total } }` fetches `name` from the users subgraph, then fetches `orders` from the orders subgraph using the user's `id` as the reference key. This happens transparently.
+
+**Performance considerations:**
+
+- Entity references add network hops — the gateway calls `__resolveReference` on the owning subgraph
+- Use `@provides` to return extra fields alongside entities to reduce follow-up fetches
+- Batch entity lookups in `__resolveReference` using DataLoader
+
+**Ownership rules:**
+
+- A type's `@key` fields must be resolvable by the defining subgraph
+- Only one subgraph should define a field (unless `@shareable`)
+- Value types (types without `@key`) must be identical across subgraphs
+
+**Common mistakes:**
+
+- Circular entity references that cause infinite gateway loops
+- Missing `__resolveReference` — the gateway cannot hydrate the entity
+- Changing `@key` fields without updating all referencing subgraphs
+- Putting too many types in one subgraph, recreating the monolith
+
+## Source
+
+https://www.apollographql.com/docs/federation/
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/graphql-federation-pattern/skill.yaml

@@ -0,0 +1,41 @@
+name: graphql-federation-pattern
+version: '1.0.0'
+description: Compose a unified GraphQL API from independently deployed subgraph services
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.graphql'
+  - '**/*.gql'
+  - '**/schema/**'
+  - '**/subgraph/**'
+related_skills:
+  - graphql-schema-design
+  - graphql-resolver-pattern
+  - graphql-apollo-server
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - federation
+  - subgraph
+  - gateway
+  - entities
+  - extend
+  - key-directive
+metadata:
+  author: community
+  upstream: apollographql.com/docs/federation
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/graphql-pagination-patterns/SKILL.md

@@ -0,0 +1,175 @@
+# GraphQL Pagination Patterns
+
+> Implement cursor-based and offset pagination in GraphQL using the Relay connection specification
+
+## When to Use
+
+- Returning lists of items that may grow unboundedly
+- Building paginated feeds, search results, or admin tables
+- Choosing between cursor-based and offset-based pagination
+- Implementing infinite scroll or "load more" UI patterns
+- Ensuring consistent pagination when items are added or removed
+
+## Instructions
+
+1. **Use the Relay connection spec for cursor-based pagination.** Even if you do not use Relay on the client, the `Connection/Edge/PageInfo` pattern is the industry standard for GraphQL pagination.
+
+```graphql
+type Query {
+  users(first: Int, after: String, last: Int, before: String): UserConnection!
+}
+
+type UserConnection {
+  edges: [UserEdge!]!
+  pageInfo: PageInfo!
+  totalCount: Int
+}
+
+type UserEdge {
+  node: User!
+  cursor: String!
+}
+
+type PageInfo {
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+  endCursor: String
+}
+```
+
+2. **Implement cursor encoding with opaque strings.** Cursors should be opaque to clients — base64-encode the underlying value. Never expose raw database IDs or offsets as cursors.
+
+```typescript
+function encodeCursor(id: string): string {
+  return Buffer.from(`cursor:${id}`).toString('base64');
+}
+
+function decodeCursor(cursor: string): string {
+  const decoded = Buffer.from(cursor, 'base64').toString('utf-8');
+  return decoded.replace('cursor:', '');
+}
+```
+
+3. **Build the resolver to handle `first/after` (forward) and `last/before` (backward) pagination.**
+
+```typescript
+const resolvers = {
+  Query: {
+    users: async (_parent, { first, after, last, before }, { db }) => {
+      const limit = first ?? last ?? 20;
+      const afterId = after ? decodeCursor(after) : null;
+      const beforeId = before ? decodeCursor(before) : null;
+
+      const users = await db.users.findPaginated({
+        limit: limit + 1, // fetch one extra to determine hasNextPage
+        afterId,
+        beforeId,
+        direction: last ? 'backward' : 'forward',
+      });
+
+      const hasMore = users.length > limit;
+      const nodes = hasMore ? users.slice(0, limit) : users;
+
+      if (last) nodes.reverse();
+
+      return {
+        edges: nodes.map((user) => ({
+          node: user,
+          cursor: encodeCursor(user.id),
+        })),
+        pageInfo: {
+          hasNextPage: first ? hasMore : false,
+          hasPreviousPage: last ? hasMore : false,
+          startCursor: nodes[0] ? encodeCursor(nodes[0].id) : null,
+          endCursor: nodes[nodes.length - 1] ? encodeCursor(nodes[nodes.length - 1].id) : null,
+        },
+      };
+    },
+  },
+};
+```
+
+4. **Include `totalCount` when clients need it** (e.g., for "showing 1-20 of 342"). Be aware this requires a separate `COUNT(*)` query, which can be expensive on large tables.
+
+5. **For simple use cases, offset pagination is acceptable.** Use it for admin dashboards, data tables, or any context where "jump to page N" is needed and data does not change frequently.
+
+```graphql
+type Query {
+  users(offset: Int, limit: Int): UserList!
+}
+
+type UserList {
+  items: [User!]!
+  totalCount: Int!
+  hasMore: Boolean!
+}
+```
+
+6. **On the client, use `fetchMore` to load additional pages.**
+
+```typescript
+const { data, fetchMore } = useQuery(GET_USERS, { variables: { first: 20 } });
+
+const loadMore = () => {
+  fetchMore({
+    variables: { after: data.users.pageInfo.endCursor },
+    updateQuery: (prev, { fetchMoreResult }) => ({
+      users: {
+        ...fetchMoreResult.users,
+        edges: [...prev.users.edges, ...fetchMoreResult.users.edges],
+      },
+    }),
+  });
+};
+```
+
+7. **Set sensible defaults and maximums for `first`/`limit`.** Default to 20, cap at 100. This prevents clients from requesting unbounded result sets.
+
+```typescript
+const limit = Math.min(first ?? 20, 100);
+```
+
+8. **Use `@connection` directive (Apollo Client) to give paginated fields a stable cache key** when the same field is queried with different pagination arguments.
+
+## Details
+
+**Cursor vs. offset trade-offs:**
+
+- **Cursor-based:** Stable under concurrent inserts/deletes, efficient with indexed columns (e.g., `WHERE id > cursor`), no "page drift." Cannot jump to arbitrary pages.
+- **Offset-based:** Simple to implement, supports "jump to page N." Degrades with large offsets (`OFFSET 10000` scans and discards rows), unstable when items are inserted/deleted between pages.
+
+**Cursor implementation strategies:**
+
+- **ID-based:** `WHERE id > :cursor ORDER BY id` — simple, efficient, works when ordering by primary key
+- **Timestamp-based:** `WHERE created_at > :cursor ORDER BY created_at` — use a composite cursor (timestamp + id) for ties
+- **Composite:** Encode multiple sort values into the cursor for multi-column sorting
+
+**Performance considerations:**
+
+- Fetch `limit + 1` to determine `hasNextPage` without a separate count query
+- Use indexed columns for cursor comparison (`WHERE` clause must hit an index)
+- Cache `totalCount` separately if it is expensive and does not need to be real-time
+- For keyset pagination on composite sorts, build the `WHERE` clause dynamically
+
+**Apollo Client cache integration:** Apollo's `offsetLimitPagination()` and `relayStylePagination()` type policies handle merging paginated results in the cache automatically.
+
+## Source
+
+https://relay.dev/graphql/connections.htm
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/gemini-cli/graphql-pagination-patterns/skill.yaml

@@ -0,0 +1,40 @@
+name: graphql-pagination-patterns
+version: '1.0.0'
+description: Implement cursor-based and offset pagination in GraphQL using the connection spec
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.graphql'
+  - '**/resolvers/**'
+related_skills:
+  - graphql-schema-design
+  - graphql-resolver-pattern
+  - graphql-performance-patterns
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - pagination
+  - cursor
+  - connection
+  - edges
+  - pageinfo
+  - offset
+  - relay
+metadata:
+  author: community
+  upstream: relay.dev/graphql/connections.htm
+state:
+  persistent: false
+  files: []
+depends_on: []