@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/astro-patterns.md

@@ -0,0 +1,233 @@
+---
+name: astro-patterns
+description: Astro patterns for islands architecture, content collections, SSG/SSR modes, integrations, and view transitions.
+---
+
+# Astro Patterns
+
+## When to Use
+Use Astro for content-heavy websites, documentation sites, blogs, marketing pages, and any project where most pages are static with selective interactivity. Astro's islands architecture ships zero JavaScript by default, hydrating only the interactive components you specify. Choose Astro when page load performance and SEO are top priorities.
+
+## How It Works
+
+### Project Structure and Configuration
+
+```typescript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import tailwind from '@astrojs/tailwind';
+import mdx from '@astrojs/mdx';
+import sitemap from '@astrojs/sitemap';
+import vercel from '@astrojs/vercel';
+
+export default defineConfig({
+  site: 'https://example.com',
+  output: 'hybrid', // static by default, opt-in to SSR per page
+  adapter: vercel(),
+  integrations: [
+    react(),
+    tailwind({ applyBaseStyles: false }),
+    mdx(),
+    sitemap({ filter: (page) => !page.includes('/admin/') }),
+  ],
+  image: { service: { entrypoint: 'astro/assets/services/sharp' } },
+  vite: { build: { assetsInlineLimit: 4096 } },
+});
+```
+
+### Islands Architecture (Partial Hydration)
+
+```astro
+---
+// src/pages/index.astro
+import Layout from '../layouts/Base.astro';
+import Hero from '../components/Hero.astro';       // Static — no JS shipped
+import SearchBar from '../components/SearchBar';    // React — hydrated on load
+import Newsletter from '../components/Newsletter';  // React — hydrated on visible
+import Analytics from '../components/Analytics';     // React — hydrated on idle
+---
+
+<Layout title="Home">
+  <Hero headline="Welcome" subline="Fast by default" />
+
+  <!-- Hydrate immediately — critical interactive component -->
+  <SearchBar client:load placeholder="Search docs..." />
+
+  <!-- Hydrate when scrolled into view — below the fold -->
+  <Newsletter client:visible />
+
+  <!-- Hydrate when browser is idle — non-critical -->
+  <Analytics client:idle />
+
+  <!-- Hydrate only on specific media query -->
+  <MobileMenu client:media="(max-width: 768px)" />
+</Layout>
+```
+
+### Content Collections
+
+```typescript
+// src/content/config.ts
+import { defineCollection, z, reference } from 'astro:content';
+
+const blog = defineCollection({
+  type: 'content',
+  schema: ({ image }) => z.object({
+    title: z.string().max(100),
+    description: z.string().max(200),
+    pubDate: z.coerce.date(),
+    updatedDate: z.coerce.date().optional(),
+    author: reference('authors'),
+    tags: z.array(z.string()).default([]),
+    cover: image().optional(),
+    draft: z.boolean().default(false),
+  }),
+});
+
+const authors = defineCollection({
+  type: 'data',
+  schema: z.object({
+    name: z.string(),
+    avatar: z.string().url(),
+    bio: z.string(),
+    social: z.object({
+      twitter: z.string().optional(),
+      github: z.string().optional(),
+    }),
+  }),
+});
+
+export const collections = { blog, authors };
+```
+
+```astro
+---
+// src/pages/blog/[...slug].astro
+import { getCollection } from 'astro:content';
+import BlogPost from '../../layouts/BlogPost.astro';
+
+export async function getStaticPaths() {
+  const posts = await getCollection('blog', ({ data }) => !data.draft);
+  return posts.map((post) => ({
+    params: { slug: post.slug },
+    props: { post },
+  }));
+}
+
+const { post } = Astro.props;
+const { Content, headings } = await post.render();
+---
+
+<BlogPost frontmatter={post.data} headings={headings}>
+  <Content />
+</BlogPost>
+```
+
+### SSR with Server Endpoints
+
+```typescript
+// src/pages/api/search.ts
+import type { APIRoute } from 'astro';
+import { getCollection } from 'astro:content';
+
+export const prerender = false; // opt this route into SSR
+
+export const GET: APIRoute = async ({ url }) => {
+  const query = url.searchParams.get('q')?.toLowerCase() ?? '';
+  if (query.length < 2) {
+    return new Response(JSON.stringify({ results: [] }), {
+      headers: { 'Content-Type': 'application/json' },
+    });
+  }
+
+  const posts = await getCollection('blog');
+  const results = posts
+    .filter((p) =>
+      p.data.title.toLowerCase().includes(query) ||
+      p.data.description.toLowerCase().includes(query)
+    )
+    .slice(0, 10)
+    .map((p) => ({ title: p.data.title, slug: p.slug, description: p.data.description }));
+
+  return new Response(JSON.stringify({ results }), {
+    headers: { 'Content-Type': 'application/json', 'Cache-Control': 'public, max-age=60' },
+  });
+};
+```
+
+### View Transitions
+
+```astro
+---
+// src/layouts/Base.astro
+import { ViewTransitions } from 'astro:transitions';
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <ViewTransitions />
+  </head>
+  <body>
+    <header transition:persist>
+      <nav><!-- persists across page navigations --></nav>
+    </header>
+
+    <main transition:animate="slide">
+      <slot />
+    </main>
+  </body>
+</html>
+```
+
+### Custom Integration
+
+```typescript
+// integrations/reading-time.ts
+import type { AstroIntegration } from 'astro';
+import { toString } from 'mdast-util-to-string';
+import getReadingTime from 'reading-time';
+
+export function readingTime(): AstroIntegration {
+  return {
+    name: 'reading-time',
+    hooks: {
+      'astro:config:setup': ({ updateConfig }) => {
+        updateConfig({
+          markdown: {
+            remarkPlugins: [
+              () => (tree: any, file: any) => {
+                const text = toString(tree);
+                const { minutes } = getReadingTime(text);
+                file.data.astro.frontmatter.readingTime = Math.ceil(minutes);
+              },
+            ],
+          },
+        });
+      },
+    },
+  };
+}
+```
+
+## Examples
+
+| Directive | When It Hydrates | Use Case |
+|-----------|-----------------|----------|
+| `client:load` | Immediately on page load | Search bar, auth widget |
+| `client:idle` | After page is idle | Analytics, chat widget |
+| `client:visible` | When scrolled into viewport | Below-fold interactive content |
+| `client:media="(max-width: 768px)"` | On matching media query | Mobile-only components |
+| `client:only="react"` | Client-only, never SSR | Components using browser APIs |
+| No directive | Never (static HTML) | Headers, footers, content |
+
+## Checklist
+- [ ] Static components have no `client:*` directive (zero JS by default)
+- [ ] Interactive islands use the least aggressive hydration directive needed
+- [ ] Content collections have Zod schemas with validation in `config.ts`
+- [ ] `getStaticPaths` filters out draft content in production
+- [ ] SSR routes explicitly set `export const prerender = false`
+- [ ] View transitions enabled with `transition:persist` on shared elements
+- [ ] Images use `astro:assets` for automatic optimization
+- [ ] Sitemap integration configured to exclude private routes

