@girardmedia/bootspring 3.3.2 → 3.4.0

package/assets/skills/markdown-processing.md

@@ -0,0 +1,318 @@
+---
+name: markdown-processing
+description: Markdown processing patterns with remark/rehype, MDX compilation, syntax highlighting, custom plugins, and content pipelines.
+---
+
+# Markdown Processing Patterns
+
+## When to Use
+Use these patterns when building documentation sites, blogs, CMSs, or any application that renders markdown content. The unified ecosystem (remark for markdown, rehype for HTML) provides a plugin pipeline for transforming content. Use MDX when you need interactive React components inside markdown. These patterns cover the full pipeline from raw markdown to styled, interactive HTML.
+
+## How It Works
+
+### Remark/Rehype Pipeline
+
+```typescript
+// src/markdown/processor.ts
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkMath from 'remark-math';
+import remarkRehype from 'remark-rehype';
+import rehypeSlug from 'rehype-slug';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import rehypeHighlight from 'rehype-highlight';
+import rehypeKatex from 'rehype-katex';
+import rehypeSanitize from 'rehype-sanitize';
+import rehypeStringify from 'rehype-stringify';
+
+export async function processMarkdown(markdown: string): Promise<{
+  html: string;
+  headings: Array<{ depth: number; text: string; id: string }>;
+}> {
+  const headings: Array<{ depth: number; text: string; id: string }> = [];
+
+  const result = await unified()
+    .use(remarkParse)
+    .use(remarkGfm)                    // tables, strikethrough, task lists
+    .use(remarkMath)                    // LaTeX math blocks
+    .use(extractHeadings, { headings }) // custom plugin
+    .use(remarkRehype, { allowDangerousHtml: false })
+    .use(rehypeSlug)                    // add id to headings
+    .use(rehypeAutolinkHeadings, { behavior: 'wrap' })
+    .use(rehypeHighlight)              // syntax highlighting
+    .use(rehypeKatex)                  // render math
+    .use(rehypeSanitize)               // XSS protection
+    .use(rehypeStringify)
+    .process(markdown);
+
+  return { html: String(result), headings };
+}
+```
+
+### Custom Remark Plugin
+
+```typescript
+// src/markdown/plugins/extract-headings.ts
+import { visit } from 'unist-util-visit';
+import { toString } from 'mdast-util-to-string';
+import type { Root, Heading } from 'mdast';
+import type { Plugin } from 'unified';
+
+interface Options {
+  headings: Array<{ depth: number; text: string; id: string }>;
+}
+
+export const extractHeadings: Plugin<[Options], Root> = (options) => {
+  return (tree) => {
+    visit(tree, 'heading', (node: Heading) => {
+      const text = toString(node);
+      const id = text.toLowerCase().replace(/[^\w]+/g, '-').replace(/(^-|-$)/g, '');
+      options.headings.push({ depth: node.depth, text, id });
+    });
+  };
+};
+```
+
+### Reading Time Plugin
+
+```typescript
+// src/markdown/plugins/reading-time.ts
+import { toString } from 'mdast-util-to-string';
+import type { Root } from 'mdast';
+import type { Plugin } from 'unified';
+import type { VFile } from 'vfile';
+
+const WORDS_PER_MINUTE = 200;
+
+export const remarkReadingTime: Plugin<[], Root> = () => {
+  return (tree: Root, file: VFile) => {
+    const text = toString(tree);
+    const words = text.split(/\s+/).filter(Boolean).length;
+    const minutes = Math.max(1, Math.ceil(words / WORDS_PER_MINUTE));
+
+    (file.data as any).readingTime = { words, minutes, text: `${minutes} min read` };
+  };
+};
+```
+
+### Syntax Highlighting with Shiki
+
+```typescript
+// src/markdown/highlighter.ts
+import { createHighlighter, type BundledLanguage } from 'shiki';
+
+let highlighter: Awaited<ReturnType<typeof createHighlighter>> | null = null;
+
+async function getHighlighter() {
+  if (!highlighter) {
+    highlighter = await createHighlighter({
+      themes: ['github-dark', 'github-light'],
+      langs: ['typescript', 'javascript', 'jsx', 'tsx', 'python', 'bash', 'json', 'sql', 'css', 'html'],
+    });
+  }
+  return highlighter;
+}
+
+export async function highlightCode(code: string, lang: string, theme: 'dark' | 'light' = 'dark') {
+  const h = await getHighlighter();
+  return h.codeToHtml(code.trim(), {
+    lang: lang as BundledLanguage,
+    theme: theme === 'dark' ? 'github-dark' : 'github-light',
+  });
+}
+
+// Rehype plugin using Shiki
+import { visit } from 'unist-util-visit';
+import type { Element, Root } from 'hast';
+
+export function rehypeShiki(): (tree: Root) => Promise<void> {
+  return async (tree) => {
+    const h = await getHighlighter();
+    const promises: Promise<void>[] = [];
+
+    visit(tree, 'element', (node: Element, _index, parent) => {
+      if (node.tagName !== 'code' || (parent as Element)?.tagName !== 'pre') return;
+
+      const className = (node.properties?.className as string[]) ?? [];
+      const lang = className.find((c) => c.startsWith('language-'))?.replace('language-', '') ?? 'text';
+
+      const code = toString(node);
+      promises.push(
+        (async () => {
+          const html = h.codeToHtml(code, { lang: lang as BundledLanguage, theme: 'github-dark' });
+          // Replace the pre>code with Shiki output
+          Object.assign(parent!, { type: 'raw', value: html });
+        })()
+      );
+    });
+
+    await Promise.all(promises);
+  };
+}
+```
+
+### MDX Compilation
+
+```typescript
+// src/markdown/mdx.ts
+import { compile, run } from '@mdx-js/mdx';
+import * as runtime from 'react/jsx-runtime';
+import remarkGfm from 'remark-gfm';
+import rehypeSlug from 'rehype-slug';
+
+// Custom components available in MDX
+const components = {
+  Callout: ({ type, children }: { type: 'info' | 'warning' | 'error'; children: React.ReactNode }) => (
+    <div className={`callout callout-${type}`} role="alert">{children}</div>
+  ),
+  CodeTabs: ({ children }: { children: React.ReactNode }) => (
+    <div className="code-tabs">{children}</div>
+  ),
+};
+
+export async function compileMDX(source: string) {
+  const code = String(
+    await compile(source, {
+      outputFormat: 'function-body',
+      remarkPlugins: [remarkGfm],
+      rehypePlugins: [rehypeSlug],
+    })
+  );
+
+  const { default: Content } = await run(code, {
+    ...runtime,
+    baseUrl: import.meta.url,
+  });
+
+  return { Content, components };
+}
+
+// Usage in React
+function MDXRenderer({ source }: { source: string }) {
+  const [Content, setContent] = useState<React.FC | null>(null);
+
+  useEffect(() => {
+    compileMDX(source).then(({ Content }) => setContent(() => Content));
+  }, [source]);
+
+  if (!Content) return <div>Loading...</div>;
+  return <Content components={components} />;
+}
+```
+
+### Content Pipeline (Frontmatter + Processing)
+
+```typescript
+// src/markdown/content-pipeline.ts
+import matter from 'gray-matter';
+import { z } from 'zod';
+
+const frontmatterSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  date: z.coerce.date(),
+  tags: z.array(z.string()).default([]),
+  draft: z.boolean().default(false),
+  author: z.string().optional(),
+});
+
+type Frontmatter = z.infer<typeof frontmatterSchema>;
+
+export interface ProcessedContent {
+  frontmatter: Frontmatter;
+  html: string;
+  headings: Array<{ depth: number; text: string; id: string }>;
+  readingTime: { words: number; minutes: number; text: string };
+  excerpt: string;
+}
+
+export async function processContentFile(filepath: string): Promise<ProcessedContent> {
+  const raw = await fs.readFile(filepath, 'utf-8');
+  const { data, content } = matter(raw);
+
+  // Validate frontmatter
+  const frontmatter = frontmatterSchema.parse(data);
+
+  // Process markdown
+  const { html, headings } = await processMarkdown(content);
+
+  // Generate excerpt (first paragraph)
+  const excerpt = content.split('\n\n')[0].replace(/[#*_`]/g, '').trim().slice(0, 200);
+
+  return { frontmatter, html, headings, readingTime: { words: 0, minutes: 0, text: '' }, excerpt };
+}
+
+// Build a searchable index
+export async function buildContentIndex(contentDir: string) {
+  const files = await glob('**/*.md', { cwd: contentDir });
+  const index = await Promise.all(
+    files.map(async (file) => {
+      const content = await processContentFile(path.join(contentDir, file));
+      return {
+        slug: file.replace(/\.md$/, ''),
+        ...content.frontmatter,
+        excerpt: content.excerpt,
+        headings: content.headings,
+      };
+    })
+  );
+
+  return index
+    .filter((item) => !item.draft)
+    .sort((a, b) => b.date.getTime() - a.date.getTime());
+}
+```
+
+### Custom Rehype Plugin (Image Optimization)
+
+```typescript
+// src/markdown/plugins/rehype-optimized-images.ts
+import { visit } from 'unist-util-visit';
+import type { Element, Root } from 'hast';
+
+export function rehypeOptimizedImages(options: { basePath: string; widths: number[] }) {
+  return (tree: Root) => {
+    visit(tree, 'element', (node: Element) => {
+      if (node.tagName !== 'img') return;
+
+      const src = node.properties?.src as string;
+      if (!src || src.startsWith('http')) return;
+
+      const srcset = options.widths
+        .map((w) => `${options.basePath}/_next/image?url=${encodeURIComponent(src)}&w=${w} ${w}w`)
+        .join(', ');
+
+      node.properties = {
+        ...node.properties,
+        srcset,
+        sizes: '(max-width: 768px) 100vw, 768px',
+        loading: 'lazy',
+        decoding: 'async',
+      };
+    });
+  };
+}
+```
+
+## Examples
+
+| Plugin | Phase | Purpose |
+|--------|-------|---------|
+| `remark-gfm` | Parse | Tables, task lists, autolinks |
+| `remark-math` | Parse | LaTeX math expressions |
+| `remark-rehype` | Transform | Markdown AST to HTML AST |
+| `rehype-slug` | Transform | Add IDs to headings |
+| `rehype-highlight` | Transform | Syntax highlighting |
+| `rehype-sanitize` | Transform | XSS protection |
+| `rehype-stringify` | Stringify | HTML AST to string |
+
+## Checklist
+- [ ] Markdown processed through unified pipeline (remark + rehype)
+- [ ] GFM enabled for tables, task lists, and strikethrough
+- [ ] Syntax highlighting uses Shiki or rehype-highlight with language detection
+- [ ] Headings have slugified IDs for anchor links
+- [ ] HTML output sanitized to prevent XSS from user content
+- [ ] Frontmatter validated with Zod schema
+- [ ] Reading time calculated and exposed to templates
+- [ ] Images have lazy loading, srcset, and sizes attributes

package/assets/skills/mcp-server-patterns.md

@@ -0,0 +1,292 @@
+---
+name: mcp-server-patterns
+description: Build MCP servers — tool definitions, resource providers, stdio transport, input validation, error handling, and testing.
+---
+
+# MCP Server Patterns
+
+## When to Use
+
+Apply these patterns when building Model Context Protocol (MCP) servers that
+expose tools and resources to AI assistants (Claude, Copilot, etc.). MCP
+servers act as a bridge between AI models and external capabilities — file
+systems, APIs, databases, or custom business logic. Use this skill when
+creating tool integrations, resource providers, or extending an existing
+MCP server with new capabilities.
+
+## How It Works
+
+### 1. Server Setup — stdio Transport
+
+```typescript
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+const server = new McpServer({
+  name: 'my-tools',
+  version: '1.0.0',
+});
+
+// Start the server on stdio
+const transport = new StdioServerTransport();
+await server.connect(transport);
+```
+
+### 2. Tool Definitions — Input Schema and Handler
+
+```typescript
+// Simple tool with validated inputs
+server.tool(
+  'search_files',
+  'Search for files matching a pattern in the project directory',
+  {
+    pattern: z.string().describe('Glob pattern to match (e.g., "**/*.ts")'),
+    directory: z.string().optional().describe('Starting directory (default: project root)'),
+    maxResults: z.number().int().min(1).max(100).default(20).describe('Maximum results to return'),
+  },
+  async ({ pattern, directory, maxResults }) => {
+    const results = await globSearch(pattern, {
+      cwd: directory ?? process.cwd(),
+      limit: maxResults,
+    });
+
+    return {
+      content: [{
+        type: 'text',
+        text: results.length > 0
+          ? results.map(f => `- ${f}`).join('\n')
+          : `No files found matching "${pattern}"`,
+      }],
+    };
+  }
+);
+
+// Tool that returns structured data
+server.tool(
+  'query_database',
+  'Run a read-only SQL query against the project database',
+  {
+    query: z.string().describe('SQL SELECT query to execute'),
+  },
+  async ({ query }) => {
+    // Validate query is read-only
+    const normalized = query.trim().toUpperCase();
+    if (!normalized.startsWith('SELECT') && !normalized.startsWith('WITH')) {
+      return {
+        content: [{ type: 'text', text: 'Error: Only SELECT queries are allowed' }],
+        isError: true,
+      };
+    }
+
+    try {
+      const rows = await db.query(query);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify(rows, null, 2),
+        }],
+      };
+    } catch (err) {
+      return {
+        content: [{ type: 'text', text: `Query error: ${(err as Error).message}` }],
+        isError: true,
+      };
+    }
+  }
+);
+```
+
+### 3. Resource Providers — Expose Contextual Data
+
+```typescript
+// Static resource
+server.resource(
+  'project-config',
+  'project://config',
+  async (uri) => ({
+    contents: [{
+      uri: uri.href,
+      mimeType: 'application/json',
+      text: JSON.stringify(await loadProjectConfig(), null, 2),
+    }],
+  })
+);
+
+// Dynamic resource with URI template
+server.resource(
+  'file-contents',
+  new ResourceTemplate('file:///{path}', { list: undefined }),
+  async (uri, { path }) => {
+    const content = await fs.readFile(path as string, 'utf-8');
+    return {
+      contents: [{
+        uri: uri.href,
+        mimeType: getMimeType(path as string),
+        text: content,
+      }],
+    };
+  }
+);
+```
+
+### 4. Error Handling — Graceful Failure
+
+```typescript
+server.tool(
+  'deploy_preview',
+  'Deploy a preview environment for the current branch',
+  {
+    branch: z.string().describe('Git branch to deploy'),
+  },
+  async ({ branch }) => {
+    try {
+      // Validate branch exists
+      const branches = await git.listBranches();
+      if (!branches.includes(branch)) {
+        return {
+          content: [{
+            type: 'text',
+            text: `Branch "${branch}" not found. Available branches:\n${branches.join('\n')}`,
+          }],
+          isError: true,
+        };
+      }
+
+      const result = await deployPreview(branch);
+      return {
+        content: [{
+          type: 'text',
+          text: `Preview deployed successfully.\nURL: ${result.url}\nStatus: ${result.status}`,
+        }],
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        content: [{
+          type: 'text',
+          text: `Deployment failed: ${message}\n\nTroubleshooting:\n- Check that Docker is running\n- Verify cloud credentials are configured`,
+        }],
+        isError: true,
+      };
+    }
+  }
+);
+```
+
+### 5. Tool Design Principles
+
+```typescript
+// GOOD: Clear name, specific description, constrained inputs
+server.tool(
+  'create_github_issue',
+  'Create a new issue in the specified GitHub repository',
+  {
+    repo: z.string().regex(/^[\w-]+\/[\w-]+$/).describe('Repository (owner/name)'),
+    title: z.string().min(1).max(256).describe('Issue title'),
+    body: z.string().optional().describe('Issue body in markdown'),
+    labels: z.array(z.string()).optional().describe('Labels to apply'),
+  },
+  handler
+);
+
+// BAD: Vague name, no input validation, overly broad
+server.tool(
+  'do_github_stuff',
+  'Does stuff with GitHub',
+  { data: z.any() },
+  handler
+);
+```
+
+**Tool design rules:**
+- Name: verb_noun format, lowercase with underscores
+- Description: one sentence explaining what the tool does and when to use it
+- Inputs: use Zod for validation with `.describe()` on every field
+- Outputs: return structured text, not raw JSON dumps
+- Errors: return `isError: true` with actionable messages, not stack traces
+
+### 6. Multi-Tool Server Pattern
+
+```typescript
+// Organize tools by domain in separate files
+// tools/files.ts
+export function registerFileTools(server: McpServer) {
+  server.tool('read_file', '...', schema, handler);
+  server.tool('write_file', '...', schema, handler);
+  server.tool('search_files', '...', schema, handler);
+}
+
+// tools/git.ts
+export function registerGitTools(server: McpServer) {
+  server.tool('git_status', '...', schema, handler);
+  server.tool('git_diff', '...', schema, handler);
+  server.tool('git_log', '...', schema, handler);
+}
+
+// index.ts
+const server = new McpServer({ name: 'dev-tools', version: '1.0.0' });
+registerFileTools(server);
+registerGitTools(server);
+```
+
+### 7. Testing MCP Tools
+
+```typescript
+import { describe, it, expect, vi } from 'vitest';
+
+describe('search_files tool', () => {
+  it('returns matching files', async () => {
+    const result = await searchFilesHandler({
+      pattern: '**/*.ts',
+      directory: '/tmp/test-project',
+      maxResults: 5,
+    });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain('.ts');
+  });
+
+  it('returns empty message when no files match', async () => {
+    const result = await searchFilesHandler({
+      pattern: '**/*.xyz',
+      directory: '/tmp/test-project',
+      maxResults: 5,
+    });
+
+    expect(result.content[0].text).toContain('No files found');
+  });
+
+  it('returns error for invalid directory', async () => {
+    const result = await searchFilesHandler({
+      pattern: '**/*.ts',
+      directory: '/nonexistent',
+      maxResults: 5,
+    });
+
+    expect(result.isError).toBe(true);
+  });
+});
+```
+
+## Examples
+
+| Component | Purpose | Protocol Role |
+|-----------|---------|---------------|
+| Tool | Execute actions (read, write, deploy) | `tools/call` |
+| Resource | Expose read-only context (config, schema) | `resources/read` |
+| Prompt | Predefined prompt templates | `prompts/get` |
+| Transport | Communication channel | stdio, SSE, HTTP |
+
+## Checklist
+
+- [ ] All tools have descriptive names (verb_noun) and one-sentence descriptions
+- [ ] Input schemas use Zod with `.describe()` on every parameter
+- [ ] Tools validate inputs and return `isError: true` on failure
+- [ ] Error messages include troubleshooting hints, not raw exceptions
+- [ ] Read-only operations separated from write operations
+- [ ] Destructive tools require explicit confirmation parameters
+- [ ] Resources expose context data that tools can reference
+- [ ] Tools organized by domain in separate files
+- [ ] Each tool handler has unit tests covering success, error, and edge cases
+- [ ] Server logs to stderr (not stdout) to avoid corrupting stdio transport