npm - @jgamaraalv/ts-dev-kit - Versions diffs - 2.2.0 → 3.0.0 - Mend

@jgamaraalv/ts-dev-kit 2.2.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/.claude-plugin/marketplace.json +3 -3
package/.claude-plugin/plugin.json +2 -2
package/CHANGELOG.md +52 -0
package/README.md +106 -50
package/package.json +2 -2
package/skills/codebase-adapter/SKILL.md +237 -0
package/skills/codebase-adapter/template.md +25 -0
package/skills/conventional-commits/SKILL.md +12 -0
package/skills/core-web-vitals/SKILL.md +102 -0
package/skills/core-web-vitals/references/cls.md +154 -0
package/skills/core-web-vitals/references/inp.md +140 -0
package/skills/core-web-vitals/references/lcp.md +89 -0
package/skills/core-web-vitals/references/tools.md +112 -0
package/skills/core-web-vitals/scripts/visualize.py +222 -0
package/skills/debug/SKILL.md +10 -27
package/skills/debug/template.md +23 -0
package/skills/{task → execute-task}/SKILL.md +78 -50
package/skills/generate-prd/SKILL.md +56 -0
package/skills/generate-prd/template.md +69 -0
package/skills/generate-task/SKILL.md +136 -0
package/skills/generate-task/template.md +71 -0
package/skills/owasp-security-review/SKILL.md +1 -10
package/skills/owasp-security-review/template.md +6 -0
package/skills/tanstack-query/SKILL.md +348 -0
package/skills/tanstack-query/references/advanced-patterns.md +376 -0
package/skills/tanstack-query/references/api-reference.md +297 -0
package/skills/tanstack-query/references/ssr-nextjs.md +272 -0
package/skills/tanstack-query/references/testing.md +175 -0
package/skills/ui-ux-guidelines/SKILL.md +1 -17
package/skills/ui-ux-guidelines/template.md +15 -0
/package/skills/{task → execute-task}/references/agent-dispatch.md +0 -0
/package/skills/{task → execute-task}/references/verification-protocol.md +0 -0
/package/skills/{task/references/output-templates.md → execute-task/template.md} +0 -0

package/skills/tanstack-query/references/ssr-nextjs.md ADDED Viewed

