ghcopilot-hub 1.0.0

package/hub/skills/tanstack-query/references/typescript.md

@@ -0,0 +1,176 @@
+# TypeScript Patterns for TanStack Query
+
+**Type-safe query and mutation patterns**
+
+> Alignment note: define `queryOptions` in the Application layer and reuse them in Presentation.
+
+---
+
+## 1. Basic Type Inference
+
+```tsx
+type Todo = {
+  id: number;
+  title: string;
+  completed: boolean;
+};
+
+const { data } = useQuery({
+  queryKey: ["todos"],
+  queryFn: async (): Promise<Todo[]> => {
+    const response = await fetch("/api/todos");
+    return response.json();
+  },
+});
+```
+
+---
+
+## 2. Generic Query Hook
+
+```tsx
+function useEntity<T>(endpoint: string, id: number) {
+  return useQuery({
+    queryKey: [endpoint, id],
+    queryFn: async (): Promise<T> => {
+      const response = await fetch(`/api/${endpoint}/${id}`);
+      return response.json();
+    },
+  });
+}
+```
+
+---
+
+## 3. queryOptions with Type Safety
+
+```tsx
+export const todosQueryOptions = queryOptions({
+  queryKey: ["todos"],
+  queryFn: async (): Promise<Todo[]> => {
+    const response = await fetch("/api/todos");
+    return response.json();
+  },
+  staleTime: 1000 * 60,
+});
+
+useQuery(todosQueryOptions);
+useSuspenseQuery(todosQueryOptions);
+queryClient.prefetchQuery(todosQueryOptions);
+```
+
+---
+
+## 4. Mutation with Types
+
+```tsx
+type CreateTodoInput = { title: string };
+
+type CreateTodoResponse = Todo;
+
+const { mutate } = useMutation<CreateTodoResponse, Error, CreateTodoInput, { previous?: Todo[] }>({
+  mutationFn: async (input) => {
+    const response = await fetch("/api/todos", {
+      method: "POST",
+      body: JSON.stringify(input),
+    });
+    return response.json();
+  },
+});
+```
+
+---
+
+## 5. Custom Error Types
+
+```tsx
+class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public code: string
+  ) {
+    super(message);
+  }
+}
+
+const { error } = useQuery<Todo[], ApiError>({
+  queryKey: ["todos"],
+  queryFn: async () => {
+    const response = await fetch("/api/todos");
+    if (!response.ok) {
+      throw new ApiError("Failed to fetch", response.status, "FETCH_ERROR");
+    }
+    return response.json();
+  },
+});
+```
+
+---
+
+## 6. Zod Schema Validation
+
+```tsx
+import { z } from "zod";
+
+const TodoSchema = z.object({
+  id: z.number(),
+  title: z.string(),
+  completed: z.boolean(),
+});
+
+type Todo = z.infer<typeof TodoSchema>;
+
+const { data } = useQuery({
+  queryKey: ["todos"],
+  queryFn: async () => {
+    const response = await fetch("/api/todos");
+    const json = await response.json();
+    return TodoSchema.array().parse(json);
+  },
+});
+```
+
+---
+
+## 7. Type-Safe Query Keys
+
+```tsx
+const queryKeys = {
+  todos: {
+    all: ["todos"] as const,
+    lists: () => [...queryKeys.todos.all, "list"] as const,
+    list: (filters: TodoFilters) => [...queryKeys.todos.lists(), filters] as const,
+    details: () => [...queryKeys.todos.all, "detail"] as const,
+    detail: (id: number) => [...queryKeys.todos.details(), id] as const,
+  },
+};
+
+useQuery({
+  queryKey: queryKeys.todos.detail(1),
+  queryFn: () => fetchTodo(1),
+});
+```
+
+---
+
+## 8. Strict Null Checks
+
+```tsx
+const { data } = useQuery({
+  queryKey: ["todo", id],
+  queryFn: () => fetchTodo(id),
+});
+
+const title = data?.title ?? "No title";
+```
+
+---
+
+## Best Practices
+
+✅ Always type `queryFn` return values
+✅ Use `as const` for query keys
+✅ Prefer `queryOptions` for reuse
+✅ Use Zod for runtime + compile-time validation
+✅ Keep strict null checks enabled

