@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/cursor/trpc-middleware-pattern/SKILL.md

@@ -0,0 +1,99 @@
+# tRPC: Middleware
+
+> Add cross-cutting logic (auth checks, logging, rate limiting) to procedures via t.middleware
+
+## When to Use
+
+- Enforcing authentication on a set of procedures without repeating the check in each handler
+- Enriching the context with derived data (user object from session ID) before the handler runs
+- Logging request/response for observability across all procedures
+- Adding rate limiting or permission checks that apply to procedure groups
+- Creating reusable procedure builders (`protectedProcedure`, `adminProcedure`)
+
+## Instructions
+
+1. Create middleware with `t.middleware(async ({ ctx, next }) => { ... })` — call `next({ ctx: { ...ctx, ...enriched } })` to pass enriched context to the handler.
+2. Attach middleware to a procedure with `.use(middleware)` — the middleware runs before the input validation and handler.
+3. Build typed procedure builders by chaining `.use()` and exporting the result: `export const protectedProcedure = t.procedure.use(isAuthed)`.
+4. Throw `new TRPCError({ code: 'UNAUTHORIZED' })` in middleware to reject the request — the error propagates to the client's `onError` handler.
+5. Access the enriched context type in the handler — TypeScript narrows the type based on what middleware adds to `ctx`.
+6. Use `.pipe()` to compose multiple middleware — each receives the context enriched by the previous middleware.
+7. Return `next()` at the end of middleware — forgetting this causes the procedure to never respond.
+
+```typescript
+// server/trpc.ts — middleware and procedure builders
+import { initTRPC, TRPCError } from '@trpc/server';
+import type { TRPCContext } from './context';
+
+const t = initTRPC.context<TRPCContext>().create();
+
+// Auth middleware — enriches ctx with session and user
+const isAuthed = t.middleware(async ({ ctx, next }) => {
+  if (!ctx.session?.user) {
+    throw new TRPCError({ code: 'UNAUTHORIZED', message: 'Not signed in' });
+  }
+  return next({
+    ctx: {
+      ...ctx,
+      // TypeScript now knows session and user are non-null in subsequent handlers
+      session: ctx.session,
+      user: ctx.session.user,
+    },
+  });
+});
+
+// Admin middleware — must be used after isAuthed (pipes)
+const isAdmin = t.middleware(async ({ ctx, next }) => {
+  // ctx.user is typed as defined by isAuthed — no null check needed
+  if (ctx.user.role !== 'admin') {
+    throw new TRPCError({ code: 'FORBIDDEN', message: 'Admin access required' });
+  }
+  return next({ ctx });
+});
+
+// Timing middleware — logs procedure duration
+const timingMiddleware = t.middleware(async ({ path, next }) => {
+  const start = Date.now();
+  const result = await next();
+  console.log(`[tRPC] ${path} took ${Date.now() - start}ms`);
+  return result;
+});
+
+export const publicProcedure = t.procedure.use(timingMiddleware);
+export const protectedProcedure = publicProcedure.use(isAuthed);
+export const adminProcedure = protectedProcedure.use(isAdmin);
+```
+
+## Details
+
+tRPC middleware is a functional chain: each middleware receives the current `ctx` and calls `next()` to pass control to the next middleware or the handler. The `ctx` passed to `next()` becomes the `ctx` available in subsequent middleware and the handler.
+
+**Context type narrowing:** When middleware adds properties to `ctx` (e.g., `user: NonNullable<Ctx['session']['user']>`), TypeScript updates the `ctx` type for everything downstream. This is why `protectedProcedure`'s handler can access `ctx.user` without null checks — the middleware has already asserted non-null.
+
+**Middleware composition:** `protectedProcedure.use(isAdmin)` creates `adminProcedure`. Middleware applied earlier in the chain runs first. `timingMiddleware.use(isAuthed).use(isAdmin)` runs timing, then auth, then admin check, then the handler.
+
+**`next()` return value:** Middleware can inspect the handler's return value by `const result = await next()` and then examine or transform `result.ok` / `result.data`. This pattern is useful for response logging and transforming output globally.
+
+**Procedure reuse pattern:** Instead of applying middleware individually to each procedure, create named procedure builders (`publicProcedure`, `protectedProcedure`, `adminProcedure`) and use them as the base for all procedures in a domain. This guarantees consistent middleware application.
+
+**Input access in middleware:** Middleware does not have access to the validated input by default. If middleware needs input values (e.g., for rate limiting by resource ID), use `experimental_caller` or restructure to check after input validation by placing middleware after `.input()`.
+
+## Source
+
+https://trpc.io/docs/server/middlewares
+
+## 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/cursor/trpc-middleware-pattern/skill.yaml

