@girardmedia/bootspring 1.1.0

package/skills/patterns/README.md

@@ -0,0 +1,163 @@
+# Bootspring Skill Patterns
+
+Battle-tested code patterns for common development tasks.
+
+## Available Patterns
+
+### Authentication
+| Pattern | Description |
+|---------|-------------|
+| [auth/clerk](./auth/clerk.md) | Clerk authentication - server auth, middleware, user sync |
+
+### Database
+| Pattern | Description |
+|---------|-------------|
+| [database/prisma](./database/prisma.md) | Prisma ORM - client setup, queries, transactions, migrations |
+
+### API Development
+| Pattern | Description |
+|---------|-------------|
+| [api/route-handler](./api/route-handler.md) | Next.js route handlers - CRUD, error handling, rate limiting |
+| [api/server-action](./api/server-action.md) | Server actions - forms, optimistic updates, useActionState |
+
+### Payments
+| Pattern | Description |
+|---------|-------------|
+| [payments/stripe](./payments/stripe.md) | Stripe - checkout, subscriptions, webhooks, customer portal |
+
+### Security
+| Pattern | Description |
+|---------|-------------|
+| [security/validation](./security/validation.md) | Input validation - Zod schemas, sanitization, CSRF, rate limiting |
+
+### Testing
+| Pattern | Description |
+|---------|-------------|
+| [testing/vitest](./testing/vitest.md) | Vitest - setup, unit tests, component tests, mocking |
+
+## Usage
+
+### Via CLI
+```bash
+# List all patterns
+bootspring skill list
+
+# Include curated external skills catalog (skills/external)
+bootspring skill list --external
+
+# Search for patterns
+bootspring skill search "auth"
+bootspring skill search "vercel" --external
+
+# Show a specific pattern
+bootspring skill show auth/clerk
+
+# Show concise summary
+bootspring skill show auth/clerk --summary
+
+# Show only matching sections and cap output size
+bootspring skill show api/route-handler --sections "basic crud,error handling" --max-chars 1200
+
+# Show an external skill by id
+bootspring skill show external/vercel-automation
+```
+
+### Via MCP Tool
+```text
+bootspring_skill { action: "show", name: "auth/clerk" }
+bootspring_skill { action: "show", name: "auth/clerk", summary: true }
+bootspring_skill { action: "show", name: "api/route-handler", sections: "basic crud", maxChars: 1200 }
+bootspring_skill { action: "search", query: "database" }
+bootspring_skill { action: "list", includeExternal: true, limit: 20 }
+```
+
+### Direct Reference
+Patterns are markdown files with code blocks. Reference them in prompts:
+```text
+Using the pattern from bootspring/skills/patterns/api/server-action.md,
+implement a server action for updating user profile.
+```
+
+## Pattern Structure
+
+Each pattern includes:
+- **Setup code** - Configuration and initialization
+- **Common patterns** - Frequently used implementations
+- **Best practices** - Security and performance considerations
+- **When to use** - Guidance on appropriate use cases
+
+## Adding Custom Patterns
+
+Create a markdown file in the appropriate category:
+```text
+skills/patterns/
+├── auth/
+│   └── my-custom-auth.md
+├── database/
+├── api/
+└── ...
+```
+
+Pattern template:
+```markdown
+# Pattern Name
+
+Brief description.
+
+## Setup
+
+~~~typescript
+// Configuration code
+~~~
+
+## Common Patterns
+
+~~~typescript
+// Implementation examples
+~~~
+
+## When to Use
+
+- Use case 1
+- Use case 2
+```
+
+## External Catalog (Curated)
+
+If `skills/external/` exists, Bootspring indexes it as an optional external catalog:
+
+- `bootspring skill list --external`
+- `bootspring skill search <query> --external`
+- `bootspring skill show external/<skill-id>`
+
+This catalog is optional. If you want a leaner repo, you can remove `skills/external/` without affecting built-in patterns.
+
+### Entitlement Policy
+
+External skills are checked through `core/entitlements.js`:
+
+- `BOOTSPRING_SKILL_ACCESS_MODE=local` (default): external skills are accessible.
+- `BOOTSPRING_SKILL_ACCESS_MODE=server`: external skills require entitlement.
+- Entitlement in server mode is granted by either:
+  - `BOOTSPRING_SKILLS_ENTITLED=true`
+  - `BOOTSPRING_USER_TIER=pro|team|enterprise`
+
+### Remote Catalog Sync
+
+For lightweight npm installs, sync protected skills from your backend into local cache:
+
+```bash
+bootspring skill sync \
+  --manifest-url https://api.bootspring.com/skills/manifest.json \
+  --content-base-url https://api.bootspring.com/skills/content
+```
+
+Relevant environment variables:
+
+- `BOOTSPRING_SKILL_MANIFEST_URL`
+- `BOOTSPRING_SKILL_CONTENT_BASE_URL`
+- `BOOTSPRING_SKILL_TOKEN`
+- `BOOTSPRING_SKILL_CACHE_DIR`
+- `BOOTSPRING_SKILL_CATALOG_SOURCE=auto|cache|local`
+- `BOOTSPRING_SKILL_MANIFEST_PUBLIC_KEY`
+- `BOOTSPRING_SKILL_MANIFEST_REQUIRE_SIGNATURE=true|false`

