@gallopsystems/agent-skills 1.0.0

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

@@ -0,0 +1,221 @@
+# Server-Sent Events (SSE)
+
+> **Example:** [sse-endpoint.ts](./examples/sse-endpoint.ts)
+
+Real-time streaming without WebSockets. Good for long-running operations, AI streaming, job progress.
+
+## Server-Side (Nitro)
+
+```typescript
+// server/api/stream/[id].get.ts
+export default defineEventHandler(async (event) => {
+  const { id } = getRouterParams(event);
+
+  // Create the event stream
+  const eventStream = createEventStream(event);
+
+  let done = false;
+
+  // Handle client disconnect
+  eventStream.onClosed(async () => {
+    console.log("Client disconnected");
+    done = true;
+    await eventStream.close();
+  });
+
+  // Async loop to push events
+  (async () => {
+    while (!done) {
+      const data = await getNextChunk(id);
+
+      if (data) {
+        await eventStream.push(JSON.stringify(data));
+
+        if (data.type === "done" || data.type === "error") {
+          done = true;
+        }
+      } else {
+        await new Promise((r) => setTimeout(r, 1000));
+      }
+    }
+
+    await eventStream.close();
+  })();
+
+  return eventStream.send();
+});
+```
+
+### Heartbeat Pattern
+
+Keep connections alive:
+
+```typescript
+const heartbeatInterval = setInterval(async () => {
+  await eventStream.push(JSON.stringify({ type: "heartbeat" }));
+}, 30000);
+
+eventStream.onClosed(() => {
+  clearInterval(heartbeatInterval);
+});
+```
+
+## Client-Side Option 1: VueUse (Recommended)
+
+```typescript
+import { useEventSource } from "@vueuse/core";
+
+const { status, data, error, close } = useEventSource(
+  `/api/stream/${sessionId}`,
+  [],  // Event names (empty = default "message")
+  {
+    autoReconnect: {
+      retries: 3,
+      delay: 1000,
+      onFailed() {
+        console.error("Failed to reconnect");
+      },
+    },
+  }
+);
+
+watch(data, (newData) => {
+  if (newData) {
+    const parsed = JSON.parse(newData);
+    // Handle the event...
+  }
+});
+
+onUnmounted(close);
+```
+
+## Client-Side Option 2: Custom Composable
+
+For more control:
+
+```typescript
+// composables/useSSE.ts
+export function useSSE() {
+  const eventSource = ref<EventSource | null>(null);
+  const data = ref<any>(null);
+  const error = ref<string | null>(null);
+  const status = ref<"connecting" | "connected" | "closed">("connecting");
+
+  const connect = (url: string) => {
+    stop();
+
+    eventSource.value = new EventSource(url);
+
+    eventSource.value.onopen = () => {
+      status.value = "connected";
+    };
+
+    eventSource.value.onmessage = (event) => {
+      try {
+        const parsed = JSON.parse(event.data);
+        data.value = parsed;
+
+        if (parsed.type === "done" || parsed.type === "error") {
+          stop();
+        }
+      } catch (e) {
+        console.error("Parse error:", e);
+      }
+    };
+
+    eventSource.value.onerror = () => {
+      error.value = "Connection error";
+      status.value = "closed";
+
+      // Auto-reconnect
+      setTimeout(() => {
+        if (status.value === "closed") {
+          connect(url);
+        }
+      }, 2000);
+    };
+  };
+
+  const stop = () => {
+    if (eventSource.value) {
+      eventSource.value.close();
+      eventSource.value = null;
+    }
+    status.value = "closed";
+  };
+
+  onUnmounted(stop);
+
+  return { connect, stop, data, error, status };
+}
+```
+
+## Usage in Component
+
+```typescript
+const { connect, stop, data, status } = useSSE();
+
+const startAnalysis = async () => {
+  const { sessionId } = await $fetch("/api/analysis/start", { method: "POST" });
+  connect(`/api/analysis/${sessionId}/stream`);
+};
+
+watch(data, (newData) => {
+  if (newData?.type === "chunk") {
+    output.value += newData.text;
+  } else if (newData?.type === "done") {
+    isComplete.value = true;
+  }
+});
+
+onUnmounted(stop);
+```
+
+## Position-Based Resumption
+
+Resume from where client left off:
+
+```typescript
+// Client tracks position
+const position = ref(0);
+
+eventSource.value.onmessage = (event) => {
+  position.value++;
+  // handle data...
+};
+
+const reconnect = () => {
+  connect(`/api/stream/${id}?position=${position.value}`);
+};
+```
+
+```typescript
+// Server reads position
+const { position } = await getValidatedQuery(event, schema);
+const chunks = await getChunksFromPosition(id, position);
+```
+
+## Fallback to Polling
+
+When SSE isn't available:
+
+```typescript
+// Server returns non-SSE response
+if (!redisAvailable) {
+  return { type: "pending", message: "Use polling" };
+}
+
+// Client detects and falls back
+if (data.value?.type === "pending") {
+  stopSSE();
+  startPolling();
+}
+```
+
+## Key Gotchas
+
+1. **Always clean up** - Call `eventSource.close()` on unmount
+2. **Parse JSON** - SSE data is always strings
+3. **Handle reconnection** - Connections drop, plan for it
+4. **Timeouts** - Long streams need heartbeats
+5. **No binary data** - SSE is text-only, use base64 if needed

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/ssr-client.md

