@gallopsystems/agent-skills 1.0.0

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: nuxt-nitro-api
+description: Build type-safe Nuxt 3 applications with Nitro API patterns. Covers validation, fetch patterns, auth, SSR, composables, background tasks, and real-time features.
+---
+
+# Nuxt 3 / Nitro API Patterns
+
+This skill provides patterns for building type-safe Nuxt 3 applications with Nitro backends.
+
+## When to Use This Skill
+
+Use this skill when:
+- Working in a Nuxt 3 project with TypeScript
+- Building API endpoints with Nitro
+- Implementing authentication with nuxt-auth-utils
+- Handling SSR + client-side state
+- Creating background tasks or real-time features
+
+## Reference Files
+
+For detailed patterns, see these topic-focused reference files:
+
+- [validation.md](./validation.md) - Zod validation with h3, Standard Schema, error handling
+- [fetch-patterns.md](./fetch-patterns.md) - useFetch vs $fetch vs useAsyncData
+- [auth-patterns.md](./auth-patterns.md) - nuxt-auth-utils, OAuth, WebAuthn, middleware
+- [page-structure.md](./page-structure.md) - Keep pages thin, components do the work
+- [composables-utils.md](./composables-utils.md) - When to use composables vs utils
+- [ssr-client.md](./ssr-client.md) - SSR + localStorage, hydration, VueUse
+- [deep-linking.md](./deep-linking.md) - URL params sync with filters and useFetch
+- [nitro-tasks.md](./nitro-tasks.md) - Background jobs, scheduled tasks, job queues
+- [sse.md](./sse.md) - Server-Sent Events for real-time streaming
+- [server-services.md](./server-services.md) - Third-party service integration patterns
+
+## Example Files
+
+Working examples from a Nuxt project:
+
+- [validation-endpoint.ts](./examples/validation-endpoint.ts) - API endpoint with Zod validation
+- [auth-middleware.ts](./examples/auth-middleware.ts) - Server auth middleware
+- [auth-utils.ts](./examples/auth-utils.ts) - Reusable auth helpers
+- [deep-link-page.vue](./examples/deep-link-page.vue) - URL params sync with filters
+- [sse-endpoint.ts](./examples/sse-endpoint.ts) - SSE streaming endpoint
+- [service-util.ts](./examples/service-util.ts) - Server-side service pattern
+
+## Core Principles
+
+1. **Let Nitro infer types** - Never add manual type params to `$fetch<Type>()` or `useFetch<Type>()`
+2. **Use h3 validation** - `getValidatedQuery()`, `readValidatedBody()` with Zod schemas
+3. **Composables for context, utils for pure functions** - Composables access Nuxt context, utils are pure
+4. **SSR-safe code** - Guard browser APIs with `import.meta.client` or `onMounted`
+5. **Keep pages thin** - Pages = layout + route params + components. Components own data fetching and logic.
+
+## Auto-Imports Quick Reference
+
+### Server-side (`/server` directory)
+
+All h3 utilities auto-imported:
+- `defineEventHandler`, `createError`, `getQuery`, `getValidatedQuery`
+- `readBody`, `readValidatedBody`, `getRouterParams`, `getValidatedRouterParams`
+- `getCookie`, `setCookie`, `deleteCookie`, `getHeader`, `setHeader`
+
+From nuxt-auth-utils:
+- `getUserSession`, `setUserSession`, `clearUserSession`, `requireUserSession`
+- `hashPassword`, `verifyPassword`
+- `defineOAuth*EventHandler` (Google, GitHub, etc.)
+
+**Need to import:** `z` from "zod", `fromZodError` from "zod-validation-error"
+
+### Client-side
+
+All auto-imported:
+- Vue: `ref`, `computed`, `watch`, `onMounted`, etc.
+- VueUse: `refDebounced`, `useLocalStorage`, `useUrlSearchParams`, etc.
+- Nuxt: `useFetch`, `useAsyncData`, `useRoute`, `useRouter`, `useState`, `navigateTo`
+
+### Shared (`/shared` directory - Nuxt 3.14+)
+
+Code auto-imported on both client AND server. Use for:
+- Types and interfaces
+- Pure utility functions
+- Constants
+
+## Quick Patterns
+
+### Validation (h3 v2+ with Standard Schema)
+
+```typescript
+// Pass Zod schema directly (h3 v2+)
+const query = await getValidatedQuery(event, z.object({
+  search: z.string().optional(),
+  page: z.coerce.number().default(1),
+}));
+
+const body = await readValidatedBody(event, z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+}));
+```
+
+### $fetch Type Inference
+
+```typescript
+// Template literals preserve type inference (fixed late 2024)
+const userId = "123";  // Literal type "123"
+const result = await $fetch(`/api/users/${userId}`);
+// result is typed from the handler's return type
+
+// NEVER do this - defeats type inference
+const result = await $fetch<User>("/api/users/123");  // WRONG
+```
+
+### useFetch for Page Data
+
+```typescript
+// Basic - types inferred from Nitro
+const { data, status, refresh } = await useFetch("/api/users");
+
+// Reactive query params - auto-refetch on change
+const search = ref("");
+const debouncedSearch = refDebounced(search, 300);  // Auto-imported
+const { data } = await useFetch("/api/users", {
+  query: computed(() => ({
+    ...(debouncedSearch.value ? { search: debouncedSearch.value } : {}),
+  })),
+});
+
+// Dynamic URL with getter
+const userId = ref("123");
+const { data } = await useFetch(() => `/api/users/${userId.value}`);
+
+// New options (Nuxt 3.14+)
+const { data } = await useFetch("/api/data", {
+  retry: 3,          // Retry on failure
+  retryDelay: 1000,  // Wait between retries
+  dedupe: "cancel",  // Cancel previous request
+  delay: 300,        // Debounce the request
+});
+```
+
+### $fetch for Event Handlers
+
+```typescript
+// ONLY use $fetch in event handlers (onClick, onSubmit)
+const handleSubmit = async () => {
+  const result = await $fetch("/api/users", {
+    method: "POST",
+    body: { name: "Test" },
+  });
+};
+```
+
+### Auth Check in API
+
+```typescript
+// In server/utils/auth.ts
+export async function getAuthenticatedUser(event: H3Event) {
+  const session = await getUserSession(event);
+  if (!session?.user) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  return session.user;
+}
+
+// In API handler
+export default defineEventHandler(async (event) => {
+  const user = await getAuthenticatedUser(event);
+  // user is typed and guaranteed to exist
+});
+```
+
+### SSR-Safe localStorage
+
+```typescript
+// Option 1: import.meta.client guard
+watch(preference, (value) => {
+  if (import.meta.client) {
+    localStorage.setItem("pref", value);
+  }
+});
+
+// Option 2: onMounted
+onMounted(() => {
+  const saved = localStorage.getItem("pref");
+  if (saved) preference.value = saved;
+});
+
+// Option 3: VueUse (SSR-safe)
+const theme = useLocalStorage("theme", "light");
+```
+
+### Composable vs Util Decision
+
+```
+Needs Nuxt/Vue context (useRuntimeConfig, useRoute, refs)?
+├─ YES → COMPOSABLE in /composables/use*.ts
+└─ NO → UTIL in /utils/*.ts (client) or /server/utils/*.ts (server)
+```
+
+## Key Gotchas
+
+1. **Don't use `$fetch` at top level** - Causes double-fetch (SSR + client). Use `useFetch`.
+2. **Debounce search inputs** - Use `refDebounced` to avoid excessive API calls.
+3. **Reset pagination on filter change** - Or users see empty page 5 with new filters.
+4. **Guard browser APIs** - Use `import.meta.client`, `onMounted`, or `<ClientOnly>`.
+5. **Nitro tasks are single-instance** - Can't run same task twice concurrently. Use DB job queue.
+6. **useRouteQuery needs Nuxt composables** - Pass `route` and `router` explicitly.
+7. **Input types aren't auto-generated** - Export Zod schemas for client use.
+8. **Cookie size limit is 4096 bytes** - Store only essential session data.
+9. **Ambiguous routes need type assertion** - See below.
+10. **Never use generic type params with useFetch/$fetch** - See below.
+
+### Ambiguous Route Type Inference
+
+Nuxt generates types in `.nuxt/types/nitro-routes.d.ts` with an `InternalApi` object keyed by route paths. When routes overlap, Nuxt can't infer types from template literals:
+
+```typescript
+// Routes: GET /api/projects and GET /api/projects/:id
+// If route.params.id is "", the path matches BOTH routes
+const { data } = await useFetch(`/api/projects/${route.params.id}`);
+// data type: unknown (ambiguous)
+
+// Fix: Assert the specific route pattern
+const { data } = await useFetch(`/api/projects/${route.params.id}` as '/api/projects/:id');
+// data type: correctly inferred from /api/projects/:id handler
+```
+
+### Extracting Types from useFetch (Never Use Generic Params)
+
+Never pass type parameters to `useFetch` or `$fetch`:
+
+```typescript
+// WRONG - Lies to type checker, breaks when endpoint changes
+const { data } = await useFetch<Project[]>('/api/projects');
+
+// RIGHT - Let Nuxt infer from the actual endpoint
+const { data: projects } = await useFetch('/api/projects');
+```
+
+To use the inferred type elsewhere in your component:
+
+```typescript
+const { data: projects } = await useFetch('/api/projects');
+
+// Get the full ref type (Ref<Project[] | null>)
+type ProjectsRef = typeof projects;
+
+// Get a single item type from an array response
+type Project = NonNullable<typeof projects.value>[number];
+
+// Use in functions/computeds
+function formatProject(project: Project) {
+  return `${project.name} - ${project.status}`;
+}
+
+const activeProjects = computed(() =>
+  projects.value?.filter(p => p.status === 'active') ?? []
+);
+```
+
+This ensures your frontend types stay in sync with your API - if the endpoint return type changes, TypeScript will catch mismatches.

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/auth-patterns.md