package/skills/patterns/api/route-handler.md

@@ -0,0 +1,217 @@
+# Next.js Route Handler Patterns
+
+Battle-tested patterns for API routes in Next.js App Router.
+
+## Basic CRUD Route Handler
+
+```typescript
+// app/api/posts/route.ts
+import { prisma } from '@/lib/db'
+import { auth } from '@/lib/auth'
+import { NextRequest, NextResponse } from 'next/server'
+import { z } from 'zod'
+
+const CreatePostSchema = z.object({
+  title: z.string().min(1).max(200),
+  content: z.string().optional(),
+  published: z.boolean().default(false)
+})
+
+// GET /api/posts
+export async function GET(request: NextRequest) {
+  const searchParams = request.nextUrl.searchParams
+  const page = parseInt(searchParams.get('page') ?? '1')
+  const limit = parseInt(searchParams.get('limit') ?? '10')
+
+  const posts = await prisma.post.findMany({
+    where: { published: true },
+    orderBy: { createdAt: 'desc' },
+    skip: (page - 1) * limit,
+    take: limit,
+    include: { author: { select: { name: true } } }
+  })
+
+  return NextResponse.json({ posts, page, limit })
+}
+
+// POST /api/posts
+export async function POST(request: NextRequest) {
+  try {
+    const { userId } = await auth()
+    if (!userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const body = await request.json()
+    const validated = CreatePostSchema.parse(body)
+
+    const post = await prisma.post.create({
+      data: { ...validated, authorId: userId }
+    })
+
+    return NextResponse.json(post, { status: 201 })
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return NextResponse.json({ error: error.errors }, { status: 400 })
+    }
+    return NextResponse.json({ error: 'Internal error' }, { status: 500 })
+  }
+}
+```
+
+## Dynamic Route Handler
+
+```typescript
+// app/api/posts/[id]/route.ts
+import { prisma } from '@/lib/db'
+import { auth } from '@/lib/auth'
+import { NextRequest, NextResponse } from 'next/server'
+
+type Params = { params: Promise<{ id: string }> }
+
+// GET /api/posts/:id
+export async function GET(request: NextRequest, { params }: Params) {
+  const { id } = await params
+
+  const post = await prisma.post.findUnique({
+    where: { id },
+    include: { author: { select: { name: true, email: true } } }
+  })
+
+  if (!post) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 })
+  }
+
+  return NextResponse.json(post)
+}
+
+// PATCH /api/posts/:id
+export async function PATCH(request: NextRequest, { params }: Params) {
+  const { userId } = await auth()
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { id } = await params
+  const body = await request.json()
+
+  const post = await prisma.post.findUnique({ where: { id } })
+  if (!post) {
+    return NextResponse.json({ error: 'Not found' }, { status: 404 })
+  }
+  if (post.authorId !== userId) {
+    return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
+  }
+
+  const updated = await prisma.post.update({
+    where: { id },
+    data: body
+  })
+
+  return NextResponse.json(updated)
+}
+
+// DELETE /api/posts/:id
+export async function DELETE(request: NextRequest, { params }: Params) {
+  const { userId } = await auth()
+  if (!userId) {
+    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const { id } = await params
+
+  const post = await prisma.post.findUnique({ where: { id } })
+  if (!post || post.authorId !== userId) {
+    return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
+  }
+
+  await prisma.post.delete({ where: { id } })
+
+  return new NextResponse(null, { status: 204 })
+}
+```
+
+## Error Handling Wrapper
+
+```typescript
+// lib/api-utils.ts
+import { NextRequest, NextResponse } from 'next/server'
+import { ZodError } from 'zod'
+
+type Handler = (req: NextRequest, context?: any) => Promise<NextResponse>
+
+export function withErrorHandling(handler: Handler): Handler {
+  return async (req, context) => {
+    try {
+      return await handler(req, context)
+    } catch (error) {
+      console.error('API Error:', error)
+
+      if (error instanceof ZodError) {
+        return NextResponse.json(
+          { error: 'Validation failed', details: error.errors },
+          { status: 400 }
+        )
+      }
+
+      if (error instanceof Error) {
+        if (error.message === 'UNAUTHORIZED') {
+          return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+        }
+        if (error.message === 'NOT_FOUND') {
+          return NextResponse.json({ error: 'Not found' }, { status: 404 })
+        }
+      }
+
+      return NextResponse.json(
+        { error: 'Internal server error' },
+        { status: 500 }
+      )
+    }
+  }
+}
+```
+
+## Rate Limiting Pattern
+
+```typescript
+// lib/rate-limit.ts
+import { NextRequest, NextResponse } from 'next/server'
+
+const rateLimit = new Map<string, { count: number; resetTime: number }>()
+
+export function checkRateLimit(
+  identifier: string,
+  limit: number = 10,
+  windowMs: number = 60000
+): boolean {
+  const now = Date.now()
+  const record = rateLimit.get(identifier)
+
+  if (!record || now > record.resetTime) {
+    rateLimit.set(identifier, { count: 1, resetTime: now + windowMs })
+    return true
+  }
+
+  if (record.count >= limit) {
+    return false
+  }
+
+  record.count++
+  return true
+}
+
+// Usage in route
+export async function POST(request: NextRequest) {
+  const ip = request.headers.get('x-forwarded-for') ?? 'anonymous'
+
+  if (!checkRateLimit(ip, 10, 60000)) {
+    return NextResponse.json(
+      { error: 'Too many requests' },
+      { status: 429 }
+    )
+  }
+
+  // Continue with handler...
+}
+```

