@buenojs/bueno 0.8.3 → 0.8.5

package/src/templates/loader.ts

@@ -0,0 +1,331 @@
+/**
+ * Template Loader
+ *
+ * Loads templates from the filesystem with support for:
+ * - YAML front matter (metadata)
+ * - Template variants (channel-specific sections)
+ * - In-memory caching with TTL
+ * - Hot reload in development mode
+ */
+
+import { readFileSync, watch } from "fs";
+import { existsSync } from "fs";
+import { extname, resolve } from "path";
+import type {
+	Template,
+	TemplateLoaderOptions,
+	TemplateMetadata,
+} from "./types";
+
+/**
+ * Parses YAML-like front matter from template
+ * Format: ---\nkey: value\n---\n
+ */
+function parseFrontMatter(content: string): {
+	metadata: TemplateMetadata;
+	body: string;
+} {
+	const lines = content.split("\n");
+
+	// Check for front matter delimiter
+	if (lines[0]?.trim() !== "---") {
+		return { metadata: {}, body: content };
+	}
+
+	// Find closing delimiter
+	let endIdx = -1;
+	for (let i = 1; i < lines.length; i++) {
+		if (lines[i]?.trim() === "---") {
+			endIdx = i;
+			break;
+		}
+	}
+
+	if (endIdx === -1) {
+		return { metadata: {}, body: content };
+	}
+
+	// Parse front matter
+	const frontMatterLines = lines.slice(1, endIdx);
+	const metadata: TemplateMetadata = {};
+
+	for (const line of frontMatterLines) {
+		if (!line.trim()) continue;
+
+		const colonIdx = line.indexOf(":");
+		if (colonIdx === -1) continue;
+
+		const key = line.substring(0, colonIdx).trim();
+		let value: unknown = line.substring(colonIdx + 1).trim();
+
+		// Simple type conversion
+		if (value === "true") value = true;
+		else if (value === "false") value = false;
+		else if (value === "null") value = null;
+		else if (!isNaN(Number(value)) && value !== "") value = Number(value);
+		else if (value.startsWith("[") && value.endsWith("]")) {
+			// Parse simple arrays: [email, sms, push] or ["email", "sms", "push"]
+			const arrayContent = value.slice(1, -1).trim();
+			value = arrayContent.split(",").map((v) => {
+				let item = v.trim();
+				// Remove quotes if present
+				if (
+					(item.startsWith('"') && item.endsWith('"')) ||
+					(item.startsWith("'") && item.endsWith("'"))
+				) {
+					item = item.slice(1, -1);
+				}
+				return item;
+			});
+		}
+
+		metadata[key] = value;
+	}
+
+	const body = lines.slice(endIdx + 1).join("\n");
+	return { metadata, body };
+}
+
+/**
+ * Parses template variants from sections
+ * Format: ## Email\n...\n---\n## SMS\n...\n---\n## Push\n...
+ *
+ * Supports:
+ * - Single variant per section: "## Email"
+ * - Multiple variants (slash): "## SMS/Push"
+ * - Multiple variants (comma): "## SMS, Push"
+ */
+function parseVariants(content: string): Record<string, string> {
+	const sections = content.split(/^## /m);
+	const variants: Record<string, string> = {};
+
+	for (const section of sections) {
+		if (!section.trim()) continue;
+
+		const lines = section.split("\n");
+		const headerLine = lines[0];
+
+		if (!headerLine) continue;
+
+		// Extract variant names from header
+		// Supports: "Email", "SMS/Push", "SMS, Push", etc.
+		const variantNames = headerLine
+			.split(/[,/]\s*/)
+			.map((s) => s.trim().toLowerCase())
+			.filter((s) => s);
+
+		// Get section content (skip header and empty lines at start)
+		const contentLines = lines.slice(1);
+		let contentStart = 0;
+		while (
+			contentStart < contentLines.length &&
+			!contentLines[contentStart]?.trim()
+		) {
+			contentStart++;
+		}
+		const sectionContent = contentLines.slice(contentStart).join("\n").trim();
+
+		// Handle separator line (---)
+		const separatorIdx = sectionContent.indexOf("\n---");
+		const finalContent =
+			separatorIdx !== -1
+				? sectionContent.substring(0, separatorIdx)
+				: sectionContent;
+
+		// Map all variant names to same content
+		for (const variantName of variantNames) {
+			variants[variantName] = finalContent;
+		}
+	}
+
+	return variants;
+}
+
+/**
+ * Detects template format from file extension or metadata
+ */
+function detectFormat(
+	filePath: string,
+	metadata: TemplateMetadata,
+): "markdown" | "text" | "html" {
+	// Check metadata override
+	if (metadata.format) {
+		const fmt = String(metadata.format).toLowerCase();
+		if (["markdown", "text", "html"].includes(fmt)) {
+			return fmt as "markdown" | "text" | "html";
+		}
+	}
+
+	// Detect from extension
+	const ext = extname(filePath).toLowerCase();
+	if (ext === ".md" || ext === ".markdown") return "markdown";
+	if (ext === ".txt" || ext === ".text") return "text";
+	if (ext === ".html" || ext === ".htm") return "html";
+
+	// Default to markdown (most common)
+	return "markdown";
+}
+
+/**
+ * Template loader with caching and hot reload
+ */
+export class TemplateLoader {
+	private cache: Map<string, { template: Template; timestamp: number }> =
+		new Map();
+	private watchers: Map<string, ReturnType<typeof watch>> = new Map();
+	private metrics = {
+		loads: 0,
+		cacheHits: 0,
+		cacheMisses: 0,
+	};
+
+	constructor(private options: TemplateLoaderOptions) {
+		// Set defaults
+		this.options.cacheEnabled = options.cacheEnabled ?? true;
+		this.options.cacheTtl = options.cacheTtl ?? 3600;
+		this.options.maxCacheSize = options.maxCacheSize ?? 100;
+		this.options.extension = options.extension ?? ".md";
+	}
+
+	/**
+	 * Load a template by ID (path like "emails/welcome")
+	 */
+	load(templateId: string): Template {
+		const now = Date.now();
+
+		// Check cache
+		if (this.options.cacheEnabled) {
+			const cached = this.cache.get(templateId);
+			if (cached) {
+				const age = (now - cached.timestamp) / 1000;
+				if (age < (this.options.cacheTtl ?? 3600)) {
+					this.metrics.cacheHits++;
+					return cached.template;
+				}
+			}
+		}
+
+		// Load from disk
+		this.metrics.cacheMisses++;
+		const template = this._loadFromDisk(templateId);
+
+		// Cache it
+		if (this.options.cacheEnabled) {
+			// Prune cache if too large
+			if (
+				this.cache.size >= (this.options.maxCacheSize ?? 100) &&
+				!this.cache.has(templateId)
+			) {
+				// Remove oldest entry
+				const oldest = Array.from(this.cache.entries()).sort(
+					(a, b) => a[1].timestamp - b[1].timestamp,
+				)[0];
+				if (oldest) {
+					this.cache.delete(oldest[0]);
+				}
+			}
+
+			this.cache.set(templateId, { template, timestamp: now });
+
+			// Set up file watcher in development mode
+			if (this.options.watch) {
+				this._watchTemplate(templateId, template.id);
+			}
+		}
+
+		this.metrics.loads++;
+		return template;
+	}
+
+	/**
+	 * Load template from disk with variant parsing
+	 */
+	private _loadFromDisk(templateId: string): Template {
+		// Try multiple extensions
+		let filePath = resolve(
+			this.options.basePath,
+			templateId + this.options.extension,
+		);
+
+		if (!existsSync(filePath)) {
+			// Try .md if original extension didn't work
+			filePath = resolve(this.options.basePath, templateId + ".md");
+		}
+
+		if (!existsSync(filePath)) {
+			// Try .txt
+			filePath = resolve(this.options.basePath, templateId + ".txt");
+		}
+
+		if (!existsSync(filePath)) {
+			throw new Error(`Template not found: ${templateId}`);
+		}
+
+		// Read file
+		const content = readFileSync(filePath, "utf-8");
+
+		// Parse front matter
+		const { metadata, body } = parseFrontMatter(content);
+
+		// Parse variants from body
+		const variants = parseVariants(body);
+
+		// If no variants found, treat entire body as default variant
+		if (Object.keys(variants).length === 0) {
+			const defaultVariant = metadata.default || "default";
+			variants[defaultVariant] = body;
+		}
+
+		// Detect format
+		const format = detectFormat(filePath, metadata);
+
+		return {
+			id: templateId,
+			format,
+			content: body,
+			variants,
+			metadata,
+			loadedAt: Date.now(),
+		};
+	}
+
+	/**
+	 * Watch template file for changes (development mode)
+	 */
+	private _watchTemplate(templateId: string, filePath: string): void {
+		if (this.watchers.has(templateId)) {
+			return; // Already watching
+		}
+
+		try {
+			const fullPath = resolve(this.options.basePath, filePath);
+			const watcher = watch(fullPath, () => {
+				// Invalidate cache on file change
+				this.cache.delete(templateId);
+				this.watchers.delete(templateId);
+			});
+
+			this.watchers.set(templateId, watcher);
+		} catch {
+			// Silently fail if file watching not available
+		}
+	}
+
+	/**
+	 * Clear all caches and watchers
+	 */
+	clear(): void {
+		this.cache.clear();
+		for (const watcher of this.watchers.values()) {
+			watcher.close();
+		}
+		this.watchers.clear();
+	}
+
+	/**
+	 * Get loader metrics
+	 */
+	getMetrics() {
+		return { ...this.metrics };
+	}
+}

package/src/templates/renderers/markdown.ts

@@ -0,0 +1,212 @@
+/**
+ * Markdown Renderer
+ *
+ * Converts Markdown to HTML or plain text.
+ * Lightweight implementation supporting:
+ * - Headings (# ## ###)
+ * - Bold/italic (*text*, **text**)
+ * - Lists (- item, 1. item)
+ * - Links [text](url)
+ * - Code (`inline`)
+ * - Blockquotes (> quote)
+ * - Paragraphs (blank line separated)
+ *
+ * NOT supported (kept lightweight):
+ * - Tables
+ * - Code blocks with syntax highlighting
+ * - Complex nesting
+ * - Strikethrough
+ * - Footnotes
+ */
+
+/**
+ * Markdown to HTML renderer
+ */
+export class MarkdownRenderer {
+	/**
+	 * Convert Markdown string to HTML
+	 */
+	static toHtml(markdown: string): string {
+		let html = markdown;
+
+		// Escape HTML special characters (but preserve user-intentional HTML)
+		// Only escape in content sections (not in already-formed tags)
+
+		// Process in order of precedence (inner → outer)
+
+		// 1. Inline code: `code`
+		html = html.replace(/`([^`]+)`/g, "<code>$1</code>");
+
+		// 2. Bold: **text** or __text__
+		html = html.replace(/\*\*([^\*]+)\*\*/g, "<strong>$1</strong>");
+		html = html.replace(/__([^_]+)__/g, "<strong>$1</strong>");
+
+		// 3. Italic: *text* or _text_
+		// (be careful not to match ** or __)
+		html = html.replace(/(?<!\*)\*([^\*]+)\*(?!\*)/g, "<em>$1</em>");
+		html = html.replace(/(?<!_)_([^_]+)_(?!_)/g, "<em>$1</em>");
+
+		// 4. Links: [text](url)
+		html = html.replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+		// 5. Line breaks (double space at end of line or \n\n)
+		html = html.replace(/ {2}\n/g, "<br>\n");
+
+		// 6. Blockquotes: > quote
+		html = html.replace(/^> (.+)$/gm, "<blockquote>$1</blockquote>");
+
+		// 7. Headings (must be on own line)
+		html = html.replace(/^### ([^\n]+)$/gm, "<h3>$1</h3>");
+		html = html.replace(/^## ([^\n]+)$/gm, "<h2>$1</h2>");
+		html = html.replace(/^# ([^\n]+)$/gm, "<h1>$1</h1>");
+
+		// 8. Ordered lists: 1. 2. 3.
+		html = this._processOrderedLists(html);
+
+		// 9. Unordered lists: - * +
+		html = this._processUnorderedLists(html);
+
+		// 10. Paragraphs (blank line = new paragraph)
+		html = this._processParagraphs(html);
+
+		// 11. Horizontal rules: ---
+		html = html.replace(/^---$/gm, "<hr>");
+
+		return html.trim();
+	}
+
+	/**
+	 * Convert Markdown string to plain text
+	 */
+	static toText(markdown: string): string {
+		let text = markdown;
+
+		// Remove inline code markers: `code` → code
+		text = text.replace(/`([^`]+)`/g, "$1");
+
+		// Remove bold markers: **text** → text
+		text = text.replace(/\*\*([^\*]+)\*\*/g, "$1");
+		text = text.replace(/__([^_]+)__/g, "$1");
+
+		// Remove italic markers: *text* → text
+		text = text.replace(/\*([^\*]+)\*/g, "$1");
+		text = text.replace(/_([^_]+)_/g, "$1");
+
+		// Convert links: [text](url) → text: url
+		text = text.replace(/\[([^\]]+)\]\(([^)]+)\)/g, "$1: $2");
+
+		// Remove blockquote markers: > quote → quote
+		text = text.replace(/^> (.+)$/gm, "$1");
+
+		// Remove headings markers: # text → text
+		text = text.replace(/^#+\s+(.+)$/gm, "$1");
+
+		// Remove list markers
+		text = text.replace(/^\d+\.\s+/gm, ""); // Ordered: 1. 2. 3.
+		text = text.replace(/^[-*+]\s+/gm, ""); // Unordered: - * +
+
+		// Clean up multiple blank lines
+		text = text.replace(/\n\n\n+/g, "\n\n");
+
+		return text.trim();
+	}
+
+	/**
+	 * Process ordered lists (1. 2. 3.)
+	 */
+	private static _processOrderedLists(html: string): string {
+		// Find list blocks
+		const lines = html.split("\n");
+		let inList = false;
+		let listHtml = "";
+		const result: string[] = [];
+
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i];
+			const match = line.match(/^(\d+)\.\s+(.+)$/);
+
+			if (match) {
+				if (!inList) {
+					inList = true;
+					listHtml = `<ol>\n<li>${match[2]}</li>`;
+				} else {
+					listHtml += `\n<li>${match[2]}</li>`;
+				}
+			} else {
+				if (inList) {
+					result.push(listHtml + "\n</ol>");
+					inList = false;
+					listHtml = "";
+				}
+				result.push(line);
+			}
+		}
+
+		if (inList) {
+			result.push(listHtml + "\n</ol>");
+		}
+
+		return result.join("\n");
+	}
+
+	/**
+	 * Process unordered lists (- * +)
+	 */
+	private static _processUnorderedLists(html: string): string {
+		// Find list blocks
+		const lines = html.split("\n");
+		let inList = false;
+		let listHtml = "";
+		const result: string[] = [];
+
+		for (let i = 0; i < lines.length; i++) {
+			const line = lines[i];
+			const match = line.match(/^[-*+]\s+(.+)$/);
+
+			if (match) {
+				if (!inList) {
+					inList = true;
+					listHtml = `<ul>\n<li>${match[1]}</li>`;
+				} else {
+					listHtml += `\n<li>${match[1]}</li>`;
+				}
+			} else {
+				if (inList) {
+					result.push(listHtml + "\n</ul>");
+					inList = false;
+					listHtml = "";
+				}
+				result.push(line);
+			}
+		}
+
+		if (inList) {
+			result.push(listHtml + "\n</ul>");
+		}
+
+		return result.join("\n");
+	}
+
+	/**
+	 * Process paragraphs (blank line separated)
+	 */
+	private static _processParagraphs(html: string): string {
+		const blocks = html.split(/\n\n+/);
+		const result: string[] = [];
+
+		for (const block of blocks) {
+			if (!block.trim()) continue;
+
+			// Skip if already wrapped in tag
+			if (block.match(/^<[a-z]/) || block.match(/^<\/[a-z]/)) {
+				result.push(block);
+			} else if (block.match(/^<(h[1-6]|ul|ol|blockquote|hr|code)/)) {
+				result.push(block);
+			} else {
+				result.push(`<p>${block}</p>`);
+			}
+		}
+
+		return result.join("\n");
+	}
+}