@harness-engineering/cli 1.23.1 → 1.24.0

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

@@ -0,0 +1,166 @@
+# GraphQL Performance Patterns
+
+> Optimize GraphQL API performance with query complexity analysis, caching, persisted queries, and DataLoader
+
+## When to Use
+
+- GraphQL API response times are degrading under load
+- Protecting the API from expensive or abusive queries
+- Implementing server-side or CDN-level caching for GraphQL
+- Reducing payload sizes and network round-trips
+- Diagnosing and fixing N+1 query problems
+
+## Instructions
+
+1. **Use DataLoader to batch and deduplicate database queries.** This is the single most impactful optimization for most GraphQL APIs. See the `graphql-dataloader-pattern` skill for detailed implementation.
+
+2. **Limit query depth to prevent deeply nested abuse.** Use `graphql-depth-limit` to reject queries that exceed a reasonable nesting level.
+
+```typescript
+import depthLimit from 'graphql-depth-limit';
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  validationRules: [depthLimit(10)],
+});
+```
+
+3. **Implement query complexity analysis.** Assign costs to fields and reject queries that exceed a budget. List fields should cost more because they multiply nested resolver costs.
+
+```graphql
+type Query {
+  users(first: Int): UserConnection @complexity(value: 1, multipliers: ["first"])
+}
+
+type User {
+  posts: [Post!]! @complexity(value: 2)
+}
+```
+
+```typescript
+import { createComplexityLimitRule } from 'graphql-validation-complexity';
+
+const server = new ApolloServer({
+  validationRules: [
+    createComplexityLimitRule(1000, {
+      scalarCost: 1,
+      objectCost: 2,
+      listFactor: 10,
+    }),
+  ],
+});
+```
+
+4. **Use `@cacheControl` directives for response caching.** Mark types and fields with their cache-ability and max age. The Apollo cache control plugin aggregates these into HTTP cache headers.
+
+```graphql
+type Product @cacheControl(maxAge: 3600) {
+  id: ID!
+  name: String!
+  price: Money! @cacheControl(maxAge: 60)
+  reviews: [Review!]! @cacheControl(maxAge: 0)
+}
+```
+
+5. **Enable Automatic Persisted Queries (APQ)** to reduce request payload sizes. Instead of sending the full query string, clients send a hash. The server looks up the query by hash; on a miss, the client resends the full query and the server caches it.
+
+```typescript
+import { ApolloServerPluginCacheControl } from '@apollo/server/plugin/cacheControl';
+import { KeyValueCache } from '@apollo/utils.keyvaluecache';
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  plugins: [ApolloServerPluginCacheControl({ defaultMaxAge: 5 })],
+  cache: new KeyvAdapter(new Keyv('redis://localhost:6379')),
+});
+```
+
+6. **Implement response caching at the CDN or reverse proxy level.** When queries have `@cacheControl` hints, set `Cache-Control` headers so Cloudflare, Fastly, or Varnish can cache responses without hitting your server.
+
+7. **Use `@defer` for progressive loading (if supported).** `@defer` allows the server to return parts of the response incrementally, sending critical data first and deferring expensive fields.
+
+```graphql
+query ProductPage($id: ID!) {
+  product(id: $id) {
+    name
+    price
+    ... @defer {
+      reviews {
+        content
+        rating
+      }
+      recommendations {
+        name
+      }
+    }
+  }
+}
+```
+
+8. **Avoid over-fetching at the resolver level.** Use the `info` argument or look-ahead libraries to fetch only the fields the client requested from the database.
+
+```typescript
+import { parseResolveInfo } from 'graphql-parse-resolve-info';
+
+const resolvers = {
+  Query: {
+    user: (_parent, { id }, _context, info) => {
+      const fields = parseResolveInfo(info);
+      const select = Object.keys(fields.fieldsByTypeName.User);
+      return db.users.findById(id, { select });
+    },
+  },
+};
+```
+
+9. **Monitor query performance in production.** Use Apollo Studio, Grafana, or custom logging to track per-operation latency, error rates, and cache hit ratios. Identify the slowest operations and optimize them specifically.
+
+10. **Set a timeout on resolver execution.** Prevent runaway resolvers from holding connections open indefinitely.
+
+```typescript
+const withTimeout = <T>(promise: Promise<T>, ms: number): Promise<T> => {
+  const timeout = new Promise<never>((_, reject) =>
+    setTimeout(() => reject(new Error('Resolver timeout')), ms)
+  );
+  return Promise.race([promise, timeout]);
+};
+```
+
+## Details
+
+**N+1 problem explained:** A query for 50 users, each with `posts`, executes 1 query for users + 50 queries for posts = 51 queries. DataLoader reduces this to 2 queries (1 for users, 1 batched for all posts).
+
+**Caching layers (from hot to cold):**
+
+1. **DataLoader** — per-request memoization (eliminates duplicate fetches within a single query)
+2. **Application cache** — Redis/Memcached (shared across requests, minutes-to-hours TTL)
+3. **HTTP cache** — CDN/reverse proxy (shared across users for public data, seconds-to-hours TTL)
+4. **Client cache** — Apollo Client InMemoryCache (per-user, session-duration)
+
+**Query allowlisting (persisted queries):** In high-security environments, only allow pre-registered queries. Reject any query not in the allowlist. This prevents attackers from crafting expensive or introspection queries.
+
+**Pagination impact:** Always paginate list fields. An unpaginated `users: [User!]!` that returns 100K records will crush your server regardless of other optimizations.
+
+**Tracing:** Enable Apollo Tracing or OpenTelemetry to see per-resolver execution times. The slowest resolver in a query determines the response time (for sequential resolution) or indicates the bottleneck (for parallel resolution).
+
+## Source
+
+https://www.apollographql.com/docs/apollo-server/performance/caching/
+
+## 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-performance-patterns/skill.yaml

