@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/codex/graphql-auth-patterns/SKILL.md

@@ -0,0 +1,197 @@
+# GraphQL Auth Patterns
+
+> Implement authentication and authorization in GraphQL with context-based identity, directives, and field-level guards
+
+## When to Use
+
+- Adding authentication to a GraphQL API
+- Implementing role-based or permission-based access control
+- Protecting specific fields, types, or mutations
+- Choosing between directive-based and resolver-based auth
+- Preventing unauthorized data access in nested resolvers
+
+## Instructions
+
+1. **Authenticate in the context factory, not in resolvers.** Extract and verify the auth token during context creation. Every resolver then has access to `context.currentUser` without re-authenticating.
+
+```typescript
+const server = new ApolloServer({ typeDefs, resolvers });
+
+app.use(
+  '/graphql',
+  expressMiddleware(server, {
+    context: async ({ req }) => {
+      const token = req.headers.authorization?.replace('Bearer ', '');
+      const currentUser = token ? await verifyJWT(token) : null;
+      return { currentUser };
+    },
+  })
+);
+```
+
+2. **Create a reusable auth guard function** that resolvers call to check permissions. This keeps authorization logic in one place.
+
+```typescript
+function requireAuth(context: Context): AuthenticatedUser {
+  if (!context.currentUser) {
+    throw new GraphQLError('Authentication required', {
+      extensions: { code: 'UNAUTHENTICATED' },
+    });
+  }
+  return context.currentUser;
+}
+
+function requireRole(context: Context, role: string): AuthenticatedUser {
+  const user = requireAuth(context);
+  if (!user.roles.includes(role)) {
+    throw new GraphQLError('Insufficient permissions', {
+      extensions: { code: 'FORBIDDEN' },
+    });
+  }
+  return user;
+}
+```
+
+3. **Use schema directives for declarative auth.** Define `@auth` and `@hasRole` directives to annotate the schema. Implement them as schema transforms.
+
+```graphql
+directive @auth on FIELD_DEFINITION | OBJECT
+directive @hasRole(role: String!) on FIELD_DEFINITION
+
+type Query {
+  me: User @auth
+  adminDashboard: Dashboard @hasRole(role: "ADMIN")
+  publicPosts: [Post!]!
+}
+
+type User @auth {
+  id: ID!
+  email: String!
+  role: String!
+}
+```
+
+4. **Implement directive transforms using `@graphql-tools/utils`.**
+
+```typescript
+import { mapSchema, getDirective, MapperKind } from '@graphql-tools/utils';
+
+function authDirectiveTransformer(schema: GraphQLSchema) {
+  return mapSchema(schema, {
+    [MapperKind.OBJECT_FIELD]: (fieldConfig) => {
+      const authDirective = getDirective(schema, fieldConfig, 'auth')?.[0];
+      const roleDirective = getDirective(schema, fieldConfig, 'hasRole')?.[0];
+
+      if (authDirective || roleDirective) {
+        const originalResolve = fieldConfig.resolve ?? defaultFieldResolver;
+        fieldConfig.resolve = async (source, args, context, info) => {
+          if (roleDirective) {
+            requireRole(context, roleDirective.role);
+          } else {
+            requireAuth(context);
+          }
+          return originalResolve(source, args, context, info);
+        };
+      }
+      return fieldConfig;
+    },
+  });
+}
+```
+
+5. **Authorize at the data layer for defense in depth.** Even with resolver-level guards, validate ownership and access in data source methods. This prevents bypasses when resolvers are added or modified.
+
+```typescript
+class OrderDataSource {
+  async findById(id: string, currentUser: User): Promise<Order> {
+    const order = await this.db.orders.findUnique({ where: { id } });
+    if (!order) throw new NotFoundError('Order');
+    if (order.userId !== currentUser.id && !currentUser.roles.includes('ADMIN')) {
+      throw new ForbiddenError('Not authorized to view this order');
+    }
+    return order;
+  }
+}
+```
+
+6. **Filter fields based on permissions when needed.** Some fields should be visible only to certain roles (e.g., `User.email` visible to admins and the user themselves).
+
+```typescript
+const resolvers = {
+  User: {
+    email: (user, _args, { currentUser }) => {
+      if (currentUser?.id === user.id || currentUser?.roles.includes('ADMIN')) {
+        return user.email;
+      }
+      return null; // or throw, depending on your schema nullability
+    },
+  },
+};
+```
+
+7. **Protect against query depth and complexity attacks.** Authenticated users can still submit expensive queries. Use query depth limiting and cost analysis.
+
+```typescript
+import depthLimit from 'graphql-depth-limit';
+import { createComplexityLimitRule } from 'graphql-validation-complexity';
+
+const server = new ApolloServer({
+  typeDefs,
+  resolvers,
+  validationRules: [depthLimit(10), createComplexityLimitRule(1000)],
+});
+```
+
+8. **Return `UNAUTHENTICATED` for missing credentials and `FORBIDDEN` for insufficient permissions.** This distinction helps clients show the right UI (login prompt vs. access denied).
+
+## Details
+
+**Authentication vs. authorization:** Authentication answers "who are you?" (JWT verification, session lookup). Authorization answers "can you do this?" (role checks, ownership validation). Keep them separate — authenticate once in context, authorize per field/mutation.
+
+**Auth approaches compared:**
+
+- **Resolver-level guards:** Explicit, easy to test, but verbose in large schemas
+- **Schema directives:** Declarative, DRY, but requires schema transformation setup
+- **Middleware (graphql-shield):** Rule-based permission layer that sits between resolvers and execution. Good for complex permission matrices
+- **Data-layer auth:** Defense in depth — catches bypasses, but harder to return GraphQL-specific errors
+
+**graphql-shield example:**
+
+```typescript
+import { shield, rule, allow } from 'graphql-shield';
+
+const isAuthenticated = rule()((parent, args, { currentUser }) => currentUser !== null);
+const isAdmin = rule()((parent, args, { currentUser }) => currentUser?.roles.includes('ADMIN'));
+
+const permissions = shield({
+  Query: { '*': isAuthenticated, publicPosts: allow },
+  Mutation: { deleteUser: isAdmin },
+});
+```
+
+**Common mistakes:**
+
+- Checking auth in the parent query resolver but not in nested field resolvers (nested fields can be queried through different parents)
+- Returning different error shapes for auth failures (always use `GraphQLError` with standard codes)
+- Trusting client-side role claims without server-side verification
+- Not rate-limiting failed authentication attempts
+
+## Source
+
+https://www.apollographql.com/docs/apollo-server/security/authentication/
+
+## 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/codex/graphql-auth-patterns/skill.yaml

@@ -0,0 +1,42 @@
+name: graphql-auth-patterns
+version: '1.0.0'
+description: Implement authentication and authorization in GraphQL with directives, middleware, and field-level guards
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.graphql'
+  - '**/resolvers/**'
+  - '**/auth/**'
+  - '**/middleware/**'
+related_skills:
+  - graphql-resolver-pattern
+  - graphql-apollo-server
+  - graphql-schema-design
+stack_signals:
+  - graphql
+  - typescript
+  - apollo
+keywords:
+  - authentication
+  - authorization
+  - directives
+  - guards
+  - permissions
+  - jwt
+  - rbac
+metadata:
+  author: community
+  upstream: apollographql.com/docs/apollo-server/security/authentication
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/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/codex/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/codex/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/codex/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: []