@harness-engineering/cli 1.23.2 → 1.24.0

package/dist/agents/skills/codex/redux-rtk-optimistic/SKILL.md

@@ -0,0 +1,117 @@
+# RTK Query Optimistic Updates
+
+> Apply optimistic and pessimistic cache updates with onQueryStarted for instant UI feedback with automatic rollback
+
+## When to Use
+
+- Toggling a like/favorite and wanting instant UI response
+- Reordering items in a list via drag-and-drop
+- Editing inline fields where waiting for the server feels sluggish
+- Any mutation where the expected server response is predictable
+
+## Instructions
+
+1. Use `onQueryStarted` in the mutation endpoint to perform cache updates before or after the server responds.
+2. For **optimistic updates**: call `dispatch(api.util.updateQueryData(...))` immediately inside `onQueryStarted`, before awaiting the result. Save the return value — it contains an `undo` function.
+3. Wrap the `await queryFulfilled` in try/catch. On failure, call `patchResult.undo()` to revert the optimistic change.
+4. For **pessimistic updates**: `await queryFulfilled` first, then update the cache with the server's response.
+5. Always match the exact cache key arguments when calling `updateQueryData` — a mismatch silently does nothing.
+6. Prefer optimistic updates for idempotent operations (toggles, edits). Prefer pessimistic updates when the server assigns critical data (IDs, computed fields).
+
+```typescript
+// Optimistic update — toggle a todo's completed status
+toggleTodo: builder.mutation<Todo, { id: string; completed: boolean }>({
+  query: ({ id, completed }) => ({
+    url: `/todos/${id}`,
+    method: 'PATCH',
+    body: { completed },
+  }),
+  async onQueryStarted({ id, completed }, { dispatch, queryFulfilled }) {
+    // Optimistically update the cache immediately
+    const patchResult = dispatch(
+      api.util.updateQueryData('getTodos', undefined, (draft) => {
+        const todo = draft.find((t) => t.id === id);
+        if (todo) todo.completed = completed;
+      })
+    );
+    try {
+      await queryFulfilled;
+    } catch {
+      // Revert on failure
+      patchResult.undo();
+    }
+  },
+}),
+```
+
+```typescript
+// Pessimistic update — server assigns the ID
+createTodo: builder.mutation<Todo, { title: string }>({
+  query: (body) => ({ url: '/todos', method: 'POST', body }),
+  async onQueryStarted(_, { dispatch, queryFulfilled }) {
+    try {
+      const { data: newTodo } = await queryFulfilled;
+      // Update cache with server response
+      dispatch(
+        api.util.updateQueryData('getTodos', undefined, (draft) => {
+          draft.push(newTodo);
+        })
+      );
+    } catch {
+      // No cache to revert — the mutation failed before we touched it
+    }
+  },
+}),
+```
+
+## Details
+
+**updateQueryData arguments:** `updateQueryData(endpointName, queryArg, updateFn)`. The `queryArg` must exactly match what was passed to the query hook. If the query was called with `useGetTodosQuery(undefined)`, pass `undefined`. If called with `useGetTodosQuery({ filter: 'active' })`, pass `{ filter: 'active' }`.
+
+**Combining with invalidation:** You can use optimistic updates AND `invalidatesTags` together. The optimistic update gives instant feedback, and the invalidation ensures the cache is eventually consistent with the server.
+
+**Multiple cache entries:** If the same data appears in multiple queries (a list query and a detail query), update both:
+
+```typescript
+async onQueryStarted({ id, title }, { dispatch, queryFulfilled }) {
+  const patchList = dispatch(api.util.updateQueryData('getPosts', undefined, (draft) => {
+    const post = draft.find((p) => p.id === id);
+    if (post) post.title = title;
+  }));
+  const patchDetail = dispatch(api.util.updateQueryData('getPost', id, (draft) => {
+    draft.title = title;
+  }));
+  try {
+    await queryFulfilled;
+  } catch {
+    patchList.undo();
+    patchDetail.undo();
+  }
+},
+```
+
+**Anti-patterns:**
+
+- Forgetting to `undo()` on failure — leaves the UI in a stale state
+- Mismatched query args — the update silently does nothing
+- Optimistic updates for operations with unpredictable server behavior (payments, inventory)
+
+## Source
+
+https://redux-toolkit.js.org/rtk-query/usage/manual-cache-updates
+
+## 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/redux-rtk-optimistic/skill.yaml