package/hub/skills/tanstack-router/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: tanstack-router
+description: >
+  TanStack Router patterns aligned with the project Clean Architecture and the tanstack skill. Trigger: When
+  implementing or refactoring routing, loaders, search params, router defaults, route-level error boundaries, and
+  recovery flows.
+license: Apache-2.0
+metadata:
+  author: jmgomezdev
+  version: "1.0"
+---
+
+## When to Use
+
+- Creating or updating TanStack Router routes, loaders, and router configuration.
+- Adding search param validation, preload strategy, or error/not-found handling.
+- Splitting route components with `.lazy.tsx` and `getRouteApi()`.
+- Using advanced routing behaviors like masks or custom search serialization.
+
+## Reference Router (Mandatory Loading)
+
+Loading protocol:
+
+1. Pick one routing scenario first.
+2. MANDATORY: read only the selected reference before implementation.
+3. Do NOT load all references by default.
+4. If blocked, load one extra reference only.
+
+| Scenario                                 | MANDATORY Reference                                                        | Do NOT Load (unless needed) |
+| ---------------------------------------- | -------------------------------------------------------------------------- | --------------------------- |
+| Loader flow and preload orchestration    | [references/loaders-and-preload.md](references/loaders-and-preload.md)     | `navigation.md`             |
+| Route-level boundary and recovery UX     | [references/errors-and-boundaries.md](references/errors-and-boundaries.md) | `code-splitting.md`         |
+| Search params parsing and defaults       | [references/search-params.md](references/search-params.md)                 | `private-routes.md`         |
+| Context wiring and typed root route      | [references/router-context.md](references/router-context.md)               | `navigation.md`             |
+| Private/public redirects and auth groups | [references/private-routes.md](references/private-routes.md)               | `search-params.md`          |
+| Lazy route modules and route API typing  | [references/code-splitting.md](references/code-splitting.md)               | `private-routes.md`         |
+| Navigation, links, masks                 | [references/navigation.md](references/navigation.md)                       | `router-context.md`         |
+
+## Critical Patterns
+
+- **Follow the tanstack skill** for render-as-you-fetch: Application owns `queryOptions`, Interface uses loaders,
+  Presentation consumes with `useSuspenseQuery`.
+- **Interface-only routing:** route files live under `src/interface/router/**` and never call repositories directly.
+- **Use typed router context:** create root with `createRootRouteWithContext` and inject `queryClient` (and auth if
+  needed).
+- **Loaders use `queryClient.ensureQueryData`**, never `prefetchQuery`, and never fetch directly in components.
+- **Always validate search params** with `validateSearch` and `zod` (defaults via `.catch`).
+- **Register the router type** once so `useNavigate`, `Link`, and hooks infer valid routes.
+- **Prefer `<Link>` over `useNavigate`** for normal navigation (accessibility + preloading).
+- **Use `from` / `Route.fullPath` / `getRouteApi()`** for strict type narrowing in components.
+- **Use parallel loaders** (`Promise.all`) to avoid waterfalls.
+- **Use `.lazy.tsx`** for heavy UI components; keep config in the main route file.
+- **Configure not-found handling** with `notFoundComponent` or `defaultNotFoundComponent`.
+- **Route read failures must bubble** to `errorComponent`; never swallow loader failures.
+- **Classify errors at route boundary**: not-found UX separate from generic server/infrastructure errors.
+- **Retry from route boundaries** with `router.invalidate()` (or equivalent route reset), not full reload.
+- **Preload intent by default** and set `defaultPreloadStaleTime: 0` when using TanStack Query.
+- **Private routes:** use pathless route groups with `beforeLoad` redirects and auth context. See
+  `references/private-routes.md`.
+
+## Code Examples
+
+### Loader + Query cache (minimal)
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+import { productQueries } from "@/application/product/product.queries";
+
+export const Route = createFileRoute("/products/$productId")({
+  loader: async ({ params, context: { queryClient } }) => {
+    await queryClient.ensureQueryData(productQueries.detail(params.productId));
+  },
+  errorComponent: ProductDetailErrorBoundary,
+  component: ProductDetailPage,
+});
+```
+
+### Search validation with Zod (minimal)
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { z } from "zod";
+
+const searchSchema = z.object({
+  page: z.number().min(1).catch(1),
+  sort: z.enum(["name", "price"]).catch("name"),
+});
+
+export const Route = createFileRoute("/products")({
+  validateSearch: (search) => searchSchema.parse(search),
+  component: ProductsPage,
+});
+```
+
+### Strict types in split components (minimal)
+
+```tsx
+import { getRouteApi } from "@tanstack/react-router";
+
+const route = getRouteApi("/products/$productId");
+
+export function ProductHeader() {
+  const { productId } = route.useParams();
+  return <h1>Product {productId}</h1>;
+}
+```
+
+## Commands
+
+```bash
+npm run lint
+npm run test
+npm run build
+```
+
+Use VS Code native search (`#tool:search`) for route boundary checks:
+
+- `query: loader:|errorComponent|notFoundComponent` (regex), path: `src/interface/router/routes`
+
+## Failure Modes and Fallbacks
+
+- Loader throws and UI stays blank: Ensure route defines `errorComponent` and retry path.
+- Not-found and server errors render the same UI: Split boundary handling into typed not-found and generic error
+  branches.
+- Navigation recovery uses hard refresh: Replace with router/query invalidation strategy.
+
+## Never Do This
+
+- Never catch loader errors only to return fake placeholder payloads.
+- Never implement route error handling solely inside page components.
+- Never use `prefetchQuery` for required route data in router flow.
+
+## Resources
+
+- Base skill: [../tanstack/SKILL.md](../tanstack/SKILL.md)
+- Base skill: [../tanstack-query/SKILL.md](../tanstack-query/SKILL.md)
+- Router context: [references/router-context.md](references/router-context.md)
+- Loaders and preload: [references/loaders-and-preload.md](references/loaders-and-preload.md)
+- Errors and boundaries: [references/errors-and-boundaries.md](references/errors-and-boundaries.md)
+- Search params: [references/search-params.md](references/search-params.md)
+- Navigation: [references/navigation.md](references/navigation.md)
+- Code splitting: [references/code-splitting.md](references/code-splitting.md)
+- TypeScript: [references/typescript.md](references/typescript.md)
+- Private routes: [references/private-routes.md](references/private-routes.md)