@@ -0,0 +1,41 @@
+name: trpc-middleware-pattern
+version: "1.0.0"
+description: tRPC middleware, t.middleware, context enrichment, and auth guards
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/trpc/**"
+  - "**/routers/**"
+  - "**/server/trpc.ts"
+related_skills:
+  - trpc-context-pattern
+  - trpc-router-composition
+  - next-auth-patterns
+  - next-middleware-pattern
+stack_signals:
+  - trpc
+  - typescript
+  - react
+keywords:
+  - tRPC-middleware
+  - t.middleware
+  - protectedProcedure
+  - auth-guard
+  - context-enrichment
+  - pipe
+metadata:
+  author: community
+  upstream: https://trpc.io/docs/server/middlewares
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/trpc-nextjs-integration/SKILL.md

@@ -0,0 +1,203 @@
+# tRPC Next.js Integration
+
+> Integrate tRPC with Next.js App Router using the fetch adapter, server-side callers, and React Server Components
+
+## When to Use
+
+- Setting up tRPC in a Next.js App Router project
+- Calling tRPC procedures from React Server Components (RSC) without an HTTP round-trip
+- Creating server-side callers for use in `generateStaticParams`, `getServerSideProps` equivalents, or route handlers
+- Sharing the same tRPC procedures between client components (via `useQuery`) and server components (via direct caller)
+
+## Instructions
+
+### 1. Create the Next.js API route handler
+
+```typescript
+// app/api/trpc/[trpc]/route.ts
+import { fetchRequestHandler } from '@trpc/server/adapters/fetch';
+import { appRouter } from '@/server/root';
+import { createTRPCContext } from '@/server/context';
+import { type NextRequest } from 'next/server';
+
+const handler = (req: NextRequest) =>
+  fetchRequestHandler({
+    endpoint: '/api/trpc',
+    req,
+    router: appRouter,
+    createContext: () => createTRPCContext({ req }),
+  });
+
+export { handler as GET, handler as POST };
+```
+
+### 2. Create the tRPC client for React Client Components
+
+```typescript
+// lib/trpc/client.tsx
+'use client';
+import { createTRPCReact } from '@trpc/react-query';
+import type { AppRouter } from '@/server/root';
+
+export const api = createTRPCReact<AppRouter>();
+```
+
+```typescript
+// lib/trpc/provider.tsx
+'use client';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { httpBatchLink } from '@trpc/client';
+import { useState } from 'react';
+import { api } from './client';
+import superjson from 'superjson';
+
+function getBaseUrl() {
+  if (typeof window !== 'undefined') return '';
+  if (process.env.VERCEL_URL) return `https://${process.env.VERCEL_URL}`;
+  return `http://localhost:${process.env.PORT ?? 3000}`;
+}
+
+export function TRPCProvider({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient());
+  const [trpcClient] = useState(() =>
+    api.createClient({
+      links: [
+        httpBatchLink({
+          url: `${getBaseUrl()}/api/trpc`,
+          transformer: superjson,
+        }),
+      ],
+    })
+  );
+
+  return (
+    <api.Provider client={trpcClient} queryClient={queryClient}>
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    </api.Provider>
+  );
+}
+```
+
+### 3. Create a server-side caller for React Server Components
+
+```typescript
+// lib/trpc/server.ts
+import { createCallerFactory } from '@/server/trpc';
+import { appRouter } from '@/server/root';
+import { createTRPCContext } from '@/server/context';
+import { cache } from 'react';
+import { headers } from 'next/headers';
+
+// cache() ensures one context per request (React's request-scoped cache)
+const createContext = cache(async () => {
+  const heads = new Headers(await headers());
+  heads.set('x-trpc-source', 'rsc');
+  return createTRPCContext({ req: { headers: heads } as Request });
+});
+
+const createCaller = createCallerFactory(appRouter);
+
+export const api = createCaller(createContext);
+```
+
+### 4. Call procedures from Server Components
+
+```typescript
+// app/posts/page.tsx — React Server Component (no 'use client')
+import { api } from '@/lib/trpc/server';
+
+export default async function PostsPage() {
+  // Direct procedure call — no HTTP round-trip, no useQuery needed
+  const posts = await api.post.list({ limit: 20 });
+
+  return (
+    <ul>
+      {posts.map((post) => (
+        <li key={post.id}>{post.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+### 5. Use the client API in Client Components
+
+```typescript
+// app/posts/NewPostForm.tsx
+'use client';
+import { api } from '@/lib/trpc/client';
+
+export function NewPostForm() {
+  const utils = api.useUtils();
+  const createPost = api.post.create.useMutation({
+    onSuccess: () => {
+      // Invalidate the list query to trigger a refetch
+      void utils.post.list.invalidate();
+    },
+  });
+
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault();
+      const form = new FormData(e.currentTarget);
+      createPost.mutate({
+        title: form.get('title') as string,
+        content: form.get('content') as string,
+      });
+    }}>
+      <input name="title" placeholder="Title" />
+      <textarea name="content" placeholder="Content" />
+      <button type="submit" disabled={createPost.isPending}>Create</button>
+    </form>
+  );
+}
+```
+
+### 6. Wrap the app with the provider
+
+```typescript
+// app/layout.tsx
+import { TRPCProvider } from '@/lib/trpc/provider';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <TRPCProvider>{children}</TRPCProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Details
+
+**Two separate `api` objects.** The server `api` (from `lib/trpc/server.ts`) is for Server Components — it calls procedures directly in-process. The client `api` (from `lib/trpc/client.tsx`) is for Client Components — it calls procedures over HTTP. Never import the server `api` in a Client Component (it would bundle server code into the client).
+
+**`cache()` for request-scoped context.** `React.cache()` memoizes the context creation per request in the React Server Component runtime. Without it, every `api.xxx()` call would create a fresh database connection. With it, all RSC procedure calls share one context (and one DB connection) per request.
+
+**`createCallerFactory` vs direct import.** `createCallerFactory(appRouter)` creates a factory for the server-side caller. This is the stable API — do not call `appRouter.createCaller()` directly (deprecated in tRPC v11).
+
+**Hydration and prefetching.** To pre-populate the TanStack Query cache on the server and hydrate it on the client (avoiding a loading flash), use `dehydrate`/`HydrationBoundary` from TanStack Query with tRPC's server API. This pattern is optional but eliminates the initial loading state.
+
+**`httpBatchLink` batches multiple queries.** When a Client Component calls multiple `useQuery` hooks, tRPC batches them into a single HTTP request automatically. This is the default behavior with `httpBatchLink`.
+
+## Source
+
+https://trpc.io/docs/client/nextjs
+
+## 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/cursor/trpc-nextjs-integration/skill.yaml

@@ -0,0 +1,43 @@
+name: trpc-nextjs-integration
+version: "1.0.0"
+description: App Router integration, createCaller, server-side caller, and RSC patterns
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/trpc/**"
+  - "**/routers/**"
+  - "**/server/trpc.ts"
+  - "**/app/api/trpc/**"
+related_skills:
+  - next-route-handlers
+  - next-server-components
+  - trpc-router-composition
+  - trpc-context-pattern
+stack_signals:
+  - trpc
+  - typescript
+  - react
+keywords:
+  - tRPC-next
+  - createCaller
+  - server-caller
+  - RSC
+  - App-Router
+  - fetch-adapter
+  - appRouter
+metadata:
+  author: community
+  upstream: https://trpc.io/docs/client/nextjs
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/trpc-react-query-integration/SKILL.md

@@ -0,0 +1,182 @@
+# tRPC React Query Integration
+
+> End-to-end type-safe data fetching with `api.xxx.useQuery`, `useMutation`, and cache invalidation via TanStack Query
+
+## When to Use
+
+- Fetching data from tRPC procedures in React client components
+- Running mutations and automatically invalidating related queries on success
+- Optimistically updating the UI before a mutation completes
+- Accessing the TanStack Query cache imperatively (prefetch, set data, invalidate)
+
+## Instructions
+
+### 1. Create the typed React hooks
+
+```typescript
+// lib/api.ts (or lib/trpc/client.tsx)
+import { createTRPCReact } from '@trpc/react-query';
+import type { AppRouter } from '@/server/root';
+
+export const api = createTRPCReact<AppRouter>();
+```
+
+All hooks (`useQuery`, `useMutation`, `useSubscription`) are available on `api.<router>.<procedure>`.
+
+### 2. Use useQuery for data fetching
+
+```typescript
+'use client';
+import { api } from '@/lib/api';
+
+function PostList() {
+  const { data, isLoading, error } = api.post.list.useQuery(
+    { limit: 20 },
+    {
+      staleTime: 60_000,           // Fresh for 60s — won't refetch on mount
+      refetchOnWindowFocus: false, // Disable auto-refetch on tab focus
+    }
+  );
+
+  if (isLoading) return <Skeleton />;
+  if (error) return <Error message={error.message} />;
+
+  return <ul>{data.map(post => <li key={post.id}>{post.title}</li>)}</ul>;
+}
+```
+
+### 3. Use useMutation for writes
+
+```typescript
+function CreatePostForm() {
+  const utils = api.useUtils();
+
+  const createPost = api.post.create.useMutation({
+    onSuccess: (newPost) => {
+      // Invalidate and refetch the post list
+      void utils.post.list.invalidate();
+    },
+    onError: (error) => {
+      toast.error(error.message);
+    },
+  });
+
+  return (
+    <form onSubmit={(e) => {
+      e.preventDefault();
+      const data = new FormData(e.currentTarget);
+      createPost.mutate({
+        title: data.get('title') as string,
+        content: data.get('content') as string,
+      });
+    }}>
+      <input name="title" />
+      <button type="submit" disabled={createPost.isPending}>
+        {createPost.isPending ? 'Creating...' : 'Create Post'}
+      </button>
+    </form>
+  );
+}
+```
+
+### 4. Optimistic updates
+
+```typescript
+const utils = api.useUtils();
+
+const likePost = api.post.like.useMutation({
+  onMutate: async ({ postId }) => {
+    // Cancel outgoing queries for this data
+    await utils.post.getById.cancel({ id: postId });
+
+    // Snapshot the current value
+    const previous = utils.post.getById.getData({ id: postId });
+
+    // Optimistically update the cache
+    utils.post.getById.setData({ id: postId }, (old) =>
+      old ? { ...old, likeCount: old.likeCount + 1 } : old
+    );
+
+    return { previous };
+  },
+  onError: (err, { postId }, context) => {
+    // Roll back on failure
+    if (context?.previous) {
+      utils.post.getById.setData({ id: postId }, context.previous);
+    }
+  },
+  onSettled: ({ postId }) => {
+    // Always refetch to sync server truth
+    void utils.post.getById.invalidate({ id: postId });
+  },
+});
+```
+
+### 5. Prefetch data for navigation
+
+```typescript
+// Prefetch on hover for instant page transitions
+function PostLink({ postId }: { postId: string }) {
+  const utils = api.useUtils();
+
+  return (
+    <a
+      href={`/posts/${postId}`}
+      onMouseEnter={() => {
+        void utils.post.getById.prefetch({ id: postId });
+      }}
+    >
+      View Post
+    </a>
+  );
+}
+```
+
+### 6. Infinite queries for pagination
+
+```typescript
+const { data, fetchNextPage, hasNextPage, isFetchingNextPage } =
+  api.post.listInfinite.useInfiniteQuery(
+    { limit: 20 },
+    {
+      getNextPageParam: (lastPage) => lastPage.nextCursor,
+      initialCursor: undefined,
+    }
+  );
+
+const allPosts = data?.pages.flatMap((page) => page.items) ?? [];
+```
+
+## Details
+
+**End-to-end type inference.** The `AppRouter` type propagates through `createTRPCReact<AppRouter>()` to every hook. `useQuery`'s `data` type is inferred from the procedure's return type. `useMutation`'s `variables` type is inferred from `.input()`. No manual type annotations required anywhere on the client.
+
+**`api.useUtils()` is the query client proxy.** It provides typed access to TanStack Query cache operations scoped to tRPC procedures: `utils.post.list.invalidate()`, `utils.post.list.setData()`, `utils.post.list.prefetch()`. These are type-safe wrappers over `queryClient.invalidateQueries`, `setQueryData`, etc.
+
+**Query key structure.** tRPC generates stable query keys from the procedure path and input. `api.post.getById.useQuery({ id: '1' })` and `api.post.getById.useQuery({ id: '2' })` have distinct cache entries. `utils.post.getById.invalidate()` (no argument) invalidates all entries for `getById`. `utils.post.getById.invalidate({ id: '1' })` invalidates only the specific entry.
+
+**`useMutation` vs `mutate` vs `mutateAsync`.** `mutate()` is fire-and-forget — errors are handled via `onError`. `mutateAsync()` returns a Promise — you can `await` it and handle errors with try/catch. Use `mutateAsync` in form submit handlers where you need to control flow after the mutation.
+
+**Error types.** `error` from `useQuery`/`useMutation` is a `TRPCClientError<AppRouter>`. Access `error.data?.code` for the tRPC error code, `error.data?.zodError` for field-level validation errors (if your server formats them), and `error.message` for the human-readable message.
+
+**Suspense mode.** Replace `useQuery` with `useSuspenseQuery` to use React Suspense for loading states. The component suspends while loading and renders only when data is available — `data` is always defined (never `undefined`).
+
+## Source
+
+https://trpc.io/docs/client/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/cursor/trpc-react-query-integration/skill.yaml

@@ -0,0 +1,43 @@
+name: trpc-react-query-integration
+version: "1.0.0"
+description: api.xxx.useQuery, useMutation, type inference end-to-end with TanStack Query
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - "**/trpc/**"
+  - "**/routers/**"
+  - "**/*trpc*.ts"
+  - "**/*trpc*.tsx"
+related_skills:
+  - tanstack-query-keys
+  - tanstack-mutation-patterns
+  - tanstack-query-invalidation
+  - trpc-router-composition
+stack_signals:
+  - trpc
+  - typescript
+  - react
+keywords:
+  - tRPC
+  - useQuery
+  - useMutation
+  - type-inference
+  - end-to-end-types
+  - createTRPCReact
+  - api-client
+metadata:
+  author: community
+  upstream: https://trpc.io/docs/client/react
+state:
+  persistent: false
+  files: []
+depends_on: []