@@ -0,0 +1,166 @@
+# SSR + Client-side Patterns
+
+## The Problem
+
+`localStorage` and other browser APIs don't exist on the server. Accessing them during SSR causes errors or hydration mismatches.
+
+## Solutions
+
+### 1. `<ClientOnly>` Component
+
+Wrap components that need browser APIs:
+
+```vue
+<ClientOnly>
+  <DataTable :value="items" />
+
+  <template #fallback>
+    <div>Loading table...</div>
+  </template>
+</ClientOnly>
+```
+
+**Use for:**
+- Complex interactive components (DataTables, Maps, Charts)
+- Components using DOM APIs
+- Third-party components without SSR support
+
+### 2. `import.meta.client` Guard
+
+Check runtime environment before using browser APIs:
+
+```typescript
+watch(viewMode, (newMode) => {
+  if (import.meta.client) {
+    localStorage.setItem("view-mode", newMode);
+  }
+});
+
+const savePreference = (key: string, value: string) => {
+  if (import.meta.client) {
+    localStorage.setItem(key, value);
+  }
+};
+```
+
+Also available: `import.meta.server` for server-only code.
+
+### 3. `onMounted` for Client Initialization
+
+Read from localStorage only after hydration:
+
+```typescript
+const viewMode = ref("table");  // Default for SSR
+const isReady = ref(false);
+
+onMounted(() => {
+  const saved = localStorage.getItem("view-mode");
+  if (saved === "table" || saved === "kanban") {
+    viewMode.value = saved;
+  }
+  isReady.value = true;
+});
+```
+
+**Pattern for URL params + localStorage fallback:**
+```typescript
+onMounted(() => {
+  const queryTab = route.query.tab as string;
+
+  if (queryTab && validTabs.includes(queryTab)) {
+    activeTab.value = queryTab;
+  } else {
+    const savedTab = localStorage.getItem("last-tab");
+    if (savedTab && validTabs.includes(savedTab)) {
+      activeTab.value = savedTab;
+      router.replace({ query: { tab: savedTab } });
+    }
+  }
+});
+```
+
+### 4. VueUse `useLocalStorage` (SSR-Safe)
+
+Automatically handles SSR - reads on client after hydration:
+
+```typescript
+// Returns default during SSR, actual value on client
+const theme = useLocalStorage("theme", "light");
+const settings = useLocalStorage("settings", { compact: false });
+
+// Use normally - syncs automatically
+theme.value = "dark";
+```
+
+For delayed initialization to avoid hydration issues:
+```typescript
+const theme = useLocalStorage("theme", "light", {
+  initOnMounted: true,  // Don't read until mounted
+});
+```
+
+## VueUse SSR Notes
+
+With `@vueuse/nuxt`, these are auto-imported:
+- `refDebounced` - Yes, auto-imported
+- `useDebounceFn` - Yes
+- `useLocalStorage` - Yes
+- `useUrlSearchParams` - Yes
+
+**Disabled by default** (conflict with Nuxt):
+- `useRoute` - use Nuxt's version
+- `useRouter` - use Nuxt's version
+- `useFetch` - use Nuxt's version
+- `useHead` - use Nuxt's version
+
+## Hydration Mismatch Prevention
+
+**Problem:** Server renders with default, client reads different value = mismatch.
+
+**Solutions:**
+
+1. **Don't render during SSR:**
+```vue
+<ClientOnly>
+  <span>{{ preference }}</span>
+</ClientOnly>
+```
+
+2. **Use a ready flag:**
+```typescript
+const preference = ref("default");
+const ready = ref(false);
+
+onMounted(() => {
+  preference.value = localStorage.getItem("pref") || "default";
+  ready.value = true;
+});
+```
+```vue
+<span v-if="ready">{{ preference }}</span>
+<span v-else>Loading...</span>
+```
+
+3. **Use `useLocalStorage` with matching initial:**
+```typescript
+const count = useLocalStorage("count", 0);
+// Initial matches SSR, updates after hydration
+```
+
+## Summary Table
+
+| Approach | When to Use | SSR-Safe |
+|----------|-------------|----------|
+| `<ClientOnly>` | Entire component needs browser | Yes |
+| `import.meta.client` | Conditional browser API calls | Yes |
+| `onMounted` | Initialize from localStorage | Yes |
+| `useLocalStorage` | Reactive persistent state | Yes |
+| Direct `localStorage` | Never at top level | No |
+
+## Key Gotchas
+
+1. **Never access `localStorage` at module top-level**
+2. **`useLocalStorage` returns default during SSR**
+3. **URL query params are SSR-safe** - can read via `useRoute()`
+4. **Watch handlers run during SSR** - always guard with `import.meta.client`
+5. **`onMounted` never runs on server** - safe for all browser APIs

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