package/hub/skills/tanstack-router/references/code-splitting.md

@@ -0,0 +1,31 @@
+# Code splitting
+
+## Rules
+
+- Keep loader/validation in the base route.
+- Lazy-load UI with `createRoute().lazy`.
+- In lazy modules, use `getRouteApi` for typed hooks.
+
+## Minimal example
+
+```tsx
+export const detailRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/products/$productId",
+  loader: ({ context: { queryClient }, params }) =>
+    queryClient.ensureQueryData(productQueries.detail(params.productId)),
+}).lazy(() => import("./productDetail.lazy").then((m) => m.Route));
+```
+
+```tsx
+import { createLazyRoute, getRouteApi } from "@tanstack/react-router";
+
+const routeApi = getRouteApi("/products/$productId");
+
+export const Route = createLazyRoute("/products/$productId")({
+  component: () => {
+    const { productId } = routeApi.useParams();
+    return <ProductDetailPage productId={productId} />;
+  },
+});
+```

package/hub/skills/tanstack-router/references/errors-and-boundaries.md

@@ -0,0 +1,44 @@
+# Errors and boundaries
+
+Use this reference when implementing route-level error behavior for loader-driven pages.
+
+## Rules
+
+- Loader read failures should propagate to route `errorComponent`.
+- Keep not-found UI separate from generic server/network failures.
+- Retry should invalidate router/query state, not hard reload the page.
+- Do not mask loader failures by returning fake fallback payloads.
+
+## Minimal route boundary pattern
+
+```tsx
+import { createFileRoute, useRouter } from "@tanstack/react-router";
+
+import { productQueries } from "@/application/product/product.queries";
+
+const isNotFoundError = (error: unknown) => error instanceof Error && error.message.includes("404");
+
+function ProductDetailErrorBoundary({ error }: { error: unknown }) {
+  const router = useRouter();
+
+  if (isNotFoundError(error)) {
+    return <ProductNotFound />;
+  }
+
+  return <RouteErrorPage title="Unable to load product" onRetry={() => router.invalidate()} />;
+}
+
+export const Route = createFileRoute("/products/$productId")({
+  loader: async ({ params, context: { queryClient } }) => {
+    await queryClient.ensureQueryData(productQueries.detail(params.productId));
+  },
+  errorComponent: ProductDetailErrorBoundary,
+  component: ProductDetailPage,
+});
+```
+
+## Common pitfalls
+
+- Catching inside loader and returning synthetic data.
+- Rendering route errors inside page components instead of boundaries.
+- Using full page reload for retry.