@@ -0,0 +1,39 @@
+name: redux-rtk-optimistic
+version: '1.0.0'
+description: Implement optimistic updates and pessimistic updates with RTK Query cache
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/api.ts'
+  - '**/api/**'
+  - '**/services/**'
+related_skills:
+  - redux-rtk-query-endpoints
+  - redux-rtk-query-setup
+  - redux-entity-adapter
+stack_signals:
+  - redux
+  - react
+  - typescript
+keywords:
+  - optimistic-update
+  - onQueryStarted
+  - cache-update
+  - pessimistic-update
+  - undo
+metadata:
+  author: community
+  upstream: 'redux-toolkit/docs/rtk-query/optimistic-updates'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/redux-rtk-query-endpoints/SKILL.md

@@ -0,0 +1,131 @@
+# RTK Query Endpoints
+
+> Define query and mutation endpoints with cache tag invalidation, response transformation, and auto-generated hooks
+
+## When to Use
+
+- Adding new API endpoints to an existing RTK Query service
+- Implementing CRUD operations with automatic cache invalidation
+- Transforming API responses before they reach components
+- Setting up pagination, polling, or conditional fetching
+
+## Instructions
+
+1. Use `builder.query` for read operations (GET) and `builder.mutation` for write operations (POST/PUT/DELETE).
+2. Provide generic type arguments: `builder.query<ReturnType, ArgType>`. Use `void` when there is no argument.
+3. Use `providesTags` on queries to declare what cache entries they populate. Use both list-level and item-level tags.
+4. Use `invalidatesTags` on mutations to declare what cache entries to refetch after the mutation succeeds.
+5. Use `transformResponse` to reshape API responses before caching — extract nested data, normalize structures.
+6. Use `injectEndpoints` from feature modules to keep endpoints co-located with their feature code.
+7. Export the auto-generated hooks. Queries produce `useXQuery` and `useLazyXQuery`; mutations produce `useXMutation`.
+
+```typescript
+// features/posts/posts.api.ts
+import { api } from '../../services/api';
+
+interface Post {
+  id: string;
+  title: string;
+  body: string;
+  authorId: string;
+}
+
+const postsApi = api.injectEndpoints({
+  endpoints: (builder) => ({
+    getPosts: builder.query<Post[], { page: number }>({
+      query: ({ page }) => `/posts?page=${page}`,
+      providesTags: (result) =>
+        result
+          ? [
+              ...result.map(({ id }) => ({ type: 'Post' as const, id })),
+              { type: 'Post', id: 'LIST' },
+            ]
+          : [{ type: 'Post', id: 'LIST' }],
+    }),
+
+    getPost: builder.query<Post, string>({
+      query: (id) => `/posts/${id}`,
+      providesTags: (result, error, id) => [{ type: 'Post', id }],
+    }),
+
+    createPost: builder.mutation<Post, Omit<Post, 'id'>>({
+      query: (body) => ({ url: '/posts', method: 'POST', body }),
+      invalidatesTags: [{ type: 'Post', id: 'LIST' }],
+    }),
+
+    updatePost: builder.mutation<Post, Pick<Post, 'id'> & Partial<Post>>({
+      query: ({ id, ...patch }) => ({ url: `/posts/${id}`, method: 'PATCH', body: patch }),
+      invalidatesTags: (result, error, { id }) => [{ type: 'Post', id }],
+    }),
+
+    deletePost: builder.mutation<void, string>({
+      query: (id) => ({ url: `/posts/${id}`, method: 'DELETE' }),
+      invalidatesTags: (result, error, id) => [
+        { type: 'Post', id },
+        { type: 'Post', id: 'LIST' },
+      ],
+    }),
+  }),
+});
+
+export const {
+  useGetPostsQuery,
+  useGetPostQuery,
+  useCreatePostMutation,
+  useUpdatePostMutation,
+  useDeletePostMutation,
+} = postsApi;
+```
+
+## Details
+
+**Tag strategy:** Use a `'LIST'` sentinel ID for collection queries. Individual item queries use the actual ID. Mutations that add/remove items invalidate `'LIST'` to refetch collections. Mutations that edit items invalidate only that item's tag.
+
+**transformResponse:** Reshape before caching:
+
+```typescript
+getUsers: builder.query<User[], void>({
+  query: () => '/users',
+  transformResponse: (response: { data: User[]; meta: unknown }) => response.data,
+}),
+```
+
+**Polling and refetching:**
+
+```typescript
+// In component
+const { data } = useGetPostsQuery({ page: 1 }, { pollingInterval: 30000 });
+
+// Refetch on window focus — enabled globally via setupListeners(store.dispatch)
+```
+
+**Pagination pattern:** RTK Query caches each argument combination separately. For `page: 1` and `page: 2`, two cache entries exist. Use `serializeQueryArgs` + `merge` + `forceRefetch` for infinite scroll:
+
+```typescript
+getPosts: builder.query<Post[], number>({
+  query: (page) => `/posts?page=${page}`,
+  serializeQueryArgs: ({ endpointName }) => endpointName,
+  merge: (currentCache, newItems) => { currentCache.push(...newItems); },
+  forceRefetch: ({ currentArg, previousArg }) => currentArg !== previousArg,
+}),
+```
+
+## Source
+
+https://redux-toolkit.js.org/rtk-query/usage/queries
+
+## 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/redux-rtk-query-endpoints/skill.yaml

