@gallopsystems/agent-skills 1.0.0

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

@@ -0,0 +1,243 @@
+# Nitro Tasks
+
+Background jobs, scheduled tasks, and one-off operations.
+
+## Enabling Tasks
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  nitro: {
+    experimental: {
+      tasks: true,
+    },
+    scheduledTasks: {
+      // Cron format: minute hour day month weekday
+      "*/5 * * * *": ["scheduled:cleanup"],      // Every 5 minutes
+      "0 0 * * *": ["scheduled:daily-report"],   // Daily at midnight
+      "0 8 * * 1": ["scheduled:weekly-digest"],  // Mondays at 8am
+    },
+  },
+});
+```
+
+## Defining Tasks
+
+Tasks live in `server/tasks/`. Directory structure = task name with colons:
+- `server/tasks/hello.ts` → `hello`
+- `server/tasks/scheduled/cleanup.ts` → `scheduled:cleanup`
+- `server/tasks/jobs/send-email.ts` → `jobs:send-email`
+
+```typescript
+// server/tasks/jobs/send-email.ts
+import { z } from "zod";
+
+const PayloadSchema = z.object({
+  to: z.string().email(),
+  subject: z.string(),
+  body: z.string(),
+});
+
+export default defineTask({
+  meta: {
+    name: "jobs:send-email",
+    description: "Send an email in the background",
+  },
+  async run({ payload }) {
+    const data = PayloadSchema.parse(payload);
+    await sendEmail(data);
+
+    return {
+      result: "success",
+      sentAt: new Date().toISOString(),
+    };
+  },
+});
+```
+
+## Running Tasks
+
+### 1. Programmatically with `runTask`
+
+```typescript
+export default defineEventHandler(async (event) => {
+  const result = await runTask("jobs:send-email", {
+    payload: {
+      to: "user@example.com",
+      subject: "Hello",
+      body: "Welcome!",
+    },
+  });
+
+  return { taskResult: result };
+});
+```
+
+### 2. Fire-and-forget Pattern
+
+```typescript
+// Don't wait for completion
+runTask("jobs:send-email", {
+  payload: { to: "user@example.com", subject: "Hello", body: "Hi!" },
+}).catch((error) => {
+  console.error("Task failed:", error);
+});
+
+return { message: "Email queued" };
+```
+
+### 3. Dev Server API (development only)
+
+```bash
+GET /_nitro/tasks                          # List all tasks
+GET /_nitro/tasks/jobs:send-email          # Run task
+POST /_nitro/tasks/jobs:send-email         # Run with payload
+```
+
+### 4. CLI
+
+```bash
+npx nitro task list
+npx nitro task run jobs:send-email --payload '{"to":"user@example.com"}'
+```
+
+## Critical Limitation: Single Instance (By Design)
+
+**Each task can only have ONE running instance at a time.**
+
+If you call `runTask("my-task")` while it's already running:
+- The second call returns the SAME result as the first
+- It does NOT queue or start a new execution
+- No error is thrown
+
+```typescript
+// These share the same execution!
+const [result1, result2] = await Promise.all([
+  runTask("long-running-task"),
+  runTask("long-running-task"),
+]);
+// result1 === result2
+```
+
+## Workaround: Database Job Queue
+
+For true background processing, use a database-backed queue:
+
+```typescript
+// 1. Enqueue job
+export async function enqueueJob(jobType: string, payload: any) {
+  const db = useDatabase();
+  const [job] = await db
+    .insertInto("job_queue")
+    .values({
+      job_type: jobType,
+      payload: JSON.stringify(payload),
+      status: "pending",
+      created_at: new Date(),
+    })
+    .returning(["id"])
+    .execute();
+  return job.id;
+}
+
+// 2. Job dispatcher (runs every few seconds)
+// server/tasks/scheduled/job-dispatcher.ts
+export default defineTask({
+  meta: { name: "scheduled:job-dispatcher" },
+  async run() {
+    const db = useDatabase();
+
+    // Dequeue with locking
+    const job = await db.transaction().execute(async (trx) => {
+      const job = await trx
+        .selectFrom("job_queue")
+        .selectAll()
+        .where("status", "=", "pending")
+        .orderBy("created_at", "asc")
+        .forUpdate()      // Lock row
+        .skipLocked()     // Skip locked rows
+        .limit(1)
+        .executeTakeFirst();
+
+      if (!job) return null;
+
+      await trx
+        .updateTable("job_queue")
+        .set({ status: "processing", started_at: new Date() })
+        .where("id", "=", job.id)
+        .execute();
+
+      return job;
+    });
+
+    if (!job) return { result: "No jobs" };
+
+    // Fire and forget the work
+    processJob(job).catch(console.error);
+
+    return { result: `Dispatched job ${job.id}` };
+  },
+});
+```
+
+```typescript
+// nuxt.config.ts
+scheduledTasks: {
+  "*/2 * * * * *": ["scheduled:job-dispatcher"],  // Every 2 seconds
+}
+```
+
+## Retry Logic
+
+```typescript
+export async function markJobFailed(jobId: number, error: Error) {
+  const db = useDatabase();
+  const job = await db
+    .selectFrom("job_queue")
+    .select(["attempt_count", "max_attempts"])
+    .where("id", "=", jobId)
+    .executeTakeFirst();
+
+  const shouldRetry = (job.attempt_count || 0) < (job.max_attempts || 3);
+
+  if (shouldRetry) {
+    // Exponential backoff: 1min, 2min, 4min...
+    const delay = Math.pow(2, job.attempt_count || 0) * 60000;
+    const jitter = Math.random() * 0.1 * delay;
+
+    await db
+      .updateTable("job_queue")
+      .set({
+        status: "pending",
+        scheduled_at: new Date(Date.now() + delay + jitter),
+        error_message: error.message,
+      })
+      .where("id", "=", jobId)
+      .execute();
+  } else {
+    await db
+      .updateTable("job_queue")
+      .set({ status: "failed", error_message: error.message })
+      .where("id", "=", jobId)
+      .execute();
+  }
+}
+```
+
+## When to Use Each Pattern
+
+| Pattern | Use Case |
+|---------|----------|
+| `runTask` with await | One-off tasks, need result |
+| Fire-and-forget | Background work, no result needed |
+| Scheduled tasks | Recurring jobs (cleanup, reports) |
+| DB job queue | Concurrent jobs, retries, reliability |
+
+## Key Gotchas
+
+1. **Single instance limitation** - Can't run same task twice concurrently
+2. **No built-in queue** - Multiple calls share result
+3. **Scheduled tasks need server** - Won't work with `nuxt generate`
+4. **Dev API only in dev** - `/_nitro/tasks/*` not in production
+5. **Cron needs specific runtimes** - node-server, bun, deno-server, cloudflare
+6. **Fire-and-forget errors** - Must add `.catch()` or errors are swallowed

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/page-structure.md

@@ -0,0 +1,162 @@
+# Page Structure
+
+Pages should be thin. Keep logic in components, use pages only for layout and routing.
+
+## The Pattern
+
+```vue
+<!-- pages/users/[id].vue -->
+<script setup lang="ts">
+// 1. Parse route params
+const route = useRoute();
+const userId = computed(() => route.params.id as string);
+
+// 2. Maybe check auth/permissions
+const { user } = useUserSession();
+</script>
+
+<template>
+  <!-- 3. Layout + components only -->
+  <div class="page-container">
+    <PageHeader title="User Profile" />
+
+    <!-- Pass parsed params to components -->
+    <UserProfile :user-id="userId" />
+
+    <UserActivity :user-id="userId" v-if="user?.role === 'admin'" />
+  </div>
+</template>
+```
+
+## What Goes Where
+
+| In Page | In Component |
+|---------|--------------|
+| Route param parsing | Data fetching (useFetch) |
+| Layout structure | Business logic |
+| Component composition | Form handling |
+| Auth guards (via middleware) | State management |
+| Page meta (title, middleware) | Event handlers |
+
+## Pages Do
+
+```vue
+<script setup lang="ts">
+// ✅ Route params
+const route = useRoute();
+const id = computed(() => route.params.id as string);
+
+// ✅ Query params (for passing to components)
+const tab = computed(() => (route.query.tab as string) || 'overview');
+
+// ✅ Page metadata
+definePageMeta({
+  middleware: 'auth',
+  layout: 'dashboard',
+});
+
+// ✅ Page title
+useHead({ title: 'User Profile' });
+</script>
+
+<template>
+  <!-- ✅ Layout wrapper -->
+  <NuxtLayout>
+    <!-- ✅ Component composition -->
+    <UserHeader :id="id" />
+    <UserTabs :active-tab="tab" :user-id="id" />
+  </NuxtLayout>
+</template>
+```
+
+## Pages Don't
+
+```vue
+<script setup lang="ts">
+// ❌ Data fetching - move to component
+const { data: user } = await useFetch(`/api/users/${route.params.id}`);
+
+// ❌ Complex computed - move to component
+const fullName = computed(() => `${user.value?.firstName} ${user.value?.lastName}`);
+
+// ❌ Event handlers - move to component
+const handleSave = async () => {
+  await $fetch(`/api/users/${route.params.id}`, { method: 'PATCH', body: form });
+};
+
+// ❌ Form state - move to component
+const form = reactive({ name: '', email: '' });
+
+// ❌ Watchers - move to component
+watch(user, (newUser) => {
+  form.name = newUser?.name || '';
+});
+</script>
+
+<template>
+  <!-- ❌ Too much logic in template -->
+  <form @submit.prevent="handleSave">
+    <input v-model="form.name" />
+    <input v-model="form.email" />
+    <button type="submit">Save</button>
+  </form>
+</template>
+```
+
+## Component Does the Work
+
+```vue
+<!-- components/UserProfile.vue -->
+<script setup lang="ts">
+const props = defineProps<{
+  userId: string;
+}>();
+
+// ✅ Data fetching in component
+const { data: user, refresh } = await useFetch(() => `/api/users/${props.userId}`);
+
+// ✅ Form state
+const form = reactive({ name: '', email: '' });
+
+// ✅ Sync form with data
+watch(user, (newUser) => {
+  if (newUser) {
+    form.name = newUser.name;
+    form.email = newUser.email;
+  }
+}, { immediate: true });
+
+// ✅ Event handlers
+const handleSave = async () => {
+  await $fetch(`/api/users/${props.userId}`, {
+    method: 'PATCH',
+    body: form,
+  });
+  refresh();
+};
+</script>
+
+<template>
+  <form @submit.prevent="handleSave">
+    <input v-model="form.name" placeholder="Name" />
+    <input v-model="form.email" placeholder="Email" />
+    <button type="submit">Save</button>
+  </form>
+</template>
+```
+
+## Benefits
+
+1. **Reusability** - Components can be used in multiple pages
+2. **Testability** - Components are easier to test in isolation
+3. **Readability** - Pages show structure at a glance
+4. **Maintainability** - Changes to logic don't affect page layout
+5. **Code splitting** - Nuxt can better optimize component loading
+
+## Key Gotchas
+
+1. **Don't fetch in pages** - Let components own their data
+2. **Props down, events up** - Pass params as props, emit events for actions
+3. **Pages are entry points** - Think of them as "controllers" that compose "views"
+4. **Middleware for auth** - Use `definePageMeta({ middleware: 'auth' })`, not inline checks
+5. **Layouts for shared UI** - Headers, footers, sidebars go in `/layouts`, not repeated in pages

package/plugins/nuxt-nitro-api/skills/nuxt-nitro-api/server-services.md

@@ -0,0 +1,238 @@
+# Server-Side Service Integrations
+
+> **Example:** [service-util.ts](./examples/service-util.ts)
+
+Composable-style utilities for third-party services in `/server/utils/`.
+
+## Basic Pattern
+
+```typescript
+// server/utils/stripe.ts
+import Stripe from "stripe";
+
+// Initialize at module level with runtime config
+const config = useRuntimeConfig();
+const stripe = new Stripe(config.stripe.secretKey);
+
+// Define typed methods
+async function createPaymentIntent(options: {
+  amount: number;
+  currency: string;
+  metadata?: Record<string, string>;
+}) {
+  return stripe.paymentIntents.create({
+    amount: options.amount,
+    currency: options.currency,
+    metadata: options.metadata,
+  });
+}
+
+async function getCustomer(customerId: string) {
+  return stripe.customers.retrieve(customerId);
+}
+
+// Export as use*()
+export function useStripe() {
+  return { createPaymentIntent, getCustomer, client: stripe };
+}
+```
+
+## Usage in API Handlers
+
+```typescript
+// server/api/checkout/create.post.ts
+export default defineEventHandler(async (event) => {
+  const { amount, currency } = await readBody(event);
+
+  const { createPaymentIntent } = useStripe();
+
+  const intent = await createPaymentIntent({
+    amount,
+    currency,
+    metadata: { source: "web" },
+  });
+
+  return { clientSecret: intent.client_secret };
+});
+```
+
+## Service Composition
+
+Services can use other services:
+
+```typescript
+// server/utils/orders.ts
+export function useOrders() {
+  const db = useDatabase();
+  const { createPaymentIntent } = useStripe();
+
+  async function createOrder(userId: number, items: CartItem[]) {
+    const total = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
+
+    // Create payment intent with Stripe
+    const paymentIntent = await createPaymentIntent({
+      amount: total,
+      currency: "usd",
+      metadata: { userId: String(userId) },
+    });
+
+    // Save order to database
+    const order = await db
+      .insertInto("orders")
+      .values({
+        user_id: userId,
+        total,
+        stripe_payment_intent_id: paymentIntent.id,
+        status: "pending",
+      })
+      .returning(["id"])
+      .executeTakeFirst();
+
+    return { order, clientSecret: paymentIntent.client_secret };
+  }
+
+  return { createOrder };
+}
+```
+
+## Lazy Initialization
+
+For expensive clients:
+
+```typescript
+// server/utils/redis.ts
+let redis: Redis | null = null;
+
+export function useRedis(): Redis {
+  if (!redis) {
+    const config = useRuntimeConfig();
+
+    if (!config.redis?.url) {
+      throw new Error("NUXT_REDIS_URL not configured");
+    }
+
+    redis = new Redis(config.redis.url);
+    redis.on("error", (err) => console.error("Redis error:", err));
+    redis.on("connect", () => console.log("Redis connected"));
+  }
+
+  return redis;
+}
+
+// Health check
+export async function isRedisAvailable(): Promise<boolean> {
+  try {
+    await useRedis().ping();
+    return true;
+  } catch {
+    return false;
+  }
+}
+```
+
+## Error Handling
+
+```typescript
+// server/utils/error-handling.ts
+export function formatServiceError(error: unknown, service: string) {
+  const err = error as any;
+
+  // PostgreSQL constraint violations
+  if (err?.code === "23505") {
+    return { status: 409, message: "Resource already exists" };
+  }
+  if (err?.code === "23503") {
+    return { status: 400, message: "Referenced resource not found" };
+  }
+
+  // Network errors
+  if (err?.code === "ECONNREFUSED" || err?.code === "ETIMEDOUT") {
+    return { status: 503, message: `${service} service unavailable` };
+  }
+
+  // API errors
+  if (err?.response?.status) {
+    return { status: err.response.status, message: err.message };
+  }
+
+  return { status: 500, message: `${service} error: ${err?.message}` };
+}
+
+// Usage
+async function callExternalApi() {
+  try {
+    return await client.doSomething();
+  } catch (error) {
+    const { status, message } = formatServiceError(error, "Stripe");
+    throw createError({ statusCode: status, message });
+  }
+}
+```
+
+## Transaction Pattern
+
+```typescript
+// server/utils/invoices.ts
+export function useInvoices() {
+  const db = useDatabase();
+
+  async function createInvoice(params: CreateParams) {
+    return await db.transaction().execute(async (trx) => {
+      // All operations use trx, not db
+      const invoice = await trx
+        .insertInto("invoice")
+        .values(params)
+        .returning(["id"])
+        .executeTakeFirst();
+
+      await trx
+        .updateTable("session")
+        .set({ invoice_id: invoice.id, locked: true })
+        .where("id", "in", params.sessionIds)
+        .execute();
+
+      return invoice;
+    });
+  }
+
+  return { createInvoice };
+}
+```
+
+## Common Structure
+
+```typescript
+// server/utils/[service].ts
+
+// 1. Import SDK
+import { ServiceClient } from "service-sdk";
+
+// 2. Initialize with runtime config
+const config = useRuntimeConfig();
+const client = new ServiceClient({ apiKey: config.service.apiKey });
+
+// 3. Define typed methods
+async function doAction(params: ActionParams): Promise<ActionResult> {
+  try {
+    return await client.action(params);
+  } catch (error) {
+    throw createError({ statusCode: 500, message: error.message });
+  }
+}
+
+// 4. Export as use*()
+export function useService() {
+  return {
+    doAction,
+    client,  // Expose for advanced usage
+  };
+}
+```
+
+## Key Gotchas
+
+1. **Config at module level** - `useRuntimeConfig()` works at module scope
+2. **Singleton clients** - Initialize once, reuse across requests
+3. **Composition order** - Call use*() inside functions, not module level
+4. **Error transformation** - Convert SDK errors to HTTP errors
+5. **Transaction scope** - Pass `trx` when in transaction