@@ -0,0 +1,228 @@
+# Auth Patterns (nuxt-auth-utils)
+
+> **Examples:** [auth-utils.ts](./examples/auth-utils.ts), [auth-middleware.ts](./examples/auth-middleware.ts)
+
+nuxt-auth-utils supports 40+ OAuth providers and includes WebAuthn (passkey) support.
+
+## Server-side Functions (auto-imported)
+
+| Function | Purpose |
+|----------|---------|
+| `getUserSession(event)` | Get session (null if not logged in) |
+| `setUserSession(event, data)` | Create/update session (merges) |
+| `replaceUserSession(event, data)` | Replace entire session (no merge) |
+| `clearUserSession(event)` | Clear session (logout) |
+| `requireUserSession(event)` | Get session or throw 401 |
+
+### Password Utilities
+
+| Function | Purpose |
+|----------|---------|
+| `hashPassword(password)` | Hash with scrypt |
+| `verifyPassword(hash, password)` | Verify password |
+| `passwordNeedsRehash(hash)` | Check if rehash needed |
+
+## Client-side Composable
+
+```typescript
+const {
+  ready,         // Computed<boolean> - session loaded?
+  loggedIn,      // Computed<boolean> - is logged in?
+  user,          // Computed<User | null> - user data
+  session,       // Ref<Session> - full session
+  fetch,         // () => Promise<void> - refresh
+  clear,         // () => Promise<void> - logout
+  openInPopup,   // (url: string) => void - OAuth popup
+} = useUserSession();
+```
+
+## OAuth Handler Pattern
+
+```typescript
+// server/api/auth/google.get.ts
+export default defineOAuthGoogleEventHandler({
+  config: {
+    clientId: config.oauth.google.clientId,
+    clientSecret: config.oauth.google.clientSecret,
+  },
+  async onSuccess(event, { user, tokens }) {
+    const dbUser = await findOrCreateUser(user.email, user);
+
+    await setUserSession(event, {
+      user: {
+        id: dbUser.id,
+        email: dbUser.email,
+        name: dbUser.name,
+        role: dbUser.role,
+      },
+    });
+
+    return sendRedirect(event, dbUser.role === "admin" ? "/dashboard" : "/home");
+  },
+  onError(event, error) {
+    console.error("OAuth error:", error);
+    return sendRedirect(event, "/login?error=oauth");
+  },
+});
+```
+
+Client trigger:
+```typescript
+const { openInPopup } = useUserSession();
+const loginWithGoogle = () => openInPopup("/api/auth/google");
+```
+
+## WebAuthn (Passkeys)
+
+```typescript
+// Server: Register credential
+export default defineWebAuthnRegisterEventHandler({
+  async onSuccess(event, { credential, user }) {
+    await db.insertInto("webauthn_credentials").values({
+      user_id: user.id,
+      credential_id: credential.id,
+      public_key: credential.publicKey,
+    }).execute();
+  },
+});
+
+// Server: Authenticate
+export default defineWebAuthnAuthenticateEventHandler({
+  async getCredential(event, credentialId) {
+    return await db.selectFrom("webauthn_credentials")
+      .where("credential_id", "=", credentialId)
+      .executeTakeFirst();
+  },
+  async onSuccess(event, { credential, user }) {
+    await setUserSession(event, { user });
+  },
+});
+```
+
+```typescript
+// Client
+const { register, authenticate } = useWebAuthn();
+await register({ userName: user.email });
+await authenticate();
+```
+
+## Server Middleware
+
+```typescript
+// server/middleware/auth.ts
+export default defineEventHandler(async (event) => {
+  // Skip auth routes
+  if (event.path.startsWith("/api/auth")) return;
+
+  if (event.path.startsWith("/api")) {
+    const session = await getUserSession(event);
+    if (!session?.user) {
+      throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+    }
+
+    // Role-based restrictions
+    if (event.path.startsWith("/api/admin") && session.user.role !== "admin") {
+      throw createError({ statusCode: 403, statusMessage: "Forbidden" });
+    }
+  }
+});
+```
+
+## Client Middleware
+
+```typescript
+// middleware/auth.global.ts
+export default defineNuxtRouteMiddleware((to) => {
+  const { loggedIn, user } = useUserSession();
+  const publicRoutes = ["/login", "/signup"];
+
+  if (!loggedIn.value && !publicRoutes.includes(to.path)) {
+    return navigateTo("/login");
+  }
+
+  if (loggedIn.value && to.path === "/login") {
+    return navigateTo("/");
+  }
+});
+```
+
+Named middleware:
+```typescript
+// middleware/admin.ts
+export default defineNuxtRouteMiddleware(() => {
+  const { loggedIn, user } = useUserSession();
+  if (!loggedIn.value || user.value?.role !== "admin") {
+    return navigateTo("/");
+  }
+});
+
+// pages/admin/dashboard.vue
+definePageMeta({ middleware: "admin" });
+```
+
+## Reusable Auth Helpers
+
+```typescript
+// server/utils/auth.ts
+export async function getAuthenticatedUser(event: H3Event) {
+  const session = await getUserSession(event);
+  if (!session?.user) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  return session.user;
+}
+
+export async function requireRole(event: H3Event, roles: string[]) {
+  const user = await getAuthenticatedUser(event);
+  if (!roles.includes(user.role)) {
+    throw createError({ statusCode: 403, statusMessage: "Forbidden" });
+  }
+  return user;
+}
+
+export async function requireAdmin(event: H3Event) {
+  return requireRole(event, ["admin", "superadmin"]);
+}
+```
+
+## Type Extension
+
+```typescript
+// types/auth.d.ts
+declare module "#auth-utils" {
+  interface User {
+    id: number;
+    email: string;
+    name: string;
+    role: "admin" | "user";
+  }
+
+  interface UserSession {
+    loggedInAt: string;
+  }
+
+  interface SecureSessionData {
+    internalToken?: string;  // Server-only
+  }
+}
+```
+
+## Configuration
+
+```bash
+# Required (32+ chars, auto-generated in dev)
+NUXT_SESSION_PASSWORD=your-super-secret-password-at-least-32-chars
+
+# OAuth (per-provider)
+NUXT_OAUTH_GOOGLE_CLIENT_ID=...
+NUXT_OAUTH_GOOGLE_CLIENT_SECRET=...
+```
+
+## Key Gotchas
+
+1. **Skip auth routes in middleware** - `/api/auth/*` and `/api/_auth/*`
+2. **Use `openInPopup` for OAuth** - Better UX than redirect
+3. **Cookie size limit is 4096 bytes** - Store only essential data
+4. **setUserSession merges** - Use `replaceUserSession` to replace
+5. **requireUserSession throws** - Use getUserSession for null
+6. **Cannot use with `nuxt generate`** - Requires running server

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/composables-utils.md