@@ -0,0 +1,40 @@
+name: redux-rtk-query-endpoints
+version: '1.0.0'
+description: Define query and mutation endpoints with cache tags and transformations
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/api.ts'
+  - '**/api/**'
+  - '**/services/**'
+related_skills:
+  - redux-rtk-query-setup
+  - redux-rtk-optimistic
+  - redux-typescript-patterns
+stack_signals:
+  - redux
+  - react
+  - typescript
+keywords:
+  - endpoints
+  - query
+  - mutation
+  - providesTags
+  - invalidatesTags
+  - transformResponse
+metadata:
+  author: community
+  upstream: 'redux-toolkit/docs/rtk-query/endpoints'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/redux-rtk-query-setup/SKILL.md

@@ -0,0 +1,117 @@
+# RTK Query Setup
+
+> Configure RTK Query with createApi and fetchBaseQuery for automatic caching, deduplication, and loading state management
+
+## When to Use
+
+- Adding data fetching to a Redux Toolkit application
+- Replacing hand-written thunks + loading/error state with a declarative API layer
+- Needing automatic request deduplication, caching, and cache invalidation
+- Building CRUD interfaces with REST or GraphQL backends
+
+## Instructions
+
+1. Create one API service per backend base URL. Place it in `services/api.ts` or `api/baseApi.ts`.
+2. Use `fetchBaseQuery` as the base query — it wraps `fetch` with sensible defaults and automatic header handling.
+3. Set `baseUrl` to the API root. Use `prepareHeaders` to inject auth tokens.
+4. Define `tagTypes` upfront for all cacheable entity types — these drive automatic invalidation.
+5. Start with an empty `endpoints` builder and inject endpoints from feature slices using `injectEndpoints`.
+6. Add the API's reducer to the store under `[api.reducerPath]` and add `api.middleware` to the middleware chain.
+7. Export auto-generated hooks from the API definition.
+
+```typescript
+// services/api.ts
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
+
+export const api = createApi({
+  reducerPath: 'api',
+  baseQuery: fetchBaseQuery({
+    baseUrl: '/api/v1',
+    prepareHeaders: (headers, { getState }) => {
+      const token = (getState() as RootState).auth.token;
+      if (token) headers.set('Authorization', `Bearer ${token}`);
+      return headers;
+    },
+  }),
+  tagTypes: ['User', 'Post', 'Comment'],
+  endpoints: () => ({}), // Injected by feature modules
+});
+```
+
+```typescript
+// store/index.ts
+import { configureStore } from '@reduxjs/toolkit';
+import { api } from '../services/api';
+
+export const store = configureStore({
+  reducer: {
+    [api.reducerPath]: api.reducer,
+    // ...other slices
+  },
+  middleware: (getDefaultMiddleware) => getDefaultMiddleware().concat(api.middleware),
+});
+```
+
+## Details
+
+**Why one API per base URL:** RTK Query normalizes cache keys per API instance. Multiple APIs hitting the same backend fragment the cache and break invalidation. Split APIs only for genuinely different backends.
+
+**fetchBaseQuery vs custom baseQuery:** `fetchBaseQuery` handles JSON serialization, error normalization, and timeout. For custom needs (Axios, retry logic, reauthentication), wrap it:
+
+```typescript
+const baseQueryWithReauth = async (args, api, extraOptions) => {
+  let result = await fetchBaseQuery({ baseUrl: '/api' })(args, api, extraOptions);
+  if (result.error?.status === 401) {
+    const refreshResult = await fetchBaseQuery({ baseUrl: '/api' })(
+      { url: '/auth/refresh', method: 'POST' },
+      api,
+      extraOptions
+    );
+    if (refreshResult.data) {
+      result = await fetchBaseQuery({ baseUrl: '/api' })(args, api, extraOptions);
+    }
+  }
+  return result;
+};
+```
+
+**Endpoint injection pattern:** Keeps the base API slim and lets features own their endpoints:
+
+```typescript
+// features/users/users.api.ts
+import { api } from '../../services/api';
+
+const usersApi = api.injectEndpoints({
+  endpoints: (builder) => ({
+    getUsers: builder.query({ query: () => '/users', providesTags: ['User'] }),
+  }),
+});
+
+export const { useGetUsersQuery } = usersApi;
+```
+
+**Common mistakes:**
+
+- Forgetting to add `api.middleware` (breaks polling, cache lifetime, and refetchOnFocus)
+- Using a string literal for `reducerPath` that does not match the store key
+- Creating multiple `createApi` instances for the same backend
+
+## Source
+
+https://redux-toolkit.js.org/rtk-query/overview
+
+## 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/redux-rtk-query-setup/skill.yaml