@@ -0,0 +1,39 @@
+name: graphql-performance-patterns
+version: '1.0.0'
+description: Optimize GraphQL API performance with query complexity limits, caching, and persisted queries
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.graphql'
+  - '**/resolvers/**'
+related_skills:
+  - graphql-dataloader-pattern
+  - graphql-resolver-pattern
+  - graphql-pagination-patterns
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - performance
+  - caching
+  - persisted-queries
+  - query-complexity
+  - depth-limit
+  - n-plus-one
+metadata:
+  author: community
+  upstream: apollographql.com/docs/apollo-server/performance/caching
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,129 @@
+# GraphQL Resolver Pattern
+
+> Implement resolvers with clean separation between data fetching, business logic, and response shaping
+
+## When to Use
+
+- Writing resolvers for queries, mutations, or subscriptions
+- Structuring resolver files across a growing schema
+- Deciding where to place business logic vs. data access
+- Debugging N+1 queries or resolver chain issues
+- Setting up the resolver context object
+
+## Instructions
+
+1. **Understand the resolver signature.** Every resolver receives four arguments: `(parent, args, context, info)`. Use them intentionally — `parent` carries the result from the parent resolver, `args` contains the field arguments, `context` is the per-request shared state, `info` holds the AST and field metadata.
+
+```typescript
+const resolvers = {
+  Query: {
+    user: (_parent: unknown, args: { id: string }, context: Context) => {
+      return context.dataSources.users.findById(args.id);
+    },
+  },
+};
+```
+
+2. **Keep resolvers thin.** A resolver should validate input, delegate to a service or data source, and return the result. It should not contain business logic, raw SQL, or HTTP calls directly.
+
+```typescript
+// Good — resolver delegates to service
+const resolvers = {
+  Mutation: {
+    cancelOrder: async (_parent, { input }, { dataSources, currentUser }) => {
+      const result = await dataSources.orders.cancel(input.orderId, input.reason, currentUser);
+      return {
+        order: result.order,
+        refundAmount: result.refund,
+        errors: result.errors,
+      };
+    },
+  },
+};
+
+// Bad — business logic in resolver
+const resolvers = {
+  Mutation: {
+    cancelOrder: async (_parent, { input }, { db }) => {
+      const order = await db.query('SELECT * FROM orders WHERE id = $1', [input.orderId]);
+      if (order.status === 'SHIPPED') throw new Error('Cannot cancel shipped order');
+      // ... 50 lines of business logic
+    },
+  },
+};
+```
+
+3. **Use field resolvers for derived data.** When a field on a type needs computation or a separate data fetch, write a field resolver on the type instead of pre-loading everything in the parent query resolver.
+
+```typescript
+const resolvers = {
+  User: {
+    fullName: (user) => `${user.firstName} ${user.lastName}`,
+    orders: (user, _args, { dataSources }) => {
+      return dataSources.orders.findByUserId(user.id);
+    },
+  },
+};
+```
+
+4. **Build a rich context object.** Initialize `context` in your server setup with authenticated user, data sources, and request-scoped services. Avoid putting the raw `req`/`res` objects in context — wrap what you need.
+
+```typescript
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  context: async ({ req }) => ({
+    currentUser: await authenticateToken(req.headers.authorization),
+    dataSources: {
+      users: new UserDataSource(db),
+      orders: new OrderDataSource(db),
+    },
+    logger: createRequestLogger(req),
+  }),
+});
+```
+
+5. **Organize resolvers by domain.** Split resolvers into files matching your domain areas — `user.resolvers.ts`, `order.resolvers.ts` — then merge them using `lodash.merge` or a resolver merging utility.
+
+6. **Return promises, not awaited values, when possible.** GraphQL execution handles promises natively. Returning the promise directly (without `await`) allows the executor to parallelize sibling field resolution.
+
+7. **Use the `info` argument sparingly.** It provides the full query AST, useful for advanced optimizations (look-ahead to avoid over-fetching), but parsing it adds complexity. Prefer DataLoader for batching over manual `info` inspection.
+
+8. **Handle null propagation deliberately.** If a field resolver throws or returns `null` for a non-null field, the error bubbles up. Consider wrapping risky resolvers in try-catch and returning `null` (for nullable fields) or structured errors (for mutation payloads).
+
+## Details
+
+**Resolver chain execution:** GraphQL resolves fields top-down, breadth-first within each level. The return value of a parent resolver becomes the `parent` argument of its child field resolvers. If a Query resolver returns `{ id: '1', name: 'Alice' }`, the `User.name` field resolver receives that object as `parent`.
+
+**Default resolver:** If no resolver is defined for a field, GraphQL uses the default resolver: `parent[fieldName]`. This means you only need explicit resolvers for fields that require computation, transformation, or separate data fetching.
+
+**Data source pattern (Apollo):** Encapsulate data access in classes that extend `DataSource`. Each data source gets access to the request context and can implement caching, batching, and error handling independently.
+
+**Testing resolvers:** Test resolvers by calling them directly with mocked `context` and `args`. Test the full GraphQL execution path separately with integration tests using `executeOperation` or `server.executeOperation`.
+
+**Common pitfalls:**
+
+- Forgetting that field resolvers run per-item in a list (causes N+1 without DataLoader)
+- Mutating the `parent` object in a field resolver (shared reference across sibling fields)
+- Throwing raw errors instead of returning structured `UserError` types in mutations
+- Over-fetching in parent resolvers to avoid field resolvers (defeats lazy resolution)
+
+## Source
+
+https://graphql.org/learn/execution/
+
+## 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-resolver-pattern/skill.yaml