@@ -0,0 +1,272 @@
+# TanStack Query v5 — SSR & Next.js
+## Table of Contents
+- [Core Concept](#core-concept)
+- [Next.js Pages Router](#nextjs-pages-router)
+- [Next.js App Router](#nextjs-app-router)
+- [Streaming](#streaming)
+- [Critical Gotchas](#critical-gotchas)
+## Core Concept
+Server rendering with TanStack Query follows three steps:
+1. **Prefetch** data on the server with `queryClient.prefetchQuery()`
+2. **Dehydrate** the cache with `dehydrate(queryClient)`
+3. **Hydrate** on the client with `<HydrationBoundary state={dehydratedState}>`
+## Next.js Pages Router
+### getStaticProps / getServerSideProps
+```tsx
+import { dehydrate, QueryClient } from '@tanstack/react-query'
+export async function getStaticProps() {
+  const queryClient = new QueryClient()
+  await queryClient.prefetchQuery({
+    queryKey: ['posts'],
+    queryFn: getPosts,
+  })
+  return {
+    props: {
+      dehydratedState: dehydrate(queryClient),
+    },
+  }
+}
+```
+### _app.tsx setup
+```tsx
+import { HydrationBoundary, QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { useState } from 'react'
+export default function MyApp({ Component, pageProps }) {
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: 60 * 1000 },
+    },
+  }))
+  return (
+    <QueryClientProvider client={queryClient}>
+      <HydrationBoundary state={pageProps.dehydratedState}>
+        <Component {...pageProps} />
+      </HydrationBoundary>
+    </QueryClientProvider>
+  )
+}
+```
+### Page component — uses useQuery normally
+```tsx
+export default function PostsPage() {
+  const { data } = useQuery({ queryKey: ['posts'], queryFn: getPosts })
+  // data is immediately available from the hydrated cache
+}
+```
+## Next.js App Router
+### Provider setup (app/providers.tsx)
+```tsx
+'use client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { useState } from 'react'
+function makeQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000, // must be > 0 for SSR
+      },
+    },
+  })
+}
+let browserQueryClient: QueryClient | undefined
+function getQueryClient() {
+  if (typeof window === 'undefined') {
+    // Server: always make a new query client
+    return makeQueryClient()
+  }
+  // Browser: reuse singleton
+  if (!browserQueryClient) browserQueryClient = makeQueryClient()
+  return browserQueryClient
+}
+export default function Providers({ children }: { children: React.ReactNode }) {
+  const queryClient = getQueryClient()
+  return (
+    <QueryClientProvider client={queryClient}>
+      {children}
+    </QueryClientProvider>
+  )
+}
+```
+**Why not `useState`?** If there is no Suspense boundary between the provider and suspending code, React throws away state on initial suspend. The singleton pattern avoids losing the client.
+### Root layout (app/layout.tsx)
+```tsx
+import Providers from './providers'
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+### Prefetch in Server Components
+```tsx
+// app/posts/page.tsx (Server Component)
+import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
+import Posts from './posts' // Client Component
+export default async function PostsPage() {
+  const queryClient = new QueryClient()
+  await queryClient.prefetchQuery({
+    queryKey: ['posts'],
+    queryFn: getPosts,
+  })
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <Posts />
+    </HydrationBoundary>
+  )
+}
+```
+```tsx
+// app/posts/posts.tsx (Client Component)
+'use client'
+import { useQuery } from '@tanstack/react-query'
+export default function Posts() {
+  const { data } = useQuery({ queryKey: ['posts'], queryFn: getPosts })
+  // data is available immediately from hydration
+}
+```
+### Nested prefetching
+Multiple `<HydrationBoundary>` with separate queryClients at different levels is fine. Deeply nested Server Components can each prefetch their own data.
+### Shared queryClient with React.cache
+```tsx
+import { cache } from 'react'
+const getQueryClient = cache(() => new QueryClient())
+// Any Server Component in the same request:
+export default async function Page() {
+  const queryClient = getQueryClient()
+  await queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: getPosts })
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <Posts />
+    </HydrationBoundary>
+  )
+}
+```
+Downside: each `dehydrate()` serializes the entire cache, including previously serialized queries.
+## Streaming
+Available since v5.40.0. Pending queries can be dehydrated and streamed without `await`.
+### Setup — configure dehydration to include pending queries
+```tsx
+function makeQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { staleTime: 60 * 1000 },
+      dehydrate: {
+        shouldDehydrateQuery: (query) =>
+          defaultShouldDehydrateQuery(query) || query.state.status === 'pending',
+      },
+    },
+  })
+}
+```
+### Stream prefetch (no await)
+```tsx
+// app/posts/page.tsx
+export default function PostsPage() {
+  const queryClient = new QueryClient()
+  // No await — query starts but doesn't block rendering
+  queryClient.prefetchQuery({ queryKey: ['posts'], queryFn: getPosts })
+  return (
+    <HydrationBoundary state={dehydrate(queryClient)}>
+      <Posts />
+    </HydrationBoundary>
+  )
+}
+```
+On the client, use `useSuspenseQuery` to consume the streamed promise:
+```tsx
+'use client'
+export default function Posts() {
+  const { data } = useSuspenseQuery({ queryKey: ['posts'], queryFn: getPosts })
+  // Suspends until streamed data arrives, then renders
+}
+```
+### Non-JSON serialization
+For data with Dates, Maps, etc., configure custom serialization:
+```tsx
+defaultOptions: {
+  dehydrate: { serializeData: superjson.serialize },
+  hydrate: { deserializeData: superjson.deserialize },
+}
+```
+## Critical Gotchas
+1. **Never create QueryClient at module scope** — it leaks data between requests/users:
+   ```tsx
+   // WRONG
+   const queryClient = new QueryClient()
+   export default function App() { ... }
+   // CORRECT
+   const [queryClient] = useState(() => new QueryClient())
+   ```
+2. **Set `staleTime > 0` for SSR** — with default `staleTime: 0`, the client immediately refetches on mount, negating the prefetch.
+3. **Don't use `fetchQuery` in Server Components to render data** — if both a Server Component and a Client Component use the same data, they desync when the client revalidates. Use `prefetchQuery` (which only populates the cache) and let client components own the data rendering.
+4. **`hydrate` only overwrites if incoming data is newer** — checked by timestamp.
+5. **`Error` objects and `undefined` are not JSON-serializable** — handle serialization manually if dehydrating errors. By default, errors are redacted (replaced with `null`).
+6. **Data ownership rule:** The component that renders the data should own it. Server Components prefetch; Client Components consume via `useQuery`/`useSuspenseQuery`.

package/skills/tanstack-query/references/testing.md ADDED Viewed

@@ -0,0 +1,175 @@
+# TanStack Query v5 — Testing
+## Setup
+Use `@testing-library/react` (v14+) directly — no need for `@testing-library/react-hooks`.
+### Create a wrapper with isolated QueryClient
+```tsx
+import { renderHook, waitFor } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+function createTestQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        retry: false,  // CRITICAL: disable retries in tests
+      },
+    },
+  })
+}
+function createWrapper() {
+  const queryClient = createTestQueryClient()
+  return function Wrapper({ children }: { children: ReactNode }) {
+    return (
+      <QueryClientProvider client={queryClient}>
+        {children}
+      </QueryClientProvider>
+    )
+  }
+}
+```
+## Testing a Custom Hook
+```tsx
+// hooks/useTodos.ts
+export function useTodos() {
+  return useQuery({ queryKey: ['todos'], queryFn: fetchTodos })
+}
+// hooks/useTodos.test.ts
+import { renderHook, waitFor } from '@testing-library/react'
+import { useTodos } from './useTodos'
+test('fetches todos', async () => {
+  const { result } = renderHook(() => useTodos(), {
+    wrapper: createWrapper(),
+  })
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+  expect(result.current.data).toEqual([{ id: 1, title: 'Test' }])
+})
+```
+## Network Mocking
+### With nock
+```tsx
+import nock from 'nock'
+test('fetches data from API', async () => {
+  nock('http://example.com')
+    .get('/api/todos')
+    .reply(200, [{ id: 1, title: 'Test' }])
+  const { result } = renderHook(() => useTodos(), {
+    wrapper: createWrapper(),
+  })
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+  expect(result.current.data).toEqual([{ id: 1, title: 'Test' }])
+})
+```
+### With msw (recommended)
+```tsx
+import { setupServer } from 'msw/node'
+import { http, HttpResponse } from 'msw'
+const server = setupServer(
+  http.get('/api/todos', () =>
+    HttpResponse.json([{ id: 1, title: 'Test' }])
+  ),
+)
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+```
+## Testing Infinite Queries
+```tsx
+import nock from 'nock'
+test('fetches multiple pages', async () => {
+  const expectation = nock('http://example.com')
+    .persist()  // .persist() for multiple requests
+    .query(true)
+    .get('/api/items')
+    .reply(200, (uri) => {
+      const url = new URL(`http://example.com${uri}`)
+      const page = url.searchParams.get('page') ?? '1'
+      return { items: [`item-${page}`], nextPage: Number(page) < 3 ? Number(page) + 1 : null }
+    })
+  const { result } = renderHook(() => useInfiniteItems(), {
+    wrapper: createWrapper(),
+  })
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+  expect(result.current.data.pages).toHaveLength(1)
+  // Fetch next page
+  result.current.fetchNextPage()
+  await waitFor(() => expect(result.current.data.pages).toHaveLength(2))
+})
+```
+## Testing Mutations
+```tsx
+test('creates a todo and invalidates list', async () => {
+  const queryClient = createTestQueryClient()
+  const wrapper = ({ children }: { children: ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  )
+  // Pre-populate cache
+  queryClient.setQueryData(['todos'], [{ id: 1, title: 'Existing' }])
+  const { result } = renderHook(() => useCreateTodo(), { wrapper })
+  result.current.mutate({ title: 'New Todo' })
+  await waitFor(() => expect(result.current.isSuccess).toBe(true))
+})
+```
+## Key Gotchas
+1. **Always disable retries** — Default 3 retries with exponential backoff causes test timeouts:
+   ```tsx
+   new QueryClient({ defaultOptions: { queries: { retry: false } } })
+   ```
+   Note: explicit `retry` on individual queries overrides this default.
+2. **Always use `waitFor`** — Query state updates are async. Never assert synchronously after `renderHook`.
+3. **Isolate QueryClient per test** — Create a new `QueryClient` for each test to prevent cross-test contamination. Do not share a client across tests.
+4. **Jest "did not exit" warning** — If you get this, set `gcTime: Infinity` on the test QueryClient to prevent garbage collection timers from hanging:
+   ```tsx
+   new QueryClient({
+     defaultOptions: {
+       queries: { retry: false, gcTime: Infinity },
+     },
+   })
+   ```
+5. **Component testing** — For testing components (not just hooks), render the component inside the wrapper:
+   ```tsx
+   import { render, screen, waitFor } from '@testing-library/react'
+   test('renders todo list', async () => {
+     render(<TodoList />, { wrapper: createWrapper() })
+     await waitFor(() => expect(screen.getByText('Test Todo')).toBeInTheDocument())
+   })
+   ```

package/skills/ui-ux-guidelines/SKILL.md CHANGED Viewed

@@ -76,23 +76,7 @@ Dispatch hub for UI/UX rules. Load the relevant reference file for full details.
 Group findings by file. Use `file:line` format (VS Code clickable). Be terse -- state issue and location. Skip explanation unless fix is non-obvious.
-```text
-## src/Button.tsx
-src/Button.tsx:42 - icon button missing aria-label
-src/Button.tsx:18 - input lacks label
-src/Button.tsx:55 - animation missing prefers-reduced-motion
-src/Button.tsx:67 - transition: all -> list properties explicitly
-## src/Modal.tsx
-src/Modal.tsx:12 - missing overscroll-behavior: contain
-src/Modal.tsx:34 - "..." -> "..."
-## src/Card.tsx
-pass
-```
+See [template.md](template.md) for the expected output format.
 ---

package/skills/ui-ux-guidelines/template.md ADDED Viewed

@@ -0,0 +1,15 @@
+## src/Button.tsx
+src/Button.tsx:42 - icon button missing aria-label
+src/Button.tsx:18 - input lacks label
+src/Button.tsx:55 - animation missing prefers-reduced-motion
+src/Button.tsx:67 - transition: all -> list properties explicitly
+## src/Modal.tsx
+src/Modal.tsx:12 - missing overscroll-behavior: contain
+src/Modal.tsx:34 - "Close" -> "Close dialog"
+## src/Card.tsx
+pass

/package/skills/{task → execute-task}/references/agent-dispatch.md RENAMED Viewed

File without changes

/package/skills/{task → execute-task}/references/verification-protocol.md RENAMED Viewed

File without changes

/package/skills/{task/references/output-templates.md → execute-task/template.md} RENAMED Viewed

File without changes