package/assets/skills/auth-patterns.md

@@ -0,0 +1,248 @@
+---
+name: auth-patterns
+description: Implement authentication and authorization — JWT, refresh tokens, RBAC, OAuth2 PKCE, and API keys.
+---
+
+# Auth Patterns
+
+## When to Use
+
+Apply these patterns whenever your application has users, API consumers, or any
+protected resource. Authentication (who are you?) and authorization (what can
+you do?) are distinct concerns — implement both. Getting auth wrong means data
+breaches, account takeovers, and compliance failures.
+
+## How It Works
+
+### 1. JWT Access Tokens
+
+Short-lived tokens (15 minutes) for API authentication. Stateless verification
+with no database lookup per request.
+
+```typescript
+import jwt from 'jsonwebtoken';
+
+interface TokenPayload {
+  sub: string;       // user ID
+  role: string;
+  permissions: string[];
+}
+
+function signAccessToken(user: User): string {
+  const payload: TokenPayload = {
+    sub: user.id,
+    role: user.role,
+    permissions: user.permissions,
+  };
+  return jwt.sign(payload, process.env.JWT_SECRET!, { expiresIn: '15m' });
+}
+
+function verifyAccessToken(token: string): TokenPayload {
+  return jwt.verify(token, process.env.JWT_SECRET!) as TokenPayload;
+}
+```
+
+Never put sensitive data (email, password hash, PII) in the JWT payload — it's
+base64 encoded, not encrypted.
+
+### 2. Refresh Tokens
+
+Long-lived (7-30 days), stored in the database, rotated on each use.
+
+```typescript
+async function refreshTokens(refreshToken: string) {
+  const stored = await db.refreshToken.findUnique({
+    where: { token: hashToken(refreshToken) },
+    include: { user: true },
+  });
+
+  if (!stored || stored.expiresAt < new Date()) {
+    throw new AuthError('Invalid refresh token');
+  }
+
+  // Rotate: delete old, create new
+  await db.refreshToken.delete({ where: { id: stored.id } });
+
+  const newRefreshToken = generateSecureToken();
+  await db.refreshToken.create({
+    data: {
+      token: hashToken(newRefreshToken),
+      userId: stored.userId,
+      expiresAt: addDays(new Date(), 7),
+    },
+  });
+
+  const accessToken = signAccessToken(stored.user);
+  return { accessToken, refreshToken: newRefreshToken };
+}
+```
+
+Store refresh tokens as hashed values. If the database leaks, raw tokens remain
+unknown.
+
+### 3. RBAC — Role-Based Access Control
+
+Define roles and permissions, check at the middleware level.
+
+```typescript
+const ROLE_PERMISSIONS: Record<string, string[]> = {
+  admin:  ['users:read', 'users:write', 'billing:manage', 'settings:write'],
+  editor: ['users:read', 'content:write', 'content:publish'],
+  viewer: ['users:read', 'content:read'],
+};
+
+function requirePermission(...required: string[]) {
+  return (req: Request, res: Response, next: NextFunction) => {
+    const userPermissions = req.user.permissions;
+    const hasAll = required.every((p) => userPermissions.includes(p));
+
+    if (!hasAll) {
+      return res.status(403).json({
+        error: { code: 'FORBIDDEN', message: 'Insufficient permissions' },
+      });
+    }
+    next();
+  };
+}
+
+// Usage
+router.delete('/users/:id', requirePermission('users:write'), deleteUser);
+router.get('/users', requirePermission('users:read'), listUsers);
+```
+
+### 4. Session Management
+
+For server-rendered apps, use secure HTTP-only cookies.
+
+```typescript
+app.use(session({
+  store: new RedisStore({ client: redisClient }),
+  secret: process.env.SESSION_SECRET!,
+  resave: false,
+  saveUninitialized: false,
+  cookie: {
+    httpOnly: true,       // JavaScript can't read it
+    secure: true,         // HTTPS only
+    sameSite: 'lax',      // CSRF protection
+    maxAge: 24 * 60 * 60 * 1000, // 24 hours
+  },
+}));
+```
+
+### 5. OAuth2 PKCE Flow
+
+For SPAs and mobile apps that can't securely store client secrets.
+
+```typescript
+// Step 1: Generate code verifier and challenge
+function generatePKCE() {
+  const verifier = crypto.randomBytes(32).toString('base64url');
+  const challenge = crypto
+    .createHash('sha256')
+    .update(verifier)
+    .digest('base64url');
+  return { verifier, challenge };
+}
+
+// Step 2: Redirect to authorization server
+const { verifier, challenge } = generatePKCE();
+sessionStorage.setItem('pkce_verifier', verifier);
+
+const authUrl = new URL('https://provider.com/authorize');
+authUrl.searchParams.set('response_type', 'code');
+authUrl.searchParams.set('client_id', CLIENT_ID);
+authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
+authUrl.searchParams.set('code_challenge', challenge);
+authUrl.searchParams.set('code_challenge_method', 'S256');
+authUrl.searchParams.set('scope', 'openid profile email');
+
+// Step 3: Exchange code for tokens (callback handler)
+async function handleCallback(code: string) {
+  const verifier = sessionStorage.getItem('pkce_verifier');
+  const response = await fetch('https://provider.com/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: REDIRECT_URI,
+      client_id: CLIENT_ID,
+      code_verifier: verifier!,
+    }),
+  });
+  return response.json(); // { access_token, refresh_token, id_token }
+}
+```
+
+### 6. API Keys
+
+For server-to-server authentication. Simpler than OAuth, appropriate when the
+caller is a trusted backend.
+
+```typescript
+// Generation
+function generateApiKey(): { key: string; hash: string } {
+  const prefix = 'bs_live_';
+  const secret = crypto.randomBytes(24).toString('base64url');
+  const key = `${prefix}${secret}`;
+  const hash = crypto.createHash('sha256').update(key).digest('hex');
+  return { key, hash }; // show key once, store hash
+}
+
+// Middleware
+function authenticateApiKey(req: Request, res: Response, next: NextFunction) {
+  const key = req.headers['x-api-key'] as string;
+  if (!key) return res.status(401).json({ error: 'API key required' });
+
+  const hash = crypto.createHash('sha256').update(key).digest('hex');
+  const record = await db.apiKey.findUnique({ where: { hash } });
+
+  if (!record || record.revokedAt) {
+    return res.status(401).json({ error: 'Invalid API key' });
+  }
+
+  req.apiKeyOwner = record.userId;
+  next();
+}
+```
+
+### 7. Authentication Middleware
+
+```typescript
+function authenticate(req: Request, res: Response, next: NextFunction) {
+  const header = req.headers.authorization;
+  if (!header?.startsWith('Bearer ')) {
+    return res.status(401).json({ error: { code: 'UNAUTHENTICATED' } });
+  }
+
+  try {
+    const token = header.slice(7);
+    req.user = verifyAccessToken(token);
+    next();
+  } catch {
+    return res.status(401).json({ error: { code: 'TOKEN_EXPIRED' } });
+  }
+}
+```
+
+## Examples
+
+| Scenario | Pattern | Token lifetime |
+|----------|---------|---------------|
+| SPA calling own API | JWT access + refresh | 15min / 7 days |
+| SSR web app | HTTP-only session cookie | 24 hours |
+| Mobile app, third-party login | OAuth2 PKCE | Provider-dependent |
+| Backend-to-backend | API key | Until revoked |
+| Microservice mesh | mTLS or JWT with service accounts | 1 hour |
+
+## Checklist
+
+- [ ] Access tokens expire in 15 minutes or less
+- [ ] Refresh tokens are hashed in the database and rotated on use
+- [ ] Passwords are hashed with bcrypt/argon2 (cost factor >= 10)
+- [ ] RBAC permissions are checked in middleware, not scattered in handlers
+- [ ] Cookies use `httpOnly`, `secure`, and `sameSite` flags
+- [ ] OAuth2 flows use PKCE, never implicit grant
+- [ ] API keys are prefixed (`bs_live_`, `bs_test_`) for identification
+- [ ] Failed login attempts are rate-limited (5 per minute per IP)
+- [ ] Token secrets and session secrets come from environment variables, never source code