@@ -0,0 +1,174 @@
+# Composables vs Utils
+
+## Quick Decision Tree
+
+```
+Needs Nuxt/Vue context (useRuntimeConfig, useRoute, refs, toast)?
+├─ YES → COMPOSABLE in /composables/use*.ts
+│
+└─ NO
+   └─ Server-side logic (DB, file system, auth)?
+      ├─ YES → SERVER UTILS in /server/utils/
+      │
+      └─ NO (Pure data transformation)
+         └─ CLIENT UTILS in /utils/
+```
+
+## Composables (`/composables/use*.ts`)
+
+**When to use:**
+- Accesses Nuxt/Vue context: `useRuntimeConfig()`, `useRoute()`, `navigateTo()`
+- Uses Vue reactivity: `ref()`, `computed()`, `watch()` (optional!)
+- Accesses global services: `useToast()`, `useUserSession()`
+- Named with `use` prefix (required for auto-import)
+
+> **Note:** A composable does NOT need reactivity. If it accesses any Nuxt composable, it's a composable.
+
+```typescript
+// composables/useFormState.ts
+export const useFormState = (initialData: FormData) => {
+  const data = ref(initialData);
+  const isDirty = computed(() =>
+    JSON.stringify(data.value) !== JSON.stringify(initialData)
+  );
+  const errors = ref<Record<string, string>>({});
+  const toast = useToast();
+
+  watch(data, (newValue) => {
+    const result = schema.safeParse(newValue);
+    errors.value = result.success ? {} : formatErrors(result.error);
+  }, { deep: true });
+
+  const save = async () => {
+    try {
+      await $fetch("/api/save", { method: "POST", body: data.value });
+      toast.add({ severity: "success", summary: "Saved!" });
+    } catch (e) {
+      toast.add({ severity: "error", summary: "Failed" });
+    }
+  };
+
+  return { data, isDirty, errors, save };
+};
+```
+
+```typescript
+// composables/usePermissions.ts
+export const usePermissions = () => {
+  const { user } = useUserSession();
+
+  const hasRole = (role: string) => user.value?.role === role;
+  const isAdmin = () => hasRole("admin") || hasRole("superadmin");
+
+  const can = (action: string, resource: string) => {
+    if (!user.value) return false;
+    if (isAdmin()) return true;
+    // User-specific permissions
+    return false;
+  };
+
+  return { hasRole, isAdmin, can };
+};
+```
+
+## Client Utils (`/utils/*.ts`)
+
+**When to use:**
+- Pure functions, no side effects
+- No Vue/Nuxt dependencies
+- Data transformations, formatting, parsing
+- NO `use` prefix
+
+```typescript
+// utils/formatting.ts
+export const formatDate = (date: string) => {
+  return new Date(date).toLocaleDateString("en-US", {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  });
+};
+
+export const formatCurrency = (amount: number) => {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+  }).format(amount);
+};
+
+export const generateColor = (id: number) => {
+  const colors = ["#3B82F6", "#EF4444", "#10B981"];
+  return colors[id % colors.length];
+};
+```
+
+## Server Utils (`/server/utils/*.ts`)
+
+**When to use:**
+- Server-side only logic
+- Database access
+- Authentication helpers
+- External APIs, file system
+- Auto-imported in `/server` directory
+
+```typescript
+// server/utils/db.ts
+import { Kysely, PostgresDialect } from "kysely";
+import pg from "pg";
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+export const db = new Kysely({ dialect: new PostgresDialect({ pool }) });
+
+export function useDatabase() {
+  return db;
+}
+```
+
+```typescript
+// server/utils/auth.ts
+export async function getAuthenticatedUser(event: H3Event) {
+  const session = await getUserSession(event);
+  if (!session?.user) {
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
+  }
+  return session.user;
+}
+```
+
+## Shared Utils (`/shared/utils/` - Nuxt 3.14+)
+
+**When to use:**
+- Code used on BOTH client and server
+- Types, constants, pure functions
+- NO browser APIs, NO server-only code
+
+```typescript
+// shared/utils/format.ts
+export function formatCurrency(amount: number) {
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+  }).format(amount);
+}
+
+// Can be used in both:
+// - /server/api/invoice.get.ts
+// - /pages/invoice.vue
+```
+
+## Summary Table
+
+| Location | Naming | Vue APIs | Auto-imported | Use Case |
+|----------|--------|----------|---------------|----------|
+| `/composables/` | `use*` | Yes | Yes (client) | Reactive state, global services |
+| `/utils/` | Any | No | Yes (client) | Pure functions, formatting |
+| `/server/utils/` | Any | No | Yes (server) | DB, auth, server logic |
+| `/shared/utils/` | Any | No | Yes (both) | Isomorphic utilities |
+
+## Key Gotchas
+
+1. **Composables must start with `use`** - Required for auto-import
+2. **Don't use Vue APIs in utils** - Keeps them testable and portable
+3. **Server utils can't use Vue** - Different runtime
+4. **Auto-import scoping** - `/utils` is client-only, `/server/utils` is server-only
+5. **Composables call order matters** - Call at top of `<script setup>`, not in callbacks