package/skills/patterns/api/server-action.md

@@ -0,0 +1,249 @@
+# Next.js Server Action Patterns
+
+Battle-tested patterns for Server Actions in Next.js App Router.
+
+## Basic Server Action
+
+```typescript
+// actions/posts.ts
+'use server'
+
+import { prisma } from '@/lib/db'
+import { auth } from '@/lib/auth'
+import { revalidatePath } from 'next/cache'
+import { redirect } from 'next/navigation'
+import { z } from 'zod'
+
+const CreatePostSchema = z.object({
+  title: z.string().min(1, 'Title is required').max(200),
+  content: z.string().optional()
+})
+
+export async function createPost(formData: FormData) {
+  const { userId } = await auth()
+  if (!userId) throw new Error('UNAUTHORIZED')
+
+  const validated = CreatePostSchema.parse({
+    title: formData.get('title'),
+    content: formData.get('content')
+  })
+
+  const post = await prisma.post.create({
+    data: { ...validated, authorId: userId }
+  })
+
+  revalidatePath('/posts')
+  redirect(`/posts/${post.id}`)
+}
+```
+
+## Server Action with Return Value
+
+```typescript
+// actions/posts.ts
+'use server'
+
+type ActionResult<T> =
+  | { success: true; data: T }
+  | { success: false; error: string }
+
+export async function updatePost(
+  postId: string,
+  formData: FormData
+): Promise<ActionResult<{ id: string }>> {
+  try {
+    const { userId } = await auth()
+    if (!userId) {
+      return { success: false, error: 'Not authenticated' }
+    }
+
+    const post = await prisma.post.findUnique({ where: { id: postId } })
+    if (!post || post.authorId !== userId) {
+      return { success: false, error: 'Not authorized' }
+    }
+
+    const title = formData.get('title') as string
+    if (!title || title.length < 1) {
+      return { success: false, error: 'Title is required' }
+    }
+
+    const updated = await prisma.post.update({
+      where: { id: postId },
+      data: { title }
+    })
+
+    revalidatePath(`/posts/${postId}`)
+    return { success: true, data: { id: updated.id } }
+  } catch (error) {
+    console.error('Update post error:', error)
+    return { success: false, error: 'Failed to update post' }
+  }
+}
+```
+
+## Using with useActionState (React 19)
+
+```typescript
+// components/create-post-form.tsx
+'use client'
+
+import { useActionState } from 'react'
+import { createPost } from '@/actions/posts'
+
+const initialState = { error: null as string | null }
+
+export function CreatePostForm() {
+  const [state, formAction, isPending] = useActionState(
+    async (prevState: typeof initialState, formData: FormData) => {
+      const result = await createPost(formData)
+      if (!result.success) {
+        return { error: result.error }
+      }
+      return { error: null }
+    },
+    initialState
+  )
+
+  return (
+    <form action={formAction}>
+      {state.error && (
+        <div className="text-red-500 mb-4">{state.error}</div>
+      )}
+
+      <input
+        name="title"
+        placeholder="Post title"
+        required
+        disabled={isPending}
+        className="w-full p-2 border rounded"
+      />
+
+      <textarea
+        name="content"
+        placeholder="Content (optional)"
+        disabled={isPending}
+        className="w-full p-2 border rounded mt-2"
+      />
+
+      <button
+        type="submit"
+        disabled={isPending}
+        className="mt-4 px-4 py-2 bg-blue-500 text-white rounded disabled:opacity-50"
+      >
+        {isPending ? 'Creating...' : 'Create Post'}
+      </button>
+    </form>
+  )
+}
+```
+
+## Delete Action with Confirmation
+
+```typescript
+// actions/posts.ts
+'use server'
+
+export async function deletePost(postId: string): Promise<ActionResult<null>> {
+  const { userId } = await auth()
+  if (!userId) {
+    return { success: false, error: 'Not authenticated' }
+  }
+
+  const post = await prisma.post.findUnique({ where: { id: postId } })
+  if (!post || post.authorId !== userId) {
+    return { success: false, error: 'Not authorized' }
+  }
+
+  await prisma.post.delete({ where: { id: postId } })
+
+  revalidatePath('/posts')
+  return { success: true, data: null }
+}
+
+// components/delete-button.tsx
+'use client'
+
+import { deletePost } from '@/actions/posts'
+import { useTransition } from 'react'
+import { useRouter } from 'next/navigation'
+
+export function DeleteButton({ postId }: { postId: string }) {
+  const [isPending, startTransition] = useTransition()
+  const router = useRouter()
+
+  const handleDelete = () => {
+    if (!confirm('Are you sure you want to delete this post?')) return
+
+    startTransition(async () => {
+      const result = await deletePost(postId)
+      if (result.success) {
+        router.push('/posts')
+      } else {
+        alert(result.error)
+      }
+    })
+  }
+
+  return (
+    <button
+      onClick={handleDelete}
+      disabled={isPending}
+      className="text-red-500 disabled:opacity-50"
+    >
+      {isPending ? 'Deleting...' : 'Delete'}
+    </button>
+  )
+}
+```
+
+## Optimistic Updates
+
+```typescript
+// components/like-button.tsx
+'use client'
+
+import { useOptimistic, useTransition } from 'react'
+import { toggleLike } from '@/actions/posts'
+
+export function LikeButton({ postId, initialLiked, initialCount }: {
+  postId: string
+  initialLiked: boolean
+  initialCount: number
+}) {
+  const [isPending, startTransition] = useTransition()
+  const [optimistic, setOptimistic] = useOptimistic(
+    { liked: initialLiked, count: initialCount },
+    (state, newLiked: boolean) => ({
+      liked: newLiked,
+      count: newLiked ? state.count + 1 : state.count - 1
+    })
+  )
+
+  const handleClick = () => {
+    startTransition(async () => {
+      setOptimistic(!optimistic.liked)
+      await toggleLike(postId)
+    })
+  }
+
+  return (
+    <button onClick={handleClick} disabled={isPending}>
+      {optimistic.liked ? '❤️' : '🤍'} {optimistic.count}
+    </button>
+  )
+}
+```
+
+## When to Use Server Actions vs Route Handlers
+
+**Use Server Actions for:**
+- Form submissions
+- Mutations from client components
+- Actions that need revalidation
+- Progressive enhancement (works without JS)
+
+**Use Route Handlers for:**
+- Webhooks from external services
+- Public APIs consumed by other apps
+- Long-running operations
+- File uploads/downloads