package/assets/skills/aws-patterns.md

@@ -0,0 +1,171 @@
+---
+name: aws-patterns
+description: AWS patterns for S3, Lambda, SQS, DynamoDB, CloudFront, and IAM best practices.
+---
+
+# AWS Patterns
+
+## When to Use
+Apply when architecting or operating workloads on AWS. Covers the most common building blocks: S3 for storage, Lambda for compute, SQS for decoupling, DynamoDB for NoSQL, CloudFront for CDN, and IAM for least-privilege access. Use this skill when designing new services, reviewing infrastructure, or optimizing AWS costs.
+
+## How It Works
+
+### S3 -- Object Storage
+
+```typescript
+import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+const s3 = new S3Client({ region: "us-east-1" });
+
+// Upload with server-side encryption
+await s3.send(new PutObjectCommand({
+  Bucket: "my-app-uploads",
+  Key: `users/${userId}/avatar.png`,
+  Body: fileBuffer,
+  ContentType: "image/png",
+  ServerSideEncryption: "AES256",
+}));
+
+// Presigned URL for client-side upload (bypass your server)
+const presignedUrl = await getSignedUrl(s3, new PutObjectCommand({
+  Bucket: "my-app-uploads",
+  Key: `users/${userId}/avatar.png`,
+  ContentType: "image/png",
+}), { expiresIn: 300 });
+```
+
+Rules: enable versioning, lifecycle policies to Glacier after 90 days, block all public access, use presigned URLs.
+
+### Lambda -- Stateless Functions
+
+```typescript
+import { SQSEvent, Context } from "aws-lambda";
+
+export const handler = async (event: SQSEvent, context: Context) => {
+  const failures: { itemIdentifier: string }[] = [];
+
+  for (const record of event.Records) {
+    try {
+      const order = JSON.parse(record.body);
+      await processOrder(order);
+    } catch {
+      failures.push({ itemIdentifier: record.messageId });
+    }
+  }
+  return { batchItemFailures: failures };
+};
+```
+
+Best practices: keep handler thin, set `reservedConcurrency`, use ARM64 (Graviton) for 20% savings, set timeout to 2x p99.
+
+### SQS -- Decouple Services
+
+```typescript
+import { SQSClient, SendMessageCommand } from "@aws-sdk/client-sqs";
+
+const sqs = new SQSClient({ region: "us-east-1" });
+
+await sqs.send(new SendMessageCommand({
+  QueueUrl: process.env.ORDER_QUEUE_URL,
+  MessageBody: JSON.stringify({ orderId, action: "fulfill" }),
+  MessageGroupId: orderId,
+  MessageDeduplicationId: `${orderId}-fulfill`,
+}));
+```
+
+Use Standard queues for throughput, FIFO for ordering. Always configure a Dead Letter Queue with `maxReceiveCount: 3`.
+
+### DynamoDB -- Single-Table Design
+
+```typescript
+// PK = entity type + ID, SK = relationship
+await dynamo.put({
+  TableName: "AppTable",
+  Item: {
+    PK: `USER#${userId}`,
+    SK: `ORDER#${orderId}`,
+    GSI1PK: `ORDER#${orderId}`,
+    GSI1SK: `USER#${userId}`,
+    type: "order",
+    total: 4599,
+    status: "pending",
+    createdAt: new Date().toISOString(),
+  },
+});
+
+// Query all orders for a user
+const orders = await dynamo.query({
+  TableName: "AppTable",
+  KeyConditionExpression: "PK = :pk AND begins_with(SK, :sk)",
+  ExpressionAttributeValues: { ":pk": `USER#${userId}`, ":sk": "ORDER#" },
+});
+```
+
+Design access patterns first, then the table. Use GSIs for inverse lookups. Avoid scans.
+
+### CloudFront -- CDN and Edge
+
+```yaml
+Origins:
+  - Id: s3-static
+    DomainName: my-app-static.s3.amazonaws.com
+    S3OriginConfig:
+      OriginAccessIdentity: origin-access-identity/cloudfront/EXXXXX
+  - Id: api-origin
+    DomainName: api.my-app.com
+    CustomOriginConfig:
+      OriginProtocolPolicy: https-only
+CacheBehaviors:
+  - PathPattern: /api/*
+    TargetOriginId: api-origin
+    CachePolicyId: 4135ea2d-...  # CachingDisabled
+  - PathPattern: /*
+    TargetOriginId: s3-static
+    CachePolicyId: 658327ea-...  # CachingOptimized
+```
+
+### IAM -- Least Privilege
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [{
+    "Effect": "Allow",
+    "Action": ["s3:GetObject", "s3:PutObject"],
+    "Resource": "arn:aws:s3:::my-app-uploads/users/${aws:PrincipalTag/userId}/*"
+  }]
+}
+```
+
+Never use `*` for actions or resources in production. Use IAM Roles for Lambda/EC2/ECS, not access keys.
+
+### Cost Optimization
+
+| Technique | Savings | Effort |
+|-----------|---------|--------|
+| Graviton (ARM) Lambda/EC2 | 20-40% | Low |
+| S3 Intelligent-Tiering | 30-70% cold data | Low |
+| Reserved Instances / Savings Plans | 30-60% steady-state | Medium |
+| Right-size Lambda memory | 10-50% | Low |
+| Spot Instances for batch | 60-90% | Medium |
+
+## Examples
+
+| Service | Pattern | Key Consideration |
+|---------|---------|-------------------|
+| S3 | Presigned uploads | Never make buckets public |
+| Lambda | SQS trigger + partial batch | Return batchItemFailures |
+| SQS | FIFO + DLQ | Monitor oldest message age |
+| DynamoDB | Single-table design | Access patterns first |
+| CloudFront | Static + API origins | Disable cache for API |
+
+## Checklist
+- [ ] S3 buckets have versioning, encryption, public access blocked
+- [ ] Lambda functions have reserved concurrency and DLQ
+- [ ] SQS queues have DLQs with `maxReceiveCount` set
+- [ ] DynamoDB access patterns documented before table design
+- [ ] CloudFront serves static assets; API bypasses cache
+- [ ] IAM policies follow least privilege -- no `*` actions
+- [ ] CloudWatch alarms on Lambda errors, SQS age, DynamoDB throttles
+- [ ] Infrastructure defined in IaC (CDK, Terraform, or SAM)