@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/claude-code/graphql-client-patterns/SKILL.md

@@ -0,0 +1,152 @@
+# GraphQL Client Patterns
+
+> Structure GraphQL client code with fragments, cache normalization, and optimistic updates for responsive UIs
+
+## When to Use
+
+- Building a React/Vue/Svelte app that consumes a GraphQL API
+- Choosing between Apollo Client, urql, or lightweight clients
+- Managing client-side cache for GraphQL data
+- Implementing optimistic UI updates for mutations
+- Organizing queries, mutations, and fragments across a large frontend
+
+## Instructions
+
+1. **Co-locate queries with the components that use them.** Define the query in the same file (or adjacent `.graphql` file) as the component that renders the data. This makes data dependencies explicit.
+
+```typescript
+const GET_USER = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      id
+      name
+      ...UserAvatar
+    }
+  }
+  ${USER_AVATAR_FRAGMENT}
+`;
+
+function UserProfile({ userId }: { userId: string }) {
+  const { data, loading, error } = useQuery(GET_USER, { variables: { id: userId } });
+  if (loading) return <Skeleton />;
+  if (error) return <ErrorBanner error={error} />;
+  return <div>{data.user.name}</div>;
+}
+```
+
+2. **Use fragments to share field selections across queries.** Fragments prevent field duplication and ensure components always receive the fields they need, regardless of which query fetches the data.
+
+```typescript
+const USER_AVATAR_FRAGMENT = gql`
+  fragment UserAvatar on User {
+    id
+    avatarUrl
+    name
+  }
+`;
+
+// Reuse in any query that needs avatar data
+```
+
+3. **Configure the normalized cache with `typePolicies`.** Apollo Client's `InMemoryCache` normalizes by `__typename:id`. Customize merge behavior, pagination, and key fields in `typePolicies`.
+
+```typescript
+const cache = new InMemoryCache({
+  typePolicies: {
+    User: {
+      keyFields: ['id'],
+    },
+    Query: {
+      fields: {
+        feed: offsetLimitPagination(),
+      },
+    },
+  },
+});
+```
+
+4. **Use optimistic responses for instant UI feedback.** When the user performs a mutation, provide an `optimisticResponse` that mirrors the expected server response. The cache updates immediately; the real response replaces it when it arrives.
+
+```typescript
+const [toggleLike] = useMutation(TOGGLE_LIKE, {
+  optimisticResponse: {
+    toggleLike: {
+      __typename: 'Post',
+      id: postId,
+      isLiked: !currentlyLiked,
+      likeCount: currentlyLiked ? count - 1 : count + 1,
+    },
+  },
+});
+```
+
+5. **Choose the right cache update strategy after mutations:**
+   - **Automatic:** If the mutation returns the modified object with its `id` and `__typename`, the cache updates automatically.
+   - **`refetchQueries`:** Re-execute specific queries after the mutation. Simple but costs a network round-trip.
+   - **`update` function:** Manually read and write the cache for complex updates (e.g., adding an item to a list).
+
+```typescript
+const [addComment] = useMutation(ADD_COMMENT, {
+  update(cache, { data: { addComment } }) {
+    cache.modify({
+      id: cache.identify({ __typename: 'Post', id: postId }),
+      fields: {
+        comments(existing = []) {
+          const newRef = cache.writeFragment({
+            data: addComment,
+            fragment: COMMENT_FIELDS,
+          });
+          return [...existing, newRef];
+        },
+      },
+    });
+  },
+});
+```
+
+6. **Handle loading and error states consistently.** Create reusable patterns — a `<QueryResult>` wrapper component or custom hooks that standardize loading/error/empty states across the app.
+
+7. **Use `fetchPolicy` intentionally.**
+   - `cache-first` (default): Read from cache, fetch only on miss. Best for stable data.
+   - `network-only`: Always fetch, update cache. Best for frequently changing data.
+   - `cache-and-network`: Return cached data immediately, then update from network. Best UX for lists.
+   - `no-cache`: Skip the cache entirely. Use for one-off sensitive data.
+
+8. **Avoid over-fetching with field-level selections.** Only request the fields the component needs. The normalized cache works best when queries request predictable field sets.
+
+## Details
+
+**Apollo Client vs. urql vs. lightweight clients:** Apollo Client offers the richest cache and ecosystem but is the largest bundle (~40KB). urql is smaller (~15KB) with a plugin-based architecture (exchanges). For simple use cases, `graphql-request` (~5KB) provides a fetch wrapper without caching.
+
+**Cache normalization explained:** Apollo splits query results into individual objects keyed by `__typename:id`. When a mutation returns an updated `User`, every query that references that user sees the update. This works only if every queried type has a stable `id` field.
+
+**Fragment colocation pattern (Relay-style):** Each component declares a fragment for the data it needs. Parent components spread those fragments into their queries. This creates a clear contract: the component works if and only if its fragment is included.
+
+**Polling vs. subscriptions:** Use `pollInterval` for data that changes infrequently (dashboard stats). Use subscriptions for real-time data (chat messages, live scores). Polling is simpler to implement and does not require WebSocket infrastructure.
+
+**Common mistakes:**
+
+- Missing `__typename` in optimistic responses (cache cannot normalize without it)
+- Using `refetchQueries` for every mutation instead of leveraging automatic cache updates
+- Requesting entire objects when only a few fields are needed (over-fetching)
+- Not handling the `error` state from `useQuery` (silent failures)
+
+## Source
+
+https://www.apollographql.com/docs/react/
+
+## 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/claude-code/graphql-client-patterns/skill.yaml

@@ -0,0 +1,41 @@
+name: graphql-client-patterns
+version: '1.0.0'
+description: Structure GraphQL client code with fragments, cache policies, and optimistic updates
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.graphql'
+  - '**/*.gql'
+  - '**/queries/**'
+  - '**/mutations/**'
+related_skills:
+  - graphql-codegen-pattern
+  - graphql-apollo-server
+  - graphql-error-handling
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - apollo-client
+  - urql
+  - cache
+  - fragments
+  - optimistic-update
+  - refetch
+metadata:
+  author: community
+  upstream: apollographql.com/docs/react
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/graphql-codegen-pattern/SKILL.md

@@ -0,0 +1,154 @@
+# GraphQL Code Generator Pattern
+
+> Generate type-safe TypeScript code from GraphQL schemas and operations to eliminate manual type maintenance
+
+## When to Use
+
+- Starting a new GraphQL project with TypeScript
+- Adding type safety to existing GraphQL queries and mutations
+- Generating typed React hooks for Apollo Client or urql
+- Generating resolver type signatures for the server
+- Keeping TypeScript types in sync with schema changes
+
+## Instructions
+
+1. **Install the codegen CLI and core plugins.**
+
+```bash
+npm install -D @graphql-codegen/cli @graphql-codegen/typescript @graphql-codegen/typescript-operations @graphql-codegen/typescript-resolvers
+```
+
+2. **Create a `codegen.ts` configuration file** at the project root. Use the TypeScript config format for type-safe configuration.
+
+```typescript
+import type { CodegenConfig } from '@graphql-codegen/cli';
+
+const config: CodegenConfig = {
+  schema: 'src/schema/**/*.graphql',
+  documents: 'src/**/*.{ts,tsx}',
+  generates: {
+    'src/__generated__/types.ts': {
+      plugins: ['typescript', 'typescript-operations'],
+      config: {
+        strictScalars: true,
+        scalars: {
+          DateTime: 'string',
+          JSON: 'Record<string, unknown>',
+        },
+      },
+    },
+    'src/__generated__/resolvers.ts': {
+      plugins: ['typescript', 'typescript-resolvers'],
+      config: {
+        useIndexSignature: true,
+        contextType: '../context#Context',
+      },
+    },
+  },
+};
+
+export default config;
+```
+
+3. **Use `TypedDocumentNode` for end-to-end type safety.** This plugin generates typed document nodes that carry their variables and result types — Apollo Client and urql pick them up automatically.
+
+```typescript
+// codegen generates:
+// export const GetUserDocument: TypedDocumentNode<GetUserQuery, GetUserQueryVariables>
+
+// Usage — variables and data are fully typed with no extra annotations:
+const { data } = useQuery(GetUserDocument, { variables: { id: '1' } });
+// data.user.name is typed as string
+```
+
+4. **Generate typed React hooks for client-side usage.** Add the `typescript-react-apollo` or `typescript-urql` plugin to generate `useGetUserQuery()` hooks directly.
+
+```typescript
+// codegen.ts addition
+'src/__generated__/hooks.ts': {
+  plugins: ['typescript', 'typescript-operations', 'typescript-react-apollo'],
+  config: {
+    withHooks: true,
+    withComponent: false,
+  },
+},
+```
+
+5. **Use `near-operation-file` preset to co-locate generated types** next to the files that define the operations, instead of one giant generated file.
+
+```typescript
+generates: {
+  'src/': {
+    preset: 'near-operation-file',
+    presetConfig: { extension: '.generated.ts', baseTypesPath: '__generated__/types.ts' },
+    plugins: ['typescript-operations', 'typescript-react-apollo'],
+  },
+},
+```
+
+6. **Run codegen in watch mode during development** and as a CI check to ensure types are up to date.
+
+```json
+{
+  "scripts": {
+    "codegen": "graphql-codegen",
+    "codegen:watch": "graphql-codegen --watch"
+  }
+}
+```
+
+7. **Enable `strictScalars`** to force explicit scalar mappings. Without this, custom scalars default to `any`, defeating the purpose of code generation.
+
+8. **Type your resolvers with the generated `Resolvers` type.** This catches mismatches between your schema and resolver implementations at compile time.
+
+```typescript
+import { Resolvers } from './__generated__/resolvers';
+
+export const resolvers: Resolvers = {
+  Query: {
+    user: async (_parent, { id }, context) => {
+      // args.id is typed as string, return type is enforced
+      return context.dataSources.users.findById(id);
+    },
+  },
+};
+```
+
+9. **Add generated files to `.gitignore` or commit them** — pick one strategy and enforce it. Committing ensures CI does not need the schema endpoint; ignoring ensures no stale generated code.
+
+## Details
+
+**Plugin ecosystem:** `typescript` (base types from schema), `typescript-operations` (types from queries/mutations), `typescript-resolvers` (resolver signatures), `typescript-react-apollo` / `typescript-urql` (framework hooks), `typed-document-node` (framework-agnostic typed documents).
+
+**Schema sources:** Codegen can read schemas from `.graphql` files, a running endpoint, a JSON introspection result, or code-first builders. Prefer `.graphql` files for CI stability.
+
+**Fragment handling:** Codegen generates types for fragments and composes them into operation types. Use fragments for shared fields to keep generated types DRY.
+
+**Enum handling:** By default, codegen generates TypeScript `enum`. Set `enumsAsTypes: true` to generate union string literals instead, which work better with tree-shaking and are simpler to use.
+
+**Common mistakes:**
+
+- Forgetting to re-run codegen after schema changes (use watch mode or CI check)
+- Not mapping custom scalars, resulting in `any` types leaking through
+- Generating into `node_modules` or build output (generate into `src/`)
+- Mixing hand-written and generated types for the same schema entity
+
+## Source
+
+https://the-guild.dev/graphql/codegen
+
+## 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/claude-code/graphql-codegen-pattern/skill.yaml

@@ -0,0 +1,39 @@
+name: graphql-codegen-pattern
+version: '1.0.0'
+description: Generate type-safe code from GraphQL schemas and operations using GraphQL Code Generator
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.graphql'
+  - '**/*.gql'
+  - '**/codegen.ts'
+  - '**/codegen.yml'
+related_skills:
+  - graphql-schema-design
+  - graphql-client-patterns
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - codegen
+  - code-generation
+  - typed-document-node
+  - type-safety
+  - schema-types
+metadata:
+  author: community
+  upstream: the-guild.dev/graphql/codegen
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/claude-code/graphql-dataloader-pattern/SKILL.md

@@ -0,0 +1,138 @@
+# GraphQL DataLoader Pattern
+
+> Batch and cache data fetches to eliminate N+1 queries in GraphQL resolvers
+
+## When to Use
+
+- Field resolvers execute per item in a list, causing N+1 database queries
+- Multiple resolvers in the same request need the same record
+- You need request-scoped caching without a shared application cache
+- Optimizing GraphQL API response times without restructuring the schema
+
+## Instructions
+
+1. **Create one DataLoader instance per request, per resource type.** DataLoader batches all `.load(key)` calls within a single tick of the event loop into one batch function call. It must be request-scoped to avoid leaking cached data between users.
+
+```typescript
+import DataLoader from 'dataloader';
+
+function createLoaders(db: Database) {
+  return {
+    userById: new DataLoader<string, User>(async (ids) => {
+      const users = await db.users.findByIds([...ids]);
+      const userMap = new Map(users.map((u) => [u.id, u]));
+      return ids.map((id) => userMap.get(id) || new Error(`User ${id} not found`));
+    }),
+  };
+}
+```
+
+2. **The batch function must return results in the same order as the input keys.** This is the critical contract. If key index 0 is `"abc"`, result index 0 must be the value for `"abc"` or an `Error`. Use a Map to reorder database results to match the input key order.
+
+3. **Attach loaders to the GraphQL context.** Create fresh loaders for each request in your server's context factory.
+
+```typescript
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  context: ({ req }) => ({
+    currentUser: authenticate(req),
+    loaders: createLoaders(db),
+  }),
+});
+```
+
+4. **Use `.load()` in field resolvers instead of direct database calls.**
+
+```typescript
+const resolvers = {
+  Order: {
+    customer: (order, _args, { loaders }) => {
+      return loaders.userById.load(order.customerId);
+    },
+  },
+  Comment: {
+    author: (comment, _args, { loaders }) => {
+      return loaders.userById.load(comment.authorId);
+    },
+  },
+};
+```
+
+When a query returns 50 orders, the `customer` field resolver calls `.load()` 50 times, but DataLoader batches them into a single `findByIds([...50 ids])` call.
+
+5. **Use `.loadMany()` for one-to-many relationships** where you have an array of keys.
+
+```typescript
+const resolvers = {
+  User: {
+    favoriteProducts: (user, _args, { loaders }) => {
+      return loaders.productById.loadMany(user.favoriteProductIds);
+    },
+  },
+};
+```
+
+6. **Create loaders for different access patterns.** A `userById` loader and a `userByEmail` loader are separate DataLoader instances with separate batch functions and separate caches.
+
+7. **Use `.prime()` to warm the cache** when you already have the data. After a mutation creates a user, prime the loader so subsequent reads in the same request hit the cache.
+
+```typescript
+const newUser = await db.users.create(input);
+context.loaders.userById.prime(newUser.id, newUser);
+```
+
+8. **Disable caching for loaders where stale reads are dangerous.** Pass `{ cache: false }` to the DataLoader constructor if you need batching without memoization — rare, but useful for data that changes mid-request.
+
+## Details
+
+**How batching works:** DataLoader collects all `.load()` calls made synchronously (within the same microtask/tick). At the end of the tick, it calls the batch function once with all collected keys, then distributes results back to each caller. This turns N sequential queries into 1 batched query.
+
+**Per-request scope is mandatory.** If you reuse a DataLoader across requests, User A's data will be served from cache to User B. Always create new DataLoader instances in the context factory.
+
+**Batch function constraints:**
+
+- Must accept an array of keys and return a Promise of an array of values
+- Return array length must equal input keys length
+- Return array order must match input keys order
+- Individual errors are represented as `Error` instances at the corresponding index
+
+**Nested batching:** DataLoader batches within a single tick, but GraphQL resolves level by level. This means field resolvers at depth 2 are batched separately from depth 3. This is usually fine — each level gets one batch call per loader.
+
+**Composite keys:** When the lookup requires multiple values (e.g., `orgId` + `userId`), serialize the key to a string and provide a `cacheKeyFn`:
+
+```typescript
+new DataLoader<{ orgId: string; userId: string }, Membership>(
+  async (keys) => {
+    /* batch by org+user */
+  },
+  { cacheKeyFn: (key) => `${key.orgId}:${key.userId}` }
+);
+```
+
+**Common mistakes:**
+
+- Creating DataLoader outside request scope (data leaks between users)
+- Returning results in database order instead of input key order (mismatched results)
+- Using DataLoader for write operations (it is a read optimization)
+- Not handling missing records (returning `undefined` instead of `Error` breaks the contract)
+
+## Source
+
+https://github.com/graphql/dataloader
+
+## 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/claude-code/graphql-dataloader-pattern/skill.yaml

@@ -0,0 +1,38 @@
+name: graphql-dataloader-pattern
+version: '1.0.0'
+description: Batch and cache data fetches to eliminate N+1 queries in GraphQL resolvers
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/resolvers/**'
+  - '**/dataloaders/**'
+  - '**/loaders/**'
+related_skills:
+  - graphql-resolver-pattern
+  - graphql-performance-patterns
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - dataloader
+  - batching
+  - n-plus-one
+  - caching
+  - per-request
+metadata:
+  author: community
+  upstream: github.com/graphql/dataloader
+state:
+  persistent: false
+  files: []
+depends_on: []