@@ -0,0 +1,39 @@
+name: graphql-resolver-pattern
+version: '1.0.0'
+description: Implement resolvers with clean separation between data fetching and business logic
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/resolvers/**'
+  - '**/*.resolvers.ts'
+  - '**/*.graphql'
+related_skills:
+  - graphql-schema-design
+  - graphql-dataloader-pattern
+  - graphql-error-handling
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - resolvers
+  - context
+  - parent
+  - field-resolvers
+  - data-sources
+metadata:
+  author: community
+  upstream: graphql.org/learn/execution
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/gemini-cli/graphql-schema-design/SKILL.md

@@ -0,0 +1,145 @@
+# GraphQL Schema Design
+
+> Design expressive, evolvable GraphQL schemas with clear type hierarchies and strong nullability contracts
+
+## When to Use
+
+- Designing a new GraphQL API from scratch
+- Adding types, queries, or mutations to an existing schema
+- Deciding between interfaces, unions, and concrete types
+- Establishing nullability conventions for a team
+- Planning schema evolution without breaking existing clients
+
+## Instructions
+
+1. **Start with the domain, not the UI.** Model your schema around business entities (Order, Product, User), not around specific screens or components. A well-modeled domain schema serves multiple clients without per-client hacks.
+
+2. **Use non-null by default.** Mark fields as `String!` (non-null) unless the field genuinely can be absent. Non-null fields simplify client code by eliminating null checks. Reserve nullable fields for truly optional data (e.g., `middleName: String`).
+
+3. **Prefer specific types over generic ones.** Use custom scalars (`DateTime`, `URL`, `EmailAddress`) instead of plain `String` for fields with validation semantics. Use enums for closed sets of values.
+
+```graphql
+scalar DateTime
+scalar URL
+
+enum OrderStatus {
+  PENDING
+  CONFIRMED
+  SHIPPED
+  DELIVERED
+  CANCELLED
+}
+
+type Order {
+  id: ID!
+  status: OrderStatus!
+  createdAt: DateTime!
+  trackingUrl: URL
+}
+```
+
+4. **Use interfaces for shared field contracts.** When multiple types share fields and clients query them polymorphically, define an interface. Use unions when types share no fields but appear in the same list.
+
+```graphql
+interface Node {
+  id: ID!
+}
+
+interface Timestamped {
+  createdAt: DateTime!
+  updatedAt: DateTime!
+}
+
+type User implements Node & Timestamped {
+  id: ID!
+  createdAt: DateTime!
+  updatedAt: DateTime!
+  name: String!
+}
+
+union SearchResult = User | Product | Order
+```
+
+5. **Design mutations around actions, not CRUD.** Name mutations after the business action: `cancelOrder`, `approveRefund`, `inviteTeamMember` — not `updateOrder(status: CANCELLED)`. Each mutation should have a dedicated input type and a dedicated payload type.
+
+```graphql
+input CancelOrderInput {
+  orderId: ID!
+  reason: String!
+}
+
+type CancelOrderPayload {
+  order: Order!
+  refundAmount: Money
+  errors: [UserError!]!
+}
+
+type Mutation {
+  cancelOrder(input: CancelOrderInput!): CancelOrderPayload!
+}
+```
+
+6. **Always include a `UserError` type in mutation payloads.** This separates expected domain errors (validation failures, business rule violations) from unexpected system errors (which use GraphQL's top-level `errors` array).
+
+```graphql
+type UserError {
+  field: [String!]
+  message: String!
+  code: ErrorCode!
+}
+```
+
+7. **Use the Relay connection spec for paginated lists.** Even if you do not use Relay on the client, the `Connection/Edge/PageInfo` pattern is well-understood, cursor-based, and forward-compatible.
+
+8. **Version through evolution, not URL paths.** Add new fields freely. Deprecate old fields with `@deprecated(reason: "Use newField instead")`. Never remove fields without a deprecation period and client migration.
+
+9. **Keep the schema file as the source of truth.** Whether you use schema-first or code-first, ensure there is one canonical `.graphql` file (or set of files) that documents every type. Generate code from the schema, not the other way around.
+
+10. **Document with descriptions.** Add descriptions above types and fields — they appear in GraphiQL/Apollo Studio and serve as living API docs.
+
+```graphql
+"""
+A customer order containing one or more line items.
+"""
+type Order {
+  """
+  Unique identifier for the order.
+  """
+  id: ID!
+}
+```
+
+## Details
+
+**Naming conventions:** Types are `PascalCase`, fields are `camelCase`, enums are `SCREAMING_SNAKE_CASE`. Input types end with `Input`, payload types end with `Payload`.
+
+**Nullability trade-offs:** Non-null fields are safer for clients but less forgiving for servers — if a non-null resolver throws, the error bubbles up to the nearest nullable parent, potentially nullifying an entire object. Place nullable "firewalls" at strategic points (e.g., nullable list items) to limit blast radius.
+
+**Schema stitching vs. federation:** For monolithic APIs, a single schema file works. For microservices, prefer Apollo Federation where each service owns its slice of the graph and extends shared types with `@key`.
+
+**Anti-patterns to avoid:**
+
+- Generic `update` mutations with a giant optional input type — they are unvalidatable and untraceable
+- Deeply nested types without pagination — they cause unbounded query cost
+- Using `JSON` scalar as a catch-all — it defeats the purpose of a typed schema
+- Mixing authentication concerns into the schema (use directives or middleware instead)
+
+## Source
+
+https://graphql.org/learn/schema/
+
+## 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-schema-design/skill.yaml

@@ -0,0 +1,41 @@
+name: graphql-schema-design
+version: '1.0.0'
+description: Design expressive, evolvable GraphQL schemas with clear type hierarchies
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.graphql'
+  - '**/*.gql'
+  - '**/schema/**'
+related_skills:
+  - graphql-resolver-pattern
+  - graphql-pagination-patterns
+  - graphql-federation-pattern
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - schema
+  - types
+  - interfaces
+  - unions
+  - input-types
+  - enums
+  - nullability
+metadata:
+  author: community
+  upstream: graphql.org/learn/schema
+state:
+  persistent: false
+  files: []
+depends_on: []