@claude-code-mastery/starter-kit 1.0.0 → 1.2.0

package/scripts/content/markdown-processor.ts

@@ -0,0 +1,261 @@
+/**
+ * Content Builder — Markdown Processor
+ *
+ * Converts markdown text to HTML with support for code blocks,
+ * tables, lists, blockquotes, headings, and inline formatting.
+ */
+
+import type { CollectedHeading } from './types.js';
+
+export function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+export function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+export function stripMarkdown(text: string): string {
+  return text
+    .replace(/\*\*\*(.*?)\*\*\*/g, '$1')
+    .replace(/\*\*(.*?)\*\*/g, '$1')
+    .replace(/\*(.*?)\*/g, '$1')
+    .replace(/`([^`]+)`/g, '$1')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+}
+
+export function processInlineFormatting(text: string): string {
+  let result = text;
+  result = result.replace(/\*\*\*(.*?)\*\*\*/g, '<strong><em>$1</em></strong>');
+  result = result.replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>');
+  result = result.replace(/\*(.*?)\*/g, '<em>$1</em>');
+  result = result.replace(/`([^`]+)`/g, '<code>$1</code>');
+  result = result.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, '<img src="$2" alt="$1">');
+  result = result.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+  result = result.replace(/ {2}$/gm, '<br>');
+  return result;
+}
+
+function convertTableToHtml(rows: string[]): string {
+  if (rows.length === 0) return '';
+  let html = '<div class="table-wrapper">\n<table>\n';
+
+  rows.forEach((row, idx) => {
+    const cells = row.split('|').slice(1, -1);
+    const tag = idx === 0 ? 'th' : 'td';
+    html += '<tr>';
+    for (const cell of cells) {
+      let content = cell.trim();
+      content = content.replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>');
+      content = content.replace(/\*(.*?)\*/g, '<em>$1</em>');
+      html += `<${tag}>${content}</${tag}>`;
+    }
+    html += '</tr>\n';
+  });
+
+  html += '</table>\n</div>';
+  return html;
+}
+
+function processMarkdownTables(html: string): string {
+  const lines = html.split('\n');
+  const result: string[] = [];
+  let inTable = false;
+  let tableRows: string[] = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith('|') && trimmed.endsWith('|')) {
+      if (!inTable) {
+        inTable = true;
+        tableRows = [];
+      }
+      if (!/^\|[\s\-:|]+\|$/.test(trimmed)) {
+        tableRows.push(trimmed);
+      }
+    } else {
+      if (inTable) {
+        result.push(convertTableToHtml(tableRows));
+        inTable = false;
+        tableRows = [];
+      }
+      result.push(line);
+    }
+  }
+
+  if (inTable && tableRows.length > 0) {
+    result.push(convertTableToHtml(tableRows));
+  }
+
+  return result.join('\n');
+}
+
+function processLists(html: string): string {
+  const lines = html.split('\n');
+  const result: string[] = [];
+  let inList = false;
+
+  for (const line of lines) {
+    const match = line.match(/^(\s*)- (.*)$/);
+    if (match) {
+      const content = processInlineFormatting(match[2]);
+      if (!inList) {
+        result.push('<ul>');
+        inList = true;
+      }
+      result.push(`<li>${content}</li>`);
+    } else {
+      if (inList) {
+        result.push('</ul>');
+        inList = false;
+      }
+      result.push(line);
+    }
+  }
+
+  if (inList) result.push('</ul>');
+  return result.join('\n');
+}
+
+function processOrderedLists(html: string): string {
+  const lines = html.split('\n');
+  const result: string[] = [];
+  let inList = false;
+
+  for (const line of lines) {
+    const match = line.match(/^\d+\.\s+(.*)$/);
+    if (match) {
+      if (!inList) {
+        result.push('<ol>');
+        inList = true;
+      }
+      result.push(`<li>${processInlineFormatting(match[1])}</li>`);
+    } else {
+      if (inList) {
+        result.push('</ol>');
+        inList = false;
+      }
+      result.push(line);
+    }
+  }
+
+  if (inList) result.push('</ol>');
+  return result.join('\n');
+}
+
+export function convertMarkdownToHtml(md: string, headings: CollectedHeading[]): string {
+  let html = md;
+
+  // Code blocks first (preserve content)
+  const codeBlocks: string[] = [];
+  html = html.replace(/````(\w*)\n([\s\S]*?)````/g, (_match, lang: string, code: string) => {
+    const placeholder = `___CODEBLOCK_${codeBlocks.length}___`;
+    codeBlocks.push(`<pre><code class="language-${lang || 'plaintext'}">${escapeHtml(code.trim())}</code></pre>`);
+    return placeholder;
+  });
+  html = html.replace(/```(\w*)\n([\s\S]*?)```/g, (_match, lang: string, code: string) => {
+    const placeholder = `___CODEBLOCK_${codeBlocks.length}___`;
+    codeBlocks.push(`<pre><code class="language-${lang || 'plaintext'}">${escapeHtml(code.trim())}</code></pre>`);
+    return placeholder;
+  });
+
+  // Tables
+  html = processMarkdownTables(html);
+
+  // Blockquotes
+  html = html.replace(/^>\s*(.*)$/gm, '<blockquote><p>$1</p></blockquote>');
+  html = html.replace(/<\/blockquote>\n<blockquote>/g, '\n');
+
+  // Headings (collect for sidebar TOC)
+  html = html.replace(/^#### (.*)$/gm, (_m, text: string) => {
+    const id = slugify(text);
+    headings.push({ level: 4, id, text: stripMarkdown(text) });
+    return `<h4 id="${id}">${processInlineFormatting(text)}</h4>`;
+  });
+  html = html.replace(/^### (.*)$/gm, (_m, text: string) => {
+    const id = slugify(text);
+    headings.push({ level: 3, id, text: stripMarkdown(text) });
+    return `<h3 id="${id}">${processInlineFormatting(text)}</h3>`;
+  });
+  html = html.replace(/^## (.*)$/gm, (_m, text: string) => {
+    const id = slugify(text);
+    headings.push({ level: 2, id, text: stripMarkdown(text) });
+    return `<h2 id="${id}">${processInlineFormatting(text)}</h2>`;
+  });
+  html = html.replace(/^# (.*)$/gm, (_m, text: string) => {
+    const id = slugify(text);
+    headings.push({ level: 1, id, text: stripMarkdown(text) });
+    return `<h1 id="${id}">${processInlineFormatting(text)}</h1>`;
+  });
+
+  // Horizontal rules
+  html = html.replace(/^---$/gm, '<hr>');
+
+  // Lists
+  html = processLists(html);
+  html = processOrderedLists(html);
+
+  // Remaining inline formatting
+  html = html.replace(/\*\*\*(.*?)\*\*\*/g, '<strong><em>$1</em></strong>');
+  html = html.replace(/\*\*(.*?)\*\*/g, '<strong>$1</strong>');
+  html = html.replace(/(?<!\*)\*([^*]+)\*(?!\*)/g, '<em>$1</em>');
+  html = html.replace(/`([^`]+)`/g, '<code>$1</code>');
+  html = html.replace(/!\[([^\]]*)\]\(([^)]+)\)/g, '<img src="$2" alt="$1">');
+  html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+  // Paragraphs
+  const blockTags = /^<(h[1-6]|ul|ol|li|blockquote|pre|div|table|tr|th|td|hr|nav|header|footer|article|section)/i;
+  const rawLines = html.split('\n');
+  const groups: Array<{ type: string; lines?: string[]; content?: string }> = [];
+  let currentGroup: string[] = [];
+
+  for (const line of rawLines) {
+    const trimmed = line.trim();
+    if (trimmed === '' || blockTags.test(trimmed) || trimmed.startsWith('___CODEBLOCK_')) {
+      if (currentGroup.length > 0) {
+        groups.push({ type: 'paragraph', lines: currentGroup });
+        currentGroup = [];
+      }
+      if (trimmed !== '') {
+        groups.push({ type: 'html', content: trimmed });
+      }
+    } else if (line.endsWith('  ')) {
+      currentGroup.push(trimmed + '<br>');
+    } else {
+      currentGroup.push(trimmed);
+    }
+  }
+  if (currentGroup.length > 0) {
+    groups.push({ type: 'paragraph', lines: currentGroup });
+  }
+
+  const result: string[] = [];
+  for (const group of groups) {
+    if (group.type === 'html') {
+      result.push(group.content!);
+    } else if (group.type === 'paragraph' && group.lines) {
+      result.push(`<p>${group.lines.join('\n')}</p>`);
+    }
+  }
+
+  html = result.join('\n');
+
+  // Restore code blocks
+  codeBlocks.forEach((block, i) => {
+    html = html.replace(`___CODEBLOCK_${i}___`, block);
+  });
+
+  html = html.replace(/<p><\/p>/g, '');
+  html = html.replace(/\n{3,}/g, '\n\n');
+
+  return html;
+}

package/scripts/content/seo-generator.ts

@@ -0,0 +1,42 @@
+/**
+ * Content Builder — SEO & Schema.org Generator
+ *
+ * Generates JSON-LD structured data for articles and FAQ pages.
+ */
+
+import type { ArticleConfig, ContentConfig } from './types.js';
+
+export function generateSchemaJson(article: ArticleConfig, config: ContentConfig): string {
+  const schema: Record<string, unknown> = {
+    '@context': 'https://schema.org',
+    '@type': 'Article',
+    headline: article.title,
+    description: article.description,
+    url: article.url,
+    datePublished: article.datePublished,
+    dateModified: article.datePublished,
+    author: { '@type': 'Person', name: config.author, url: config.siteUrl },
+    publisher: { '@type': 'Person', name: config.author },
+    keywords: article.keywords ?? [],
+    isPartOf: article.parent
+      ? { '@type': 'Article', url: `${config.siteUrl}${article.parent.url}` }
+      : { '@type': 'WebSite', name: config.siteName, url: config.siteUrl },
+  };
+
+  let block = `    <script type="application/ld+json">\n    ${JSON.stringify(schema, null, 4)}\n    </script>`;
+
+  if (article.faqSchema && article.faqSchema.length > 0) {
+    const faqSchema = {
+      '@context': 'https://schema.org',
+      '@type': 'FAQPage',
+      mainEntity: article.faqSchema.map((faq) => ({
+        '@type': 'Question',
+        name: faq.question,
+        acceptedAnswer: { '@type': 'Answer', text: faq.answer },
+      })),
+    };
+    block += `\n    <script type="application/ld+json">\n    ${JSON.stringify(faqSchema, null, 4)}\n    </script>`;
+  }
+
+  return block;
+}

package/scripts/content/sidebar-generator.ts

@@ -0,0 +1,71 @@
+/**
+ * Content Builder — Sidebar Generator
+ *
+ * Generates sidebar HTML with TOC, parent/child navigation, and grouping.
+ */
+
+import type { ArticleConfig, CollectedHeading } from './types.js';
+
+export function generateSidebarHtml(article: ArticleConfig, headings: CollectedHeading[]): string {
+  if (!article.sidebar) return '';
+
+  const parts: string[] = [];
+
+  if (article.parent) {
+    parts.push(`        <a href="${article.parent.url}" class="sidebar-back">${article.parent.title}</a>`);
+  }
+
+  const maxLevel = article.tocLevel ?? (article.parent ? 2 : 1);
+  let tocHeadings = headings.filter((h) => h.level <= maxLevel);
+  if (article.tocFilter) {
+    const re = new RegExp(article.tocFilter);
+    tocHeadings = tocHeadings.filter((h) => re.test(h.text));
+  }
+
+  if (tocHeadings.length > 0) {
+    parts.push('        <div class="sidebar-label">CONTENTS</div>');
+    parts.push('        <ul class="sidebar-toc">');
+    for (const h of tocHeadings) {
+      const cls = h.level === 1 ? 'toc-h1' : 'toc-h2';
+      parts.push(`            <li><a href="#${h.id}" class="${cls}">${h.text}</a></li>`);
+    }
+    parts.push('        </ul>');
+  }
+
+  if (article.children && article.children.length > 0) {
+    const currentPath = '/' + article.htmlOutput.replace(/index\.html$/, '');
+    const hasGroups = article.children.some((c) => c.group);
+
+    if (hasGroups) {
+      let listOpen = false;
+      for (const child of article.children) {
+        if (child.group) {
+          if (listOpen) parts.push('        </ul>');
+          parts.push(`        <div class="sidebar-label">${child.group}</div>`);
+          parts.push('        <ul class="sidebar-links">');
+          listOpen = true;
+        }
+        const isCurrent = child.url === currentPath;
+        const cls = isCurrent ? ' class="sidebar-current"' : '';
+        parts.push(`            <li><a href="${child.url}"${cls}>${child.title}</a></li>`);
+      }
+      if (listOpen) parts.push('        </ul>');
+    } else {
+      const label = article.childrenLabel ?? (article.parent ? 'RELATED' : 'DEEP DIVES');
+      parts.push(`        <div class="sidebar-label">${label}</div>`);
+      parts.push('        <ul class="sidebar-links">');
+      for (const child of article.children) {
+        const isCurrent = child.url === currentPath;
+        const cls = isCurrent ? ' class="sidebar-current"' : '';
+        parts.push(`            <li><a href="${child.url}"${cls}>${child.title}</a></li>`);
+      }
+      parts.push('        </ul>');
+    }
+  }
+
+  return `    <aside class="article-sidebar" id="articleSidebar">
+        <div class="sidebar-inner">
+${parts.join('\n')}
+        </div>
+    </aside>`;
+}

package/scripts/content/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Content Builder — Types & Validation
+ *
+ * Shared types and Zod schemas for the content build system.
+ */
+
+import { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Zod Schemas (runtime validation)
+// ---------------------------------------------------------------------------
+
+const SidebarChildSchema = z.object({
+  title: z.string().min(1),
+  url: z.string().min(1),
+  group: z.string().optional(),
+});
+
+const FaqItemSchema = z.object({
+  question: z.string().min(1),
+  answer: z.string().min(1),
+});
+
+const ArticleConfigSchema = z.object({
+  id: z.string().min(1, 'Article id is required'),
+  published: z.boolean(),
+  mdSource: z.string().min(1, 'mdSource path is required'),
+  htmlOutput: z.string().min(1, 'htmlOutput path is required'),
+  title: z.string().min(1, 'title is required'),
+  titleHtml: z.string().optional(),
+  subtitle: z.string().optional(),
+  description: z.string().min(1, 'description is required'),
+  bannerImage: z.string().optional(),
+  bannerAlt: z.string().optional(),
+  url: z.string().url('url must be a valid URL'),
+  datePublished: z.string().min(1, 'datePublished is required'),
+  category: z.string().optional(),
+  tags: z.array(z.string()).optional(),
+  keywords: z.array(z.string()).optional(),
+  sidebar: z.boolean().optional(),
+  parent: z.object({ title: z.string(), url: z.string() }).optional(),
+  children: z.array(SidebarChildSchema).optional(),
+  childrenLabel: z.string().optional(),
+  tocLevel: z.number().int().min(1).max(6).optional(),
+  tocFilter: z.string().optional(),
+  faqSchema: z.array(FaqItemSchema).optional(),
+});
+
+const ContentConfigSchema = z.object({
+  siteUrl: z.string().url('siteUrl must be a valid URL'),
+  siteName: z.string().min(1, 'siteName is required'),
+  author: z.string().min(1, 'author is required'),
+  outputDir: z.string().min(1, 'outputDir is required'),
+  categories: z.array(z.string()),
+  articles: z.array(ArticleConfigSchema),
+});
+
+export { ContentConfigSchema, ArticleConfigSchema };
+
+// ---------------------------------------------------------------------------
+// TypeScript interfaces (inferred from Zod for zero drift)
+// ---------------------------------------------------------------------------
+
+export type SidebarChild = z.infer<typeof SidebarChildSchema>;
+export type ArticleConfig = z.infer<typeof ArticleConfigSchema>;
+export type ContentConfig = z.infer<typeof ContentConfigSchema>;
+
+export interface CollectedHeading {
+  level: number;
+  id: string;
+  text: string;
+}

package/scripts/content.config.json

@@ -0,0 +1,49 @@
+{
+  "siteUrl": "https://example.com",
+  "siteName": "My Project",
+  "author": "Your Name",
+  "outputDir": "public/articles",
+  "categories": ["All", "Guides", "Updates", "Tutorials"],
+  "articles": [
+    {
+      "id": "getting-started",
+      "published": true,
+      "mdSource": "content/getting-started.md",
+      "htmlOutput": "public/articles/getting-started/index.html",
+      "title": "Getting Started Guide",
+      "titleHtml": "Getting <span>Started</span>",
+      "subtitle": "Everything you need to know",
+      "description": "A comprehensive guide to getting started with the project. Covers installation, configuration, and first steps.",
+      "bannerImage": "/images/getting-started-banner.webp",
+      "bannerAlt": "Getting Started Guide",
+      "url": "https://example.com/articles/getting-started/",
+      "datePublished": "2026-01-15",
+      "category": "Guides",
+      "tags": ["Guide", "Setup", "2026"],
+      "keywords": ["getting started", "setup", "installation", "tutorial"]
+    },
+    {
+      "id": "example-with-sidebar",
+      "published": false,
+      "mdSource": "content/advanced-guide.md",
+      "htmlOutput": "public/articles/advanced-guide/index.html",
+      "title": "Advanced Configuration",
+      "titleHtml": "Advanced <span>Configuration</span>",
+      "subtitle": "Deep dive into settings",
+      "description": "Advanced configuration options and patterns for power users.",
+      "bannerImage": "/images/advanced-banner.webp",
+      "bannerAlt": "Advanced Configuration Guide",
+      "url": "https://example.com/articles/advanced-guide/",
+      "datePublished": "2026-02-01",
+      "category": "Tutorials",
+      "tags": ["Advanced", "Configuration", "2026"],
+      "keywords": ["advanced", "configuration", "settings", "customization"],
+      "sidebar": true,
+      "children": [
+        { "title": "Database Setup", "url": "/articles/advanced-guide/database/" },
+        { "title": "Authentication", "url": "/articles/advanced-guide/auth/" },
+        { "title": "Deployment", "url": "/articles/advanced-guide/deploy/" }
+      ]
+    }
+  ]
+}

package/scripts/db-query.ts

@@ -0,0 +1,143 @@
+#!/usr/bin/env npx tsx
+/**
+ * db-query.ts — Test Query Master
+ *
+ * This is the MASTER INDEX for all database test/dev queries.
+ * It is NOT production code — it exists solely for developer exploration.
+ *
+ * HOW IT WORKS:
+ * - Each query lives in its own file under scripts/queries/
+ * - Every query file is registered here with a name and description
+ * - Run: npx tsx scripts/db-query.ts <query-name> [args...]
+ * - Run: npx tsx scripts/db-query.ts --list  (to see all available queries)
+ *
+ * WHY THIS PATTERN:
+ * - Keeps test/dev database code COMPLETELY separate from production code
+ * - Every query receives a shared StrictDB instance — no raw driver imports
+ * - Easy to see at a glance what queries exist and what they do
+ * - Individual files are easy to review, modify, and delete
+ * - Production code in src/ never touches this — clean separation
+ *
+ * RULES:
+ * - EVERY query file MUST accept a StrictDB instance as its first parameter
+ * - NEVER import native database drivers directly in query files
+ * - NEVER copy query logic into production code — if you need it in prod,
+ *   create a proper handler in src/handlers/
+ * - Each query file exports: { name, description, run(db, args) }
+ *
+ * Install: npm install tsx -D (if not already installed)
+ */
+
+import { StrictDB } from 'strictdb';
+
+// ---------------------------------------------------------------------------
+// Query registry — add new queries here
+// ---------------------------------------------------------------------------
+
+interface QueryModule {
+  name: string;
+  description: string;
+  run: (db: StrictDB, args: string[]) => Promise<void>;
+}
+
+/**
+ * Register all query files here.
+ * Each entry maps a command name to its query module path.
+ *
+ * When Claude creates a new query for you, it will:
+ * 1. Create a new file in scripts/queries/<name>.ts
+ * 2. Add an entry to this registry
+ *
+ * Example:
+ *   'user-lookup': () => import('./queries/user-lookup.js'),
+ */
+const queryRegistry: Record<string, () => Promise<{ default: QueryModule }>> = {
+  // --- Example queries (remove or modify as needed) ---
+  'example-find-user': () => import('./queries/example-find-user.js'),
+  'example-count-docs': () => import('./queries/example-count-docs.js'),
+
+  // --- Add your queries below this line ---
+};
+
+// ---------------------------------------------------------------------------
+// CLI runner
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  // Show help
+  if (!command || command === '--help' || command === '-h') {
+    printUsage();
+    return;
+  }
+
+  // List all queries (no DB connection needed for listing)
+  if (command === '--list' || command === '-l') {
+    await listQueries();
+    return;
+  }
+
+  // Find and run the query
+  const loader = queryRegistry[command];
+  if (!loader) {
+    console.error(`\n  Unknown query: "${command}"\n`);
+    console.error('  Run with --list to see available queries.\n');
+    process.exit(1);
+  }
+
+  const db = await StrictDB.create({ uri: process.env.STRICTDB_URI! });
+
+  try {
+    const mod = await loader();
+    const query = mod.default;
+    console.log(`\n  Running: ${query.name}`);
+    console.log(`  ${query.description}\n`);
+    await query.run(db, args.slice(1));
+  } catch (err) {
+    console.error('\n  Query failed:', err);
+    process.exit(1);
+  } finally {
+    await db.close();
+  }
+}
+
+function printUsage(): void {
+  console.log(`
+  db-query — Test Query Master
+
+  Usage:
+    npx tsx scripts/db-query.ts <query-name> [args...]
+    npx tsx scripts/db-query.ts --list
+
+  Options:
+    --list, -l     List all registered queries
+    --help, -h     Show this help message
+
+  Examples:
+    npx tsx scripts/db-query.ts example-find-user test@example.com
+    npx tsx scripts/db-query.ts example-count-docs users
+    npx tsx scripts/db-query.ts --list
+  `);
+}
+
+async function listQueries(): Promise<void> {
+  console.log('\n  Available queries:\n');
+
+  for (const [name, loader] of Object.entries(queryRegistry)) {
+    try {
+      const mod = await loader();
+      console.log(`    ${name.padEnd(30)} ${mod.default.description}`);
+    } catch {
+      console.log(`    ${name.padEnd(30)} (failed to load)`);
+    }
+  }
+
+  console.log('');
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/scripts/queries/example-count-docs.ts

@@ -0,0 +1,25 @@
+/**
+ * Example query: Count documents in a collection
+ *
+ * Usage: npx tsx scripts/db-query.ts example-count-docs <collection>
+ *
+ * This is a TEST query — not production code.
+ */
+
+import type { StrictDB } from 'strictdb';
+
+export default {
+  name: 'example-count-docs',
+  description: 'Count documents in any collection',
+
+  async run(db: StrictDB, args: string[]): Promise<void> {
+    const collection = args[0];
+    if (!collection) {
+      console.error('  Usage: example-count-docs <collection>');
+      process.exit(1);
+    }
+
+    const total = await db.count(collection);
+    console.log(`  Collection "${collection}" has ${total} documents.`);
+  },
+};