@ultrakit/ultrakit 0.0.0

package/dist/template/.opencode/skill/pdf-extract/SKILL.md

@@ -0,0 +1,438 @@
+---
+name: pdf-extract
+description: Use when extracting text, images, tables, or metadata from PDF files. MUST load to choose the correct extraction library based on PDF complexity — simple text vs structured data vs complex layouts.
+version: 1.0.0
+tags: [research, integration]
+dependencies: []
+---
+
+# PDF Content Extraction
+
+## When to Use
+
+- When you need to extract text, images, tables, or metadata from PDF files.
+
+## When NOT to Use
+
+- When the source data is already available in a non-PDF, structured format.
+
+
+## Quick Decision Guide
+
+| Use Case                    | Recommended Library | Why                                |
+| --------------------------- | ------------------- | ---------------------------------- |
+| Simple text extraction      | `pdf-parse` (v2+)   | Fast, lightweight, pure TypeScript |
+| Complex layouts/coordinates | `pdfjs-dist`        | Full control, precise positioning  |
+| Tables/tabular data         | `pdf-data-parser`   | Built for grid-based content       |
+| Forms (XFA)                 | `pdf-lib` + custom  | Form field extraction              |
+| Browser + Node.js           | `pdf-parse` v2      | Cross-platform, works everywhere   |
+
+---
+
+## Library 1: pdf-parse (Recommended for Text)
+
+**Best for:** Simple text extraction, metadata, fast processing
+
+### Installation
+
+```bash
+npm install pdf-parse
+```
+
+### Basic Text Extraction
+
+```typescript
+import { PDFParse } from "pdf-parse";
+import { readFile } from "fs/promises";
+
+async function extractText(filePath: string): Promise<string> {
+  const parser = new PDFParse();
+  const buffer = await readFile(filePath);
+
+  const result = await parser.parse(buffer);
+  return result.text;
+}
+
+// Usage
+const text = await extractText("./document.pdf");
+console.log(text);
+```
+
+### Extract with Metadata
+
+```typescript
+import { PDFParse } from "pdf-parse";
+
+async function extractWithMetadata(filePath: string) {
+  const parser = new PDFParse();
+  const buffer = await readFile(filePath);
+
+  const result = await parser.parse(buffer);
+
+  return {
+    text: result.text,
+    info: result.info, // Document metadata
+    numpages: result.numpages,
+    version: result.version,
+  };
+}
+```
+
+### Extract Specific Pages
+
+```typescript
+import { PDFParse } from "pdf-parse";
+
+async function extractPage(filePath: string, pageNum: number) {
+  const parser = new PDFParse();
+  const buffer = await readFile(filePath);
+
+  const result = await parser.parse(buffer, {
+    max: pageNum,
+    min: pageNum,
+  });
+
+  return result.text;
+}
+```
+
+### URL-based Extraction (without downloading full file)
+
+```typescript
+import { getHeader } from "pdf-parse/node";
+
+async function checkPDFHeaders(url: string) {
+  // Check file size and headers before downloading
+  const headers = await getHeader(url, true);
+  console.log(`File size: ${headers.size} bytes`);
+
+  if (headers.size > 10 * 1024 * 1024) {
+    console.warn("Large PDF - consider streaming");
+  }
+}
+```
+
+---
+
+## Library 2: pdfjs-dist (Mozilla PDF.js)
+
+**Best for:** Complex layouts, coordinates, images, page-by-page control
+
+### Installation
+
+```bash
+npm install pdfjs-dist
+```
+
+### Basic Text Extraction with Coordinates
+
+```typescript
+import * as pdfjsLib from "pdfjs-dist/legacy/build/pdf.mjs";
+import { readFile } from "fs/promises";
+import path from "path";
+
+async function extractWithCoordinates(pdfPath: string) {
+  const data = await readFile(pdfPath);
+  const dataArray = new Uint8Array(data);
+
+  const pdfDocument = await pdfjsLib.getDocument({
+    data: dataArray,
+    standardFontDataUrl: path.join(process.cwd(), "node_modules/pdfjs-dist/standard_fonts/"),
+  }).promise;
+
+  const numPages = pdfDocument.numPages;
+  const results = [];
+
+  for (let pageNum = 1; pageNum <= numPages; pageNum++) {
+    const page = await pdfDocument.getPage(pageNum);
+    const textContent = await page.getTextContent();
+
+    const pageText = textContent.items.map((item: any) => ({
+      text: item.str,
+      x: item.transform[4],
+      y: item.transform[5],
+      font: item.fontName,
+      width: item.width,
+      height: item.height,
+    }));
+
+    results.push({
+      page: pageNum,
+      items: pageText,
+    });
+  }
+
+  return results;
+}
+```
+
+### Extract Images from PDF
+
+```typescript
+import * as pdfjsLib from "pdfjs-dist/legacy/build/pdf.mjs";
+
+async function extractImages(pdfPath: string) {
+  const data = await readFile(pdfPath);
+  const pdfDocument = await pdfjsLib.getDocument({ data: new Uint8Array(data) }).promise;
+
+  const images = [];
+
+  for (let pageNum = 1; pageNum <= pdfDocument.numPages; pageNum++) {
+    const page = await pdfDocument.getPage(pageNum);
+    const ops = await page.getOperatorList();
+
+    for (let i = 0; i < ops.fnArray.length; i++) {
+      if (ops.fnArray[i] === pdfjsLib.OPS.paintImageXObject) {
+        const imageName = ops.argsArray[i][0];
+        const image = await page.objs.get(imageName);
+
+        images.push({
+          page: pageNum,
+          name: imageName,
+          width: image.width,
+          height: image.height,
+          data: image.data, // Raw image data
+        });
+      }
+    }
+  }
+
+  return images;
+}
+```
+
+### Render Page to Image
+
+```typescript
+import * as pdfjsLib from "pdfjs-dist/legacy/build/pdf.mjs";
+import { createCanvas } from "canvas";
+import { writeFile } from "fs/promises";
+
+async function renderPageToImage(pdfPath: string, pageNum: number, outputPath: string) {
+  const data = await readFile(pdfPath);
+  const pdfDocument = await pdfjsLib.getDocument({ data: new Uint8Array(data) }).promise;
+
+  const page = await pdfDocument.getPage(pageNum);
+  const viewport = page.getViewport({ scale: 2.0 }); // Higher scale = better quality
+
+  const canvas = createCanvas(viewport.width, viewport.height);
+  const context = canvas.getContext("2d");
+
+  await page.render({
+    canvasContext: context,
+    viewport: viewport,
+  }).promise;
+
+  const buffer = canvas.toBuffer("image/png");
+  await writeFile(outputPath, buffer);
+
+  console.log(`Page ${pageNum} saved to ${outputPath}`);
+}
+```
+
+---
+
+## Library 3: pdf-data-parser (Tables)
+
+**Best for:** Tabular data, structured grid content
+
+### Installation
+
+```bash
+npm install pdf-data-parser
+```
+
+### Extract Tables
+
+```typescript
+import { PdfDataParser } from "pdf-data-parser";
+
+async function extractTables(pdfPath: string) {
+  const parser = new PdfDataParser({
+    url: pdfPath,
+    // Options
+    heading: "Table Title", // Filter to specific table
+    cells: 3, // Minimum cells per row
+    headers: ["Name", "Amount"], // Expected headers
+    repeating: false, // Handle repeating headers
+  });
+
+  const rows = await parser.parse();
+  return rows; // Array of arrays
+}
+```
+
+### Stream Large PDFs
+
+```typescript
+import { PdfDataReader } from "pdf-data-parser";
+import { createWriteStream } from "fs";
+
+async function streamToCSV(pdfPath: string, outputPath: string) {
+  const reader = new PdfDataReader({
+    url: pdfPath,
+    cells: 2,
+  });
+
+  const output = createWriteStream(outputPath);
+
+  reader.on("data", (row: string[]) => {
+    output.write(row.join(",") + "\n");
+  });
+
+  reader.on("end", () => {
+    output.end();
+    console.log("CSV created");
+  });
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Error Handling
+
+```typescript
+async function safeExtract(filePath: string) {
+  try {
+    const buffer = await readFile(filePath);
+
+    // Validate PDF header
+    const header = buffer.slice(0, 5).toString();
+    if (header !== "%PDF-") {
+      throw new Error("Invalid PDF file");
+    }
+
+    const result = await parser.parse(buffer);
+    return result;
+  } catch (error) {
+    if (error.message.includes("password")) {
+      throw new Error("PDF is password protected");
+    }
+    if (error.message.includes("damaged")) {
+      throw new Error("PDF is corrupted");
+    }
+    throw error;
+  }
+}
+```
+
+### 2. Memory Management (Large Files)
+
+```typescript
+// For large PDFs, process page by page
+async function extractLargePDF(pdfPath: string) {
+  const data = await readFile(pdfPath);
+  const pdfDocument = await pdfjsLib.getDocument({ data: new Uint8Array(data) }).promise;
+
+  // Don't load all pages at once
+  for (let i = 1; i <= pdfDocument.numPages; i++) {
+    const page = await pdfDocument.getPage(i);
+    const text = await page.getTextContent();
+
+    // Process immediately, don't accumulate
+    await processPageText(text);
+
+    // Clean up
+    page.cleanup();
+  }
+}
+```
+
+### 3. Text Cleaning
+
+```typescript
+function cleanExtractedText(text: string): string {
+  return text
+    .replace(/\s+/g, " ") // Normalize whitespace
+    .replace(/[^\x20-\x7E\n]/g, "") // Remove non-printable chars
+    .trim();
+}
+```
+
+### 4. Performance Tips
+
+```typescript
+// Parallel extraction for multiple files
+async function extractMultiple(files: string[]) {
+  const results = await Promise.all(
+    files.map((file) => extractText(file).catch((err) => ({ file, error: err }))),
+  );
+  return results;
+}
+
+// Use streams for very large files
+import { createReadStream } from "fs";
+import { PdfDataReader } from "pdf-data-parser";
+```
+
+---
+
+## Common Issues & Solutions
+
+| Issue                | Cause                 | Solution                              |
+| -------------------- | --------------------- | ------------------------------------- |
+| Text appears garbled | Encoding issue        | Use pdfjs-dist with explicit encoding |
+| Missing text         | Scanned image PDF     | Use OCR (Tesseract) before extraction |
+| Out of memory        | Large PDF             | Stream processing, page-by-page       |
+| Password error       | Encrypted PDF         | Use `pdf-lib` to decrypt first        |
+| Missing coordinates  | Wrong library         | Use pdfjs-dist for positioning        |
+| Table structure lost | Plain text extraction | Use pdf-data-parser                   |
+| Font warnings        | Missing fonts         | Set `standardFontDataUrl` option      |
+
+---
+
+## Complete Example: Document Processor
+
+```typescript
+import { PDFParse } from "pdf-parse";
+import { readFile } from "fs/promises";
+
+interface DocumentResult {
+  text: string;
+  metadata: {
+    title?: string;
+    author?: string;
+    pages: number;
+    creationDate?: Date;
+  };
+  summary: string;
+}
+
+async function processDocument(filePath: string): Promise<DocumentResult> {
+  const parser = new PDFParse();
+  const buffer = await readFile(filePath);
+
+  const result = await parser.parse(buffer);
+
+  // Generate summary (first 500 chars)
+  const summary = result.text.replace(/\s+/g, " ").slice(0, 500).trim() + "...";
+
+  return {
+    text: result.text,
+    metadata: {
+      title: result.info?.Title,
+      author: result.info?.Author,
+      pages: result.numpages,
+      creationDate: result.info?.CreationDate ? new Date(result.info.CreationDate) : undefined,
+    },
+    summary,
+  };
+}
+
+// Usage
+const doc = await processDocument("./report.pdf");
+console.log(`Document: ${doc.metadata.title}`);
+console.log(`Pages: ${doc.metadata.pages}`);
+console.log(`Summary: ${doc.summary}`);
+```
+
+---
+
+## References
+
+- [pdf-parse npm](https://www.npmjs.com/package/pdf-parse)
+- [pdfjs-dist docs](https://mozilla.github.io/pdf.js/)
+- [pdf-data-parser GitHub](https://github.com/drewletcher/pdf-data-parser)
+- [pdf-lib GitHub](https://github.com/Hopding/pdf-lib)

package/dist/template/.opencode/skill/performance-optimization/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: performance-optimization
+description: Use when profiling, optimizing, or adding performance budgets to applications — covers measure-first workflow, Core Web Vitals, common anti-patterns, and performance regression prevention
+version: 1.0.0
+tags: [performance, code-quality]
+dependencies: []
+---
+
+# Performance Optimization
+
+> **Replaces** premature optimization and gut-feeling tuning with measurement-driven improvements that target actual bottlenecks
+
+## When to Use
+
+- Application is measurably slow (user reports, metrics, profiler data)
+- Setting up performance budgets for a new project
+- Reviewing code for common performance anti-patterns
+- Performance regression detected in CI or monitoring
+
+## When NOT to Use
+
+- No evidence of a performance problem — premature optimization wastes time
+- Micro-optimizations that save nanoseconds in non-hot paths
+- Choosing "fast" over "correct" — correctness first, always
+
+## Overview
+
+Performance optimization is an empirical process. Measure, identify, fix, verify. Never optimize without profiling first.
+
+**Core principle:** Measure before optimizing. Optimize the bottleneck, not the code you happen to be reading. Verify the improvement with numbers.
+
+## Measure-First Workflow
+
+```
+1. MEASURE   — Profile to identify actual bottlenecks (not guessed ones)
+2. IDENTIFY  — Find the specific hot path or resource constraint
+3. FIX       — Apply targeted optimization to the bottleneck
+4. VERIFY    — Measure again to confirm improvement
+5. GUARD     — Add budget/benchmark to prevent regression
+```
+
+**Rule:** Skip to step 3 only if you have measurement data that justifies the optimization.
+
+## Performance Targets
+
+### Core Web Vitals (Web)
+
+| Metric                          | Good    | Needs Improvement | Poor    |
+| ------------------------------- | ------- | ----------------- | ------- |
+| LCP (Largest Contentful Paint)  | ≤ 2.5s  | ≤ 4.0s            | > 4.0s  |
+| INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms           | > 500ms |
+| CLS (Cumulative Layout Shift)   | ≤ 0.1   | ≤ 0.25            | > 0.25  |
+
+### General Targets
+
+| Context             | Target       | Measure                |
+| ------------------- | ------------ | ---------------------- |
+| API response (p95)  | < 200ms      | Server-side timing     |
+| CLI command startup | < 500ms      | `time` or `perf_hooks` |
+| Build time          | < 60s        | CI pipeline metrics    |
+| Bundle size (JS)    | < 200KB gzip | Bundler output         |
+| Database query      | < 50ms       | Query EXPLAIN + timing |
+
+## Common Anti-Patterns & Fixes
+
+### N+1 Queries
+
+```typescript
+// ❌ N+1: One query per user
+const users = await db.query("SELECT * FROM users");
+for (const user of users) {
+  user.posts = await db.query("SELECT * FROM posts WHERE user_id = ?", [user.id]);
+}
+
+// ✅ Batch: Two queries total
+const users = await db.query("SELECT * FROM users");
+const userIds = users.map((u) => u.id);
+const posts = await db.query("SELECT * FROM posts WHERE user_id IN (?)", [userIds]);
+// Group posts by user_id in application code
+```
+
+### Unbounded Fetching
+
+```typescript
+// ❌ Fetch everything
+const allItems = await db.query("SELECT * FROM items");
+
+// ✅ Paginate
+const items = await db.query("SELECT * FROM items LIMIT ? OFFSET ?", [pageSize, offset]);
+```
+
+### Missing Memoization
+
+```typescript
+// ❌ Recompute on every render
+function ExpensiveList({ items }) {
+  const sorted = items.sort((a, b) => complexSort(a, b)); // sorts on every render
+  return <List items={sorted} />;
+}
+
+// ✅ Memoize expensive computation
+function ExpensiveList({ items }) {
+  const sorted = useMemo(
+    () => [...items].sort((a, b) => complexSort(a, b)),
+    [items]
+  );
+  return <List items={sorted} />;
+}
+```
+
+### Large Bundle Size
+
+```typescript
+// ❌ Import entire library
+import _ from "lodash";
+const result = _.debounce(fn, 300);
+
+// ✅ Import only what you need
+import debounce from "lodash/debounce";
+const result = debounce(fn, 300);
+
+// ✅✅ Use native (no dependency)
+function debounce(fn, ms) {
+  /* ... */
+}
+```
+
+### Missing Image Optimization
+
+```html
+<!-- ❌ Unoptimized -->
+<img src="hero.png" />
+
+<!-- ✅ Optimized -->
+<img
+  src="hero.webp"
+  srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w"
+  sizes="(max-width: 600px) 400px, (max-width: 1024px) 800px, 1200px"
+  loading="lazy"
+  decoding="async"
+  width="1200"
+  height="630"
+  alt="Hero image"
+/>
+```
+
+### Unnecessary Re-renders (React)
+
+```typescript
+// ❌ New object every render causes child re-render
+function Parent() {
+  return <Child style={{ color: 'red' }} onClick={() => doThing()} />;
+}
+
+// ✅ Stable references
+const style = { color: 'red' };
+function Parent() {
+  const handleClick = useCallback(() => doThing(), []);
+  return <Child style={style} onClick={handleClick} />;
+}
+```
+
+## Profiling Tools
+
+| Context          | Tool                             | What It Shows                     |
+| ---------------- | -------------------------------- | --------------------------------- |
+| Web (browser)    | Chrome DevTools Performance      | Paint, scripting, layout, network |
+| Web (field data) | CrUX, PageSpeed Insights         | Real-user Core Web Vitals         |
+| Node.js          | `node --prof` + `--prof-process` | V8 profiling ticks per function   |
+| Node.js          | `clinic.js`                      | Flamegraphs, event loop delays    |
+| React            | React DevTools Profiler          | Component render times            |
+| SQL              | `EXPLAIN ANALYZE`                | Query execution plan              |
+| Bundle           | `source-map-explorer`            | Module size breakdown             |
+| Network          | `lighthouse`                     | Loading performance audit         |
+
+## Performance Budget
+
+### Setting Budgets
+
+```json
+{
+  "budgets": [
+    { "metric": "js-bundle", "max": "200KB", "warn": "150KB" },
+    { "metric": "css-bundle", "max": "50KB", "warn": "40KB" },
+    { "metric": "lcp", "max": "2500ms", "warn": "2000ms" },
+    { "metric": "api-p95", "max": "200ms", "warn": "150ms" }
+  ]
+}
+```
+
+### Enforcing Budgets in CI
+
+```yaml
+- name: Check bundle size
+  run: |
+    npx bundlesize --config .bundlesizerc.json
+
+- name: Lighthouse audit
+  run: |
+    npx lighthouse $URL --output json --chrome-flags="--headless"
+    # Parse and assert against budgets
+```
+
+## Common Rationalizations
+
+| Excuse                            | Rebuttal                                                                           |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| "It's fast enough on my machine"  | Test on low-end devices and slow networks. Your machine isn't representative.      |
+| "We'll optimize later"            | Performance debt compounds. Set budgets now, optimize when they're breached.       |
+| "This micro-optimization matters" | Profile first. If it's not in the hot path, it doesn't matter.                     |
+| "Users won't notice 200ms"        | Studies show 100ms delays reduce conversions. Users notice more than you think.    |
+| "Adding metrics is overhead"      | The overhead of measurement is trivial compared to the cost of blind optimization. |
+| "Caching will fix it"             | Caching masks problems. Fix the root cause, then add caching as defense.           |
+
+## Red Flags — STOP
+
+- Optimizing without profiling data
+- Adding caching to mask a fundamentally slow operation
+- Micro-optimizing code that runs once per request
+- Bundle size growing without review
+- No performance budget or monitoring in place
+- Using `SELECT *` in production queries
+
+## Verification
+
+- [ ] Bottleneck identified with profiling data (not intuition)
+- [ ] Optimization shows measurable improvement in profiler
+- [ ] Performance budget is set and enforced in CI
+- [ ] No regressions in existing benchmarks
+- [ ] Optimization doesn't sacrifice correctness or readability
+
+## See Also
+
+- **react-best-practices** — React-specific performance patterns (server components, bundle optimization)
+- **ci-cd-and-automation** — Enforcing performance budgets in CI
+- **code-simplification** — Simplifying code often improves performance as a side effect