@@ -0,0 +1,131 @@
+# Validation Patterns
+
+> **Example:** [validation-endpoint.ts](./examples/validation-endpoint.ts)
+
+## Available Utilities (all auto-imported from h3)
+
+| Raw | Validated |
+|-----|-----------|
+| `readBody(event)` | `readValidatedBody(event, validator)` |
+| `getQuery(event)` | `getValidatedQuery(event, validator)` |
+| `getRouterParams(event)` | `getValidatedRouterParams(event, validator)` |
+
+Note: It's `getRouterParams` (plural), not `getRouterParam`.
+
+## Pattern 1: Direct Schema (h3 v2+ with Standard Schema)
+
+h3 v2+ supports Standard Schema, meaning you can pass Zod schemas directly:
+
+```typescript
+const querySchema = z.object({
+  search: z.string().min(1),
+  page: z.coerce.number().default(1),
+});
+
+// Pass schema directly (recommended)
+const query = await getValidatedQuery(event, querySchema);
+
+// Also works for body and params
+const body = await readValidatedBody(event, bodySchema);
+const params = await getValidatedRouterParams(event, paramsSchema);
+```
+
+**Pros:** Simplest syntax, cleaner code
+**Cons:** ZodError thrown directly - not user-friendly
+
+## Pattern 2: Manual Validator Function
+
+For custom validation logic:
+
+```typescript
+const query = await getValidatedQuery(event, (data) => querySchema.parse(data));
+```
+
+## Pattern 3: safeParse for Better Errors
+
+```typescript
+import { fromZodError } from "zod-validation-error";
+
+const rawQuery = getQuery(event);
+const result = querySchema.safeParse(rawQuery);
+
+if (!result.success) {
+  console.error("Validation error:", result.error);  // Dev log
+  const userError = fromZodError(result.error);      // User-friendly
+  throw createError({
+    statusCode: 400,
+    statusMessage: "Bad Request",
+    message: userError.message,
+  });
+}
+
+return result.data;
+```
+
+## Common Zod Patterns
+
+### Query Parameters
+
+```typescript
+const querySchema = z.object({
+  // Optional string
+  search: z.string().optional(),
+
+  // Coerce to number (query params are strings)
+  page: z.coerce.number().default(1),
+  limit: z.coerce.number().max(100).default(20),
+
+  // Boolean from string
+  active: z.enum(["true", "false"]).transform(v => v === "true").optional(),
+
+  // Enum
+  status: z.enum(["pending", "active", "closed"]).optional(),
+
+  // Array from comma-separated
+  tags: z.string().transform(s => s.split(",")).optional(),
+});
+```
+
+### Request Body
+
+```typescript
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1).max(100),
+  role: z.enum(["admin", "user"]).default("user"),
+  metadata: z.record(z.string(), z.any()).optional(),
+});
+```
+
+### Path Parameters
+
+```typescript
+const paramsSchema = z.object({
+  id: z.coerce.number().positive(),
+});
+
+// In /api/users/[id].get.ts
+const { id } = await getValidatedRouterParams(event, paramsSchema);
+```
+
+## Type Inference from Schemas
+
+Export schemas for client-side type reuse:
+
+```typescript
+// types/api.ts
+import { z } from "zod";
+
+export const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+});
+
+export type CreateUserInput = z.infer<typeof CreateUserSchema>;
+
+// Client usage
+import type { CreateUserInput } from "~/types/api";
+const body: CreateUserInput = { email: "test@example.com", name: "Test" };
+```
+
+**Note:** Nitro auto-generates response types, but NOT input types from Zod schemas.