@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/video-processing.md

@@ -0,0 +1,340 @@
+---
+name: video-processing
+description: Video processing patterns with FFmpeg for transcoding, HLS streaming, thumbnail generation, upload handling, and progress tracking.
+---
+
+# Video Processing Patterns
+
+## When to Use
+Apply video processing patterns when your application handles user-uploaded videos, needs adaptive streaming, generates video thumbnails, or transcodes between formats. FFmpeg (via fluent-ffmpeg) is the standard tool for server-side video work. These patterns cover transcoding, HLS/DASH adaptive streaming, thumbnail extraction, chunked upload handling, and progress reporting. Always process videos asynchronously via job queues.
+
+## How It Works
+
+### FFmpeg Transcoding
+
+```typescript
+// src/video/transcoder.ts
+import ffmpeg from 'fluent-ffmpeg';
+import path from 'path';
+
+interface TranscodeOptions {
+  inputPath: string;
+  outputPath: string;
+  width?: number;
+  height?: number;
+  videoBitrate?: string;
+  audioBitrate?: string;
+  format?: 'mp4' | 'webm';
+  onProgress?: (percent: number) => void;
+}
+
+export function transcodeVideo(options: TranscodeOptions): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let command = ffmpeg(options.inputPath)
+      .videoCodec(options.format === 'webm' ? 'libvpx-vp9' : 'libx264')
+      .audioCodec(options.format === 'webm' ? 'libopus' : 'aac')
+      .audioBitrate(options.audioBitrate ?? '128k')
+      .videoBitrate(options.videoBitrate ?? '2500k')
+      .format(options.format ?? 'mp4');
+
+    if (options.width || options.height) {
+      const w = options.width ?? -2;  // -2 = auto, divisible by 2
+      const h = options.height ?? -2;
+      command = command.size(`${w}x${h}`);
+    }
+
+    if (options.format === 'mp4') {
+      command = command.outputOptions([
+        '-preset', 'fast',
+        '-crf', '23',
+        '-movflags', '+faststart',  // optimize for web streaming
+        '-pix_fmt', 'yuv420p',       // compatibility
+      ]);
+    }
+
+    command
+      .on('progress', (progress) => {
+        options.onProgress?.(Math.round(progress.percent ?? 0));
+      })
+      .on('end', () => resolve(options.outputPath))
+      .on('error', (err) => reject(new Error(`Transcode failed: ${err.message}`)))
+      .save(options.outputPath);
+  });
+}
+```
+
+### HLS Adaptive Streaming
+
+```typescript
+// src/video/hls-generator.ts
+import ffmpeg from 'fluent-ffmpeg';
+import fs from 'fs/promises';
+import path from 'path';
+
+interface HlsVariant {
+  width: number;
+  height: number;
+  videoBitrate: string;
+  audioBitrate: string;
+  label: string;
+}
+
+const variants: HlsVariant[] = [
+  { width: 426, height: 240, videoBitrate: '400k', audioBitrate: '64k', label: '240p' },
+  { width: 640, height: 360, videoBitrate: '800k', audioBitrate: '96k', label: '360p' },
+  { width: 854, height: 480, videoBitrate: '1400k', audioBitrate: '128k', label: '480p' },
+  { width: 1280, height: 720, videoBitrate: '2800k', audioBitrate: '128k', label: '720p' },
+  { width: 1920, height: 1080, videoBitrate: '5000k', audioBitrate: '192k', label: '1080p' },
+];
+
+export async function generateHls(
+  inputPath: string,
+  outputDir: string,
+  onProgress?: (variant: string, percent: number) => void
+): Promise<string> {
+  await fs.mkdir(outputDir, { recursive: true });
+
+  // Generate each variant
+  for (const variant of variants) {
+    const variantDir = path.join(outputDir, variant.label);
+    await fs.mkdir(variantDir, { recursive: true });
+
+    await new Promise<void>((resolve, reject) => {
+      ffmpeg(inputPath)
+        .videoCodec('libx264')
+        .audioCodec('aac')
+        .size(`${variant.width}x${variant.height}`)
+        .videoBitrate(variant.videoBitrate)
+        .audioBitrate(variant.audioBitrate)
+        .outputOptions([
+          '-preset', 'fast',
+          '-crf', '23',
+          '-g', '48',                    // keyframe every 2s at 24fps
+          '-keyint_min', '48',
+          '-sc_threshold', '0',
+          '-hls_time', '6',              // 6-second segments
+          '-hls_list_size', '0',         // keep all segments
+          '-hls_segment_filename', path.join(variantDir, 'segment_%03d.ts'),
+          '-f', 'hls',
+        ])
+        .on('progress', (p) => onProgress?.(variant.label, Math.round(p.percent ?? 0)))
+        .on('end', () => resolve())
+        .on('error', (err) => reject(err))
+        .save(path.join(variantDir, 'playlist.m3u8'));
+    });
+  }
+
+  // Generate master playlist
+  const masterPlaylist = generateMasterPlaylist(variants);
+  const masterPath = path.join(outputDir, 'master.m3u8');
+  await fs.writeFile(masterPath, masterPlaylist);
+
+  return masterPath;
+}
+
+function generateMasterPlaylist(variants: HlsVariant[]): string {
+  let content = '#EXTM3U\n#EXT-X-VERSION:3\n\n';
+
+  for (const v of variants) {
+    const bandwidth = parseInt(v.videoBitrate) * 1000;
+    content += `#EXT-X-STREAM-INF:BANDWIDTH=${bandwidth},RESOLUTION=${v.width}x${v.height}\n`;
+    content += `${v.label}/playlist.m3u8\n\n`;
+  }
+
+  return content;
+}
+```
+
+### Thumbnail Generation
+
+```typescript
+// src/video/thumbnails.ts
+import ffmpeg from 'fluent-ffmpeg';
+
+export async function generateThumbnails(
+  inputPath: string,
+  outputDir: string,
+  count: number = 5
+): Promise<string[]> {
+  return new Promise((resolve, reject) => {
+    const filenames: string[] = [];
+
+    ffmpeg(inputPath)
+      .on('filenames', (names) => filenames.push(...names))
+      .on('end', () => resolve(filenames.map((f) => path.join(outputDir, f))))
+      .on('error', (err) => reject(err))
+      .screenshots({
+        count,
+        folder: outputDir,
+        filename: 'thumb_%i.jpg',
+        size: '640x360',
+      });
+  });
+}
+
+// Generate a single thumbnail at specific time
+export async function generateThumbnailAtTime(
+  inputPath: string,
+  outputPath: string,
+  timeSeconds: number
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    ffmpeg(inputPath)
+      .seekInput(timeSeconds)
+      .frames(1)
+      .size('640x360')
+      .on('end', () => resolve(outputPath))
+      .on('error', (err) => reject(err))
+      .save(outputPath);
+  });
+}
+
+// Generate animated GIF preview
+export async function generateGifPreview(
+  inputPath: string,
+  outputPath: string,
+  startTime: number = 0,
+  duration: number = 3
+): Promise<string> {
+  return new Promise((resolve, reject) => {
+    ffmpeg(inputPath)
+      .seekInput(startTime)
+      .duration(duration)
+      .outputOptions([
+        '-vf', 'fps=10,scale=320:-1:flags=lanczos',
+        '-loop', '0',
+      ])
+      .on('end', () => resolve(outputPath))
+      .on('error', (err) => reject(err))
+      .save(outputPath);
+  });
+}
+```
+
+### Video Metadata Extraction
+
+```typescript
+// src/video/metadata.ts
+import ffmpeg from 'fluent-ffmpeg';
+
+export interface VideoMetadata {
+  duration: number;
+  width: number;
+  height: number;
+  fps: number;
+  bitrate: number;
+  codec: string;
+  audioCodec: string;
+  fileSize: number;
+}
+
+export function getVideoMetadata(inputPath: string): Promise<VideoMetadata> {
+  return new Promise((resolve, reject) => {
+    ffmpeg.ffprobe(inputPath, (err, data) => {
+      if (err) return reject(err);
+
+      const videoStream = data.streams.find((s) => s.codec_type === 'video');
+      const audioStream = data.streams.find((s) => s.codec_type === 'audio');
+
+      if (!videoStream) return reject(new Error('No video stream found'));
+
+      resolve({
+        duration: data.format.duration ?? 0,
+        width: videoStream.width ?? 0,
+        height: videoStream.height ?? 0,
+        fps: eval(videoStream.r_frame_rate ?? '0') || 0,
+        bitrate: parseInt(String(data.format.bit_rate ?? '0')),
+        codec: videoStream.codec_name ?? 'unknown',
+        audioCodec: audioStream?.codec_name ?? 'none',
+        fileSize: data.format.size ?? 0,
+      });
+    });
+  });
+}
+```
+
+### Chunked Upload with Resumability
+
+```typescript
+// src/video/upload-handler.ts
+import { Router } from 'express';
+import fs from 'fs/promises';
+import path from 'path';
+
+const router = Router();
+const UPLOAD_DIR = '/tmp/video-uploads';
+
+// Initialize upload
+router.post('/api/videos/upload/init', async (req, res) => {
+  const { filename, fileSize, mimeType } = req.body;
+  const uploadId = crypto.randomUUID();
+  const chunkSize = 5 * 1024 * 1024; // 5MB chunks
+  const totalChunks = Math.ceil(fileSize / chunkSize);
+
+  await fs.mkdir(path.join(UPLOAD_DIR, uploadId), { recursive: true });
+  await db.query(
+    'INSERT INTO uploads (id, filename, file_size, mime_type, total_chunks, status) VALUES ($1,$2,$3,$4,$5,$6)',
+    [uploadId, filename, fileSize, mimeType, totalChunks, 'uploading']
+  );
+
+  res.json({ uploadId, chunkSize, totalChunks });
+});
+
+// Upload a chunk
+router.put('/api/videos/upload/:uploadId/chunk/:index', async (req, res) => {
+  const { uploadId, index } = req.params;
+  const chunkPath = path.join(UPLOAD_DIR, uploadId, `chunk_${index.padStart(5, '0')}`);
+
+  const chunks: Buffer[] = [];
+  for await (const chunk of req) chunks.push(chunk);
+  await fs.writeFile(chunkPath, Buffer.concat(chunks));
+
+  res.json({ received: parseInt(index) });
+});
+
+// Finalize upload — merge chunks and queue processing
+router.post('/api/videos/upload/:uploadId/finalize', async (req, res) => {
+  const { uploadId } = req.params;
+  const uploadDir = path.join(UPLOAD_DIR, uploadId);
+  const chunks = (await fs.readdir(uploadDir)).sort();
+  const outputPath = path.join(UPLOAD_DIR, `${uploadId}.mp4`);
+
+  // Merge chunks
+  const writeStream = require('fs').createWriteStream(outputPath);
+  for (const chunk of chunks) {
+    const data = await fs.readFile(path.join(uploadDir, chunk));
+    writeStream.write(data);
+  }
+  writeStream.end();
+
+  // Clean up chunks
+  await fs.rm(uploadDir, { recursive: true });
+
+  // Queue processing job
+  await videoQueue.add('process', { uploadId, inputPath: outputPath });
+
+  res.json({ uploadId, status: 'processing' });
+});
+
+export default router;
+```
+
+## Examples
+
+| Operation | Tool | Output |
+|-----------|------|--------|
+| Transcode to MP4 | fluent-ffmpeg | Web-optimized MP4 (faststart) |
+| Adaptive streaming | HLS generator | Master playlist + segment files |
+| Thumbnail grid | ffmpeg screenshots | 5 JPEG thumbnails at intervals |
+| GIF preview | ffmpeg filter | 3-second looping GIF |
+| Metadata | ffprobe | Duration, resolution, codec info |
+
+## Checklist
+- [ ] Video processing runs asynchronously via job queue, not in request handler
+- [ ] FFmpeg outputs use `-movflags +faststart` for web MP4 files
+- [ ] HLS segments are 6 seconds with closed GOPs for clean seeking
+- [ ] Multiple quality variants generated for adaptive streaming
+- [ ] Thumbnails generated at evenly spaced intervals
+- [ ] Chunked upload supports resumption on connection failure
+- [ ] Progress reported to client via WebSocket or polling endpoint
+- [ ] Temporary files cleaned up after processing completes

package/assets/skills/vue-patterns.md

@@ -0,0 +1,247 @@
+---
+name: vue-patterns
+description: Vue.js patterns for Composition API, composables, Pinia stores, slots, teleport, and transitions.
+---
+
+# Vue.js Patterns
+
+## When to Use
+
+Apply these patterns when building Vue 3 applications with the Composition API.
+Use this skill for writing composables, managing state with Pinia, designing
+reusable components with slots, rendering outside the DOM tree with Teleport,
+and adding animations with transitions.
+
+## How It Works
+
+### Composition API with `<script setup>`
+
+Use `<script setup>` for all components. It provides better TypeScript inference,
+less boilerplate, and automatic component/directive registration.
+
+```vue
+<script setup lang="ts">
+import { ref, computed, onMounted } from 'vue'
+import { useUserStore } from '@/stores/user'
+
+const props = defineProps<{
+  projectId: string
+  editable?: boolean
+}>()
+
+const emit = defineEmits<{
+  save: [data: ProjectData]
+  cancel: []
+}>()
+
+const userStore = useUserStore()
+const title = ref('')
+const isValid = computed(() => title.value.length >= 3)
+
+onMounted(async () => {
+  const project = await fetchProject(props.projectId)
+  title.value = project.title
+})
+
+function handleSave() {
+  if (isValid.value) {
+    emit('save', { title: title.value })
+  }
+}
+</script>
+```
+
+### Composables
+
+Extract reusable reactive logic into composable functions. Name them `use*`.
+Return reactive refs and methods. Accept refs as arguments for reactivity.
+
+```typescript
+// composables/usePagination.ts
+import { ref, computed, watch, type Ref } from 'vue'
+
+export function usePagination<T>(
+  items: Ref<T[]>,
+  options: { pageSize?: number } = {}
+) {
+  const pageSize = options.pageSize ?? 20
+  const currentPage = ref(1)
+
+  const totalPages = computed(() =>
+    Math.ceil(items.value.length / pageSize)
+  )
+
+  const paginatedItems = computed(() => {
+    const start = (currentPage.value - 1) * pageSize
+    return items.value.slice(start, start + pageSize)
+  })
+
+  function goToPage(page: number) {
+    currentPage.value = Math.max(1, Math.min(page, totalPages.value))
+  }
+
+  // Reset to page 1 when items change
+  watch(items, () => { currentPage.value = 1 })
+
+  return { currentPage, totalPages, paginatedItems, goToPage }
+}
+```
+
+```typescript
+// composables/useAsync.ts
+export function useAsync<T>(fn: () => Promise<T>) {
+  const data = ref<T | null>(null) as Ref<T | null>
+  const error = ref<Error | null>(null)
+  const loading = ref(false)
+
+  async function execute() {
+    loading.value = true
+    error.value = null
+    try {
+      data.value = await fn()
+    } catch (e) {
+      error.value = e instanceof Error ? e : new Error(String(e))
+    } finally {
+      loading.value = false
+    }
+  }
+
+  return { data, error, loading, execute }
+}
+```
+
+### Pinia Stores
+
+Use setup-style stores for full Composition API flexibility. Keep stores focused
+on one domain. Use `storeToRefs` for destructuring without losing reactivity.
+
+```typescript
+// stores/cart.ts
+import { defineStore } from 'pinia'
+import { ref, computed } from 'vue'
+
+export const useCartStore = defineStore('cart', () => {
+  const items = ref<CartItem[]>([])
+
+  const total = computed(() =>
+    items.value.reduce((sum, item) => sum + item.price * item.quantity, 0)
+  )
+
+  const itemCount = computed(() =>
+    items.value.reduce((sum, item) => sum + item.quantity, 0)
+  )
+
+  function addItem(product: Product, quantity = 1) {
+    const existing = items.value.find(i => i.productId === product.id)
+    if (existing) {
+      existing.quantity += quantity
+    } else {
+      items.value.push({ productId: product.id, name: product.name, price: product.price, quantity })
+    }
+  }
+
+  function removeItem(productId: string) {
+    items.value = items.value.filter(i => i.productId !== productId)
+  }
+
+  function clear() {
+    items.value = []
+  }
+
+  return { items, total, itemCount, addItem, removeItem, clear }
+})
+```
+
+### Slots for Composition
+
+Use named slots for layout composition. Use scoped slots to expose data to the
+parent. Default slot content serves as fallback.
+
+```vue
+<!-- BaseCard.vue -->
+<template>
+  <div class="card">
+    <div v-if="$slots.header" class="card-header">
+      <slot name="header" />
+    </div>
+    <div class="card-body">
+      <slot :loading="loading" :error="error" />
+    </div>
+    <div v-if="$slots.footer" class="card-footer">
+      <slot name="footer" />
+    </div>
+  </div>
+</template>
+
+<!-- Usage with scoped slot -->
+<BaseCard>
+  <template #header>User Profile</template>
+  <template #default="{ loading, error }">
+    <Spinner v-if="loading" />
+    <ErrorBanner v-else-if="error" :error="error" />
+    <UserDetails v-else :user="user" />
+  </template>
+</BaseCard>
+```
+
+### Teleport
+
+Use `<Teleport>` to render modals, tooltips, and toasts outside the component's
+DOM hierarchy while keeping them logically owned by the component.
+
+```vue
+<template>
+  <button @click="showModal = true">Open</button>
+  <Teleport to="body">
+    <div v-if="showModal" class="modal-overlay" @click.self="showModal = false">
+      <div class="modal-content">
+        <slot />
+        <button @click="showModal = false">Close</button>
+      </div>
+    </div>
+  </Teleport>
+</template>
+```
+
+### Transitions
+
+Use `<Transition>` for enter/leave animations. Use `<TransitionGroup>` for lists.
+Define CSS classes or use JavaScript hooks for complex animations.
+
+```vue
+<template>
+  <Transition name="fade" mode="out-in">
+    <component :is="currentView" :key="currentView.__name" />
+  </Transition>
+</template>
+
+<style>
+.fade-enter-active, .fade-leave-active { transition: opacity 0.2s ease; }
+.fade-enter-from, .fade-leave-to { opacity: 0; }
+</style>
+```
+
+## Examples
+
+**Pattern: Provide/Inject for deep dependency passing**
+```typescript
+// Parent
+const theme = ref<'light' | 'dark'>('light')
+provide('theme', readonly(theme))
+
+// Deep child
+const theme = inject<Ref<string>>('theme', ref('light'))
+```
+
+## Checklist
+
+- [ ] `<script setup lang="ts">` on every component
+- [ ] Props defined with `defineProps<T>()`, emits with `defineEmits<T>()`
+- [ ] Composables named `use*`, return reactive refs and functions
+- [ ] Pinia stores use setup-style syntax; `storeToRefs` for destructuring
+- [ ] Named slots for layout regions; scoped slots for exposing data
+- [ ] `<Teleport to="body">` for modals, tooltips, and overlays
+- [ ] `<Transition>` with `mode="out-in"` for route/view transitions
+- [ ] `v-model` with `defineModel()` (Vue 3.4+) for two-way binding
+- [ ] `watchEffect` for side effects, `watch` when you need old/new values
+- [ ] `provide/inject` with `readonly()` for deep dependency passing