package/hub/skills/tanstack-router/references/loaders-and-preload.md

@@ -0,0 +1,51 @@
+# Loaders and preload
+
+## Rules
+
+- Required data must be loaded in loaders with `ensureQueryData`.
+- Use `Promise.all` for parallel loading.
+- Use `defaultPreload: 'intent'` and `defaultPreloadStaleTime: 0` with TanStack Query.
+- Keep loader failures visible to route boundaries; do not return fake fallback data from loader catches.
+
+## Boundary hand-off
+
+When loader data is required for first render, pair loader prefetch with route `errorComponent`.
+
+```tsx
+export const detailRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/products/$productId",
+  loader: async ({ context: { queryClient }, params }) => {
+    await queryClient.ensureQueryData(productQueries.detail(params.productId));
+  },
+  errorComponent: ProductDetailErrorBoundary,
+  component: ProductDetailPage,
+});
+```
+
+Retry should invalidate router/query state (for example `router.invalidate()`), not hard refresh.
+
+## Minimal example
+
+```tsx
+export const detailRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/products/$productId",
+  loader: async ({ context: { queryClient }, params }) => {
+    await Promise.all([
+      queryClient.ensureQueryData(productQueries.detail(params.productId)),
+      queryClient.ensureQueryData(productQueries.related(params.productId)),
+    ]);
+  },
+  component: ProductDetailPage,
+});
+```
+
+```tsx
+export const router = createRouter({
+  routeTree,
+  context: { queryClient },
+  defaultPreload: "intent",
+  defaultPreloadStaleTime: 0,
+});
+```

package/hub/skills/tanstack-router/references/navigation.md

@@ -0,0 +1,24 @@
+# Navigation
+
+## Rules
+
+- Prefer `Link` for standard navigation.
+- Use `useNavigate` only for side effects.
+- Use route masks for modal URLs.
+
+## Minimal example
+
+```tsx
+import { Link, useNavigate } from "@tanstack/react-router";
+
+<Link to="/products/$productId" params={{ productId: product.id }} preload="intent">
+  View
+</Link>;
+
+const navigate = useNavigate();
+navigate({ to: "/products" });
+
+<Link to="/products/$productId" params={{ productId: product.id }} mask={{ to: "/products" }}>
+  Quick view
+</Link>;
+```

package/hub/skills/tanstack-router/references/private-routes.md