@@ -0,0 +1,39 @@
+name: redux-rtk-query-setup
+version: '1.0.0'
+description: Configure RTK Query API service with createApi and fetchBaseQuery
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/api.ts'
+  - '**/api/**'
+  - '**/services/**'
+related_skills:
+  - redux-rtk-query-endpoints
+  - redux-store-setup
+  - redux-rtk-optimistic
+stack_signals:
+  - redux
+  - react
+  - typescript
+keywords:
+  - createApi
+  - fetchBaseQuery
+  - rtk-query
+  - api-service
+  - cache
+metadata:
+  author: community
+  upstream: 'redux-toolkit/docs/rtk-query'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/redux-selectors-pattern/SKILL.md

@@ -0,0 +1,100 @@
+# Redux Selectors Pattern
+
+> Derive and memoize computed state with createSelector to avoid redundant calculations and unnecessary re-renders
+
+## When to Use
+
+- Computing derived data from Redux state (filtered lists, totals, lookups)
+- Preventing re-renders caused by creating new array/object references on every selector call
+- Composing complex selectors from simpler building blocks
+- Parameterizing selectors (e.g., select items by category)
+
+## Instructions
+
+1. Co-locate simple selectors with the slice that owns the state. Export them from the slice file.
+2. Use `createSelector` from `@reduxjs/toolkit` (re-exported from Reselect) for any computation that produces derived data.
+3. Input selectors should be simple property accessors — no computation. Only the result function should do work.
+4. Compose selectors by passing other selectors as inputs. Never reach into `state.someSlice.nested.field` from outside the slice boundary.
+5. For parameterized selectors, create a factory function that returns a new selector per parameter value.
+6. Keep the selector return type stable — returning a new array/object reference defeats memoization.
+
+```typescript
+// features/todos/todos.selectors.ts
+import { createSelector } from '@reduxjs/toolkit';
+import { RootState } from '../../store';
+
+// Simple selectors (no memoization needed)
+const selectTodosState = (state: RootState) => state.todos;
+export const selectAllTodos = (state: RootState) => state.todos.items;
+export const selectFilter = (state: RootState) => state.todos.filter;
+
+// Memoized derived selector
+export const selectFilteredTodos = createSelector(
+  [selectAllTodos, selectFilter],
+  (todos, filter) => {
+    switch (filter) {
+      case 'active':
+        return todos.filter((t) => !t.completed);
+      case 'completed':
+        return todos.filter((t) => t.completed);
+      default:
+        return todos;
+    }
+  }
+);
+
+// Composed selector
+export const selectTodoStats = createSelector([selectAllTodos], (todos) => ({
+  total: todos.length,
+  completed: todos.filter((t) => t.completed).length,
+  active: todos.filter((t) => !t.completed).length,
+}));
+
+// Parameterized selector factory
+export const makeSelectTodoById = (id: string) =>
+  createSelector([selectAllTodos], (todos) => todos.find((t) => t.id === id));
+```
+
+## Details
+
+**How memoization works:** `createSelector` caches the last result. If all input selectors return the same references as last time, the result function is skipped and the cached result is returned. This is reference equality, not deep equality.
+
+**Common memoization mistakes:**
+
+- Inline `createSelector` inside a component — creates a new selector instance on every render, defeating memoization. Move selectors outside components or use `useMemo`.
+- Input selectors that do computation — the result function is skipped only when inputs are referentially equal. If an input selector creates a new object, memoization never works.
+- Returning `items.filter(...)` from a simple selector (not `createSelector`) — creates a new array every time, causing re-renders.
+
+**Per-component memoization:** When multiple component instances need the same parameterized selector with different args, use a factory with `useMemo`:
+
+```typescript
+function TodoItem({ id }: { id: string }) {
+  const selectTodo = useMemo(() => makeSelectTodoById(id), [id]);
+  const todo = useAppSelector(selectTodo);
+  // Each TodoItem has its own memoized selector
+}
+```
+
+**Reselect 5.0+ (RTK 2.0+):** Supports `createSelector` with custom equality checks and `weakMapMemoize` for multi-argument caching without factories.
+
+**Testing selectors:** Test them as pure functions — pass in a mock `RootState` and assert the output. They are the easiest Redux code to test.
+
+## Source
+
+https://redux-toolkit.js.org/api/createSelector
+
+## 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/redux-selectors-pattern/skill.yaml

@@ -0,0 +1,39 @@
+name: redux-selectors-pattern
+version: '1.0.0'
+description: Derive and memoize state with createSelector for efficient re-renders
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.slice.ts'
+  - '**/selectors/**'
+  - '**/slices/**'
+related_skills:
+  - redux-slice-pattern
+  - redux-entity-adapter
+  - redux-typescript-patterns
+stack_signals:
+  - redux
+  - react
+  - typescript
+keywords:
+  - createSelector
+  - reselect
+  - memoization
+  - derived-state
+  - selector
+metadata:
+  author: community
+  upstream: 'reselect/docs'
+state:
+  persistent: false
+  files: []
+depends_on: []