@@ -0,0 +1,169 @@
+# Private Routes
+
+This reference describes how to implement private routes with TanStack Router while respecting the project Clean Architecture.
+
+## Goals
+
+- Share auth state across the route tree via Router context.
+- Redirect early in `beforeLoad` for protected and public-only areas.
+- Route index decides where to land based on auth and role.
+- Layout routes group protected areas (admin, dashboard, etc.).
+- Auth changes trigger redirects by invalidating the router.
+
+## Architecture Rules
+
+- Route files live in `src/interface/router/**`.
+- Auth is owned by Application (query + hook), not by Interface or Presentation.
+- Presentation provides Router context (no direct repository calls in routes).
+- Redirects happen in `beforeLoad`, not inside page components.
+
+## Router Context and Provider
+
+Create a typed router context that includes `queryClient` and `auth`. Set `auth: undefined!` in router creation and pass the real value in the provider.
+
+```tsx
+import { QueryClient } from "@tanstack/react-query";
+import { createRootRouteWithContext, createRouter } from "@tanstack/react-router";
+
+type RouterContext = {
+  queryClient: QueryClient;
+  auth: AuthState | undefined;
+};
+
+export const rootRoute = createRootRouteWithContext<RouterContext>()({
+  component: AppLayout,
+});
+
+const queryClient = new QueryClient();
+
+export const router = createRouter({
+  routeTree,
+  context: { queryClient, auth: undefined! },
+  defaultPreload: "intent",
+  defaultPreloadStaleTime: 0,
+});
+```
+
+```tsx
+import { RouterProvider } from "@tanstack/react-router";
+
+import { useAuth } from "@/application/auth/hooks/useAuth";
+import { router } from "@/interface/router";
+
+export function AuthedRouterProvider() {
+  const auth = useAuth();
+
+  React.useEffect(() => {
+    router.invalidate();
+  }, [auth]);
+
+  return <RouterProvider router={router} context={{ auth }} />;
+}
+```
+
+## Route Groups and Redirects
+
+Use pathless route groups to separate authenticated and unauthenticated sections. Place these in `src/interface/router/routes/`.
+
+```
+routes/
+  _authenticated/
+    route.tsx
+    admin/
+      route.tsx
+  _unauthenticated/
+    route.tsx
+  index.tsx
+```
+
+### Protected group
+
+```tsx
+import { Outlet, createFileRoute, redirect } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/_authenticated")({
+  beforeLoad: ({ context: { auth } }) => {
+    if (!auth?.user) {
+      throw redirect({ to: "/login" });
+    }
+  },
+  component: RouteComponent,
+});
+
+function RouteComponent() {
+  return <Outlet />;
+}
+```
+
+### Public-only group
+
+```tsx
+import { Outlet, createFileRoute, redirect } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/_unauthenticated")({
+  beforeLoad: ({ context: { auth } }) => {
+    if (auth?.user) {
+      throw redirect({ to: "/admin" });
+    }
+  },
+  component: RouteComponent,
+});
+
+function RouteComponent() {
+  return <Outlet />;
+}
+```
+
+## Index Redirect
+
+Index route decides where to land based on auth and role.
+
+```tsx
+import { createFileRoute, redirect } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/")({
+  beforeLoad: ({ context: { auth } }) => {
+    if (!auth?.user) {
+      throw redirect({ to: "/login" });
+    }
+
+    if (auth.user.role === "admin") {
+      throw redirect({ to: "/admin" });
+    }
+
+    throw redirect({ to: "/products" });
+  },
+  component: PageLoader,
+});
+```
+
+## Layout Route for Admin
+
+Use a layout route to wrap all admin pages and redirect bare `/admin` to a default child.
+
+```tsx
+import { createFileRoute, redirect } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/_authenticated/admin")({
+  beforeLoad: ({ location }) => {
+    if (location.pathname === "/admin") {
+      throw redirect({ to: "/admin/profile" });
+    }
+  },
+  component: AdminDashboardLayout,
+});
+```
+
+## Auth Change Redirects
+
+Invalidate the router when auth changes so `beforeLoad` runs again. Also invalidate the auth query when login/logout happens.
+
+```tsx
+queryClient.invalidateQueries({ queryKey: ["auth"] });
+```
+
+## Common Pitfalls
+
+- Do not fetch auth directly in routes or pages.
+- Do not handle redirects inside page components.
+- Do not import DTOs or repositories in Presentation or Interface routes.

package/hub/skills/tanstack-router/references/router-context.md

@@ -0,0 +1,35 @@
+# Router context
+
+## Rules
+
+- Use `createRootRouteWithContext` to type router context.
+- Inject shared services via `createRouter` context.
+- Access `context.queryClient` inside loaders.
+- Avoid global imports inside route files.
+
+## Minimal example
+
+```tsx
+import type { QueryClient } from "@tanstack/react-query";
+import { createRootRouteWithContext, createRoute, createRouter } from "@tanstack/react-router";
+
+type RouterContext = { queryClient: QueryClient };
+
+export const rootRoute = createRootRouteWithContext<RouterContext>()({
+  component: RootLayout,
+});
+
+export const listRoute = createRoute({
+  getParentRoute: () => rootRoute,
+  path: "/",
+  loader: async ({ context: { queryClient } }) => {
+    await queryClient.ensureQueryData(productQueries.list());
+  },
+  component: ProductListPage,
+});
+
+export const router = createRouter({
+  routeTree: rootRoute.addChildren([listRoute]),
+  context: { queryClient },
+});
+```