@bytechain.cn/colamd-themes 0.3.0 → 0.3.2

package/src/generator.ts

@@ -1,7 +1,7 @@
 /** CSS theme file generator — v3.0 seed palette pipeline. */
 
 import Handlebars from "handlebars";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, statSync } from "node:fs";
 import { join, dirname, isAbsolute } from "node:path";
 import { fileURLToPath } from "node:url";
 import type { ThemeStyle } from "./models.js";
@@ -20,14 +20,95 @@ Handlebars.registerHelper("rgba", (hex: unknown, alpha: unknown) => {
   return toRgba(String(hex), Number(alpha));
 });
 
-let compiledTemplate: HandlebarsTemplateDelegate<ThemeStyle> | null = null;
+// ── Template Cache with Size Limits and Auto-Invalidation ──
 
-function getTemplate(): HandlebarsTemplateDelegate<ThemeStyle> {
-  if (!compiledTemplate) {
-    const source = readFileSync(templatePath, "utf-8");
-    compiledTemplate = Handlebars.compile(source, { noEscape: true });
+interface CachedTemplate {
+  compiled: HandlebarsTemplateDelegate<ThemeStyle>;
+  mtimeMs: number;
+  compiledAt: number;
+}
+
+const TEMPLATE_CACHE_MAX_SIZE = 10;
+const TEMPLATE_CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const templateCache = new Map<string, CachedTemplate>();
+
+/**
+ * Get or compile a Handlebars template with caching.
+ *
+ * Features:
+ * - LRU-style cache (max 10 templates)
+ * - File modification time detection for auto-invalidation
+ * - TTL-based expiration (30 minutes)
+ * - Automatic cleanup of expired entries on access
+ */
+function getTemplate(path?: string): HandlebarsTemplateDelegate<ThemeStyle> {
+  const key = path || templatePath;
+
+  // Check cache hit
+  const cached = templateCache.get(key);
+  if (cached) {
+    // Check TTL expiration
+    if (Date.now() - cached.compiledAt > TEMPLATE_CACHE_TTL_MS) {
+      templateCache.delete(key);
+    }
+    // Check file modification time
+    else {
+      try {
+        const stats = statSync(key);
+        if (stats.mtimeMs > cached.mtimeMs) {
+          templateCache.delete(key);
+        } else {
+          return cached.compiled;
+        }
+      } catch {
+        return cached.compiled;
+      }
+    }
+  }
+
+  // Enforce max cache size (evict oldest entry)
+  if (templateCache.size >= TEMPLATE_CACHE_MAX_SIZE) {
+    let oldestKey: string | null = null;
+    let oldestTime = Infinity;
+
+    for (const [k, v] of templateCache.entries()) {
+      if (v.compiledAt < oldestTime) {
+        oldestTime = v.compiledAt;
+        oldestKey = k;
+      }
+    }
+
+    if (oldestKey) {
+      templateCache.delete(oldestKey);
+    }
   }
-  return compiledTemplate;
+
+  // Compile new template
+  const source = readFileSync(key, "utf-8");
+  const compiled = Handlebars.compile(source, { noEscape: true });
+
+  // Get modification time for invalidation
+  let mtimeMs = 0;
+  try {
+    mtimeMs = statSync(key).mtimeMs;
+  } catch {
+    mtimeMs = Date.now();
+  }
+
+  templateCache.set(key, {
+    compiled,
+    mtimeMs,
+    compiledAt: Date.now(),
+  });
+
+  return compiled;
+}
+
+/**
+ * Clear all cached templates to free memory.
+ */
+export function clearTemplateCache(): void {
+  templateCache.clear();
 }
 
 // ── Pipeline ──

package/src/renderer.ts

@@ -15,7 +15,7 @@
 import puppeteer, { type Browser, type Page } from "puppeteer";
 import { createServer, type Server } from "node:http";
 import { readFileSync, existsSync, createReadStream } from "node:fs";
-import { resolve, dirname } from "node:path";
+import { resolve, dirname, join } from "node:path";
 
 // ── Types ──
 
@@ -69,6 +69,7 @@ function findRendererPath(): string {
 const SHELL_HTML = `<!DOCTYPE html>
 <html><head>
 <meta charset="utf-8">
+<link rel="stylesheet" href="/colamd.css">
 <style>body{margin:0;padding:0}#editor{width:100%;min-height:100vh}</style>
 </head><body><div id="editor"></div></body></html>`;
 
@@ -78,6 +79,7 @@ interface LocalServer {
 }
 
 function startLocalServer(rendererPath: string): Promise<LocalServer> {
+  const cssPath = join(dirname(rendererPath), "colamd.css");
   return new Promise((resolveStart, reject) => {
     const server: Server = createServer((req, res) => {
       if (req.url === "/" || req.url === "/index.html") {
@@ -86,6 +88,9 @@ function startLocalServer(rendererPath: string): Promise<LocalServer> {
       } else if (req.url === "/colamd-renderer.js") {
         res.writeHead(200, { "Content-Type": "application/javascript; charset=utf-8" });
         createReadStream(rendererPath).pipe(res);
+      } else if (req.url === "/colamd.css") {
+        res.writeHead(200, { "Content-Type": "text/css; charset=utf-8" });
+        createReadStream(cssPath).pipe(res);
       } else {
         res.writeHead(404);
         res.end();
@@ -106,6 +111,69 @@ function startLocalServer(rendererPath: string): Promise<LocalServer> {
   });
 }
 
+// ── Export CSS variable supplementation ──
+
+/**
+ * CSS variables that colamd-renderer.js's buildExportHTML() may not include.
+ * Injected as a post-processing step so we don't need to patch node_modules.
+ */
+const EXTRA_CSS_VARIABLES: Record<string, string> = {
+  "--seed-accent": "var(--accent-color, #333)",           // hardcoded — not in colamd.css
+  "--seed-accent-light": "var(--accent-light, #e0e0e0)",  // hardcoded — not in colamd.css
+  "--seed-accent-dark": "var(--accent-dark, #111)",       // hardcoded — not in colamd.css
+  "--seed-surface": "var(--bg-color, #fff)",               // chains to colamd.css --bg-color
+  "--seed-panel": "var(--surface-color, #f5f5f5)",        // hardcoded — not in colamd.css
+  "--seed-panel-alt": "var(--surface-alt, #eee)",          // hardcoded — not in colamd.css
+  "--seed-ink": "var(--text-color, #333)",                 // chains to colamd.css --text-color
+  "--seed-ink-muted": "var(--text-muted, #888)",           // chains to colamd.css --text-muted
+  "--seed-ink-dim": "var(--text-dim, #aaa)",               // hardcoded — not in colamd.css
+  "--seed-border": "var(--border-color, #ddd)",            // chains to colamd.css --border-color
+  "--seed-border-strong": "var(--table-border, #ccc)",     // hardcoded — not in colamd.css
+  "--heading-color": "var(--text-color, #333)",            // chains to colamd.css --text-color
+  "--code-color": "var(--code-block-text, #333)",          // chains to colamd.css --code-block-text
+  "--hr-color": "var(--border-color, #ddd)",               // chains to colamd.css --border-color
+  "--table-header-text": "var(--text-color, #333)",        // chains to colamd.css --text-color
+  "--table-border": "var(--border-color, #ddd)",           // chains to colamd.css --border-color
+  "--scrollbar-thumb": "var(--border-color, #ccc)",        // chains to colamd.css --border-color
+  "--scrollbar-thumb-hover": "var(--text-muted, #999)",    // chains to colamd.css --text-muted
+  "--content-width": "780px",                              // hardcoded — no colamd.css equivalent
+  "--line-height-body": "1.75",                            // hardcoded — no colamd.css equivalent
+  "--line-height-heading": "1.3",                          // hardcoded — no colamd.css equivalent
+  "--line-height-code": "1.6",                             // hardcoded — no colamd.css equivalent
+};
+
+/**
+ * Supplement a buildExportHTML() result with extra CSS variables
+ * that colamd-renderer.js may not include. Only adds variables
+ * that are not already present in the HTML's <style> block.
+ */
+function supplementExportHTML(html: string): string {
+  // Find the existing CSS variables (--name: value; or --name:value;)
+  const existing = new Set<string>();
+  const varRe = /(--[\w-]+)\s*:/g;
+  let vm: RegExpExecArray | null;
+  while ((vm = varRe.exec(html)) !== null) {
+    existing.add(vm[1]);
+  }
+
+  // Build style block for only missing variables
+  const missingLines: string[] = [];
+  for (const [name, fallback] of Object.entries(EXTRA_CSS_VARIABLES)) {
+    if (!existing.has(name)) {
+      missingLines.push(`  ${name}: ${fallback};`);
+    }
+  }
+
+  if (missingLines.length === 0) return html;
+
+  // Inject into :root block, or before first style rule
+  const supplement = `\n  /* colamd-themes supplement */\n${missingLines.join("\n")}\n`;
+  return html.replace(
+    /(<style[^>]*>)/i,
+    (match, styleTag) => `${styleTag}:root {\n${supplement}}`
+  );
+}
+
 // ── Renderer ──
 
 export class ColamdRenderer {
@@ -199,10 +267,13 @@ export class ColamdRenderer {
       return (window as any).__colamdHandle.buildExportHTML();
     });
 
+    // Post-process: supplement any CSS variables that colamd-renderer.js may not include
+    const supplementedHtml = supplementExportHTML(html);
+
     // Inject custom title if provided
     const finalHtml = input.title
-      ? html.replace(/<title>[^<]*<\/title>/, `<title>${input.title}</title>`)
-      : html;
+      ? supplementedHtml.replace(/<title>[^<]*<\/title>/, `<title>${input.title}</title>`)
+      : supplementedHtml;
 
     return { html: finalHtml };
   }
@@ -220,8 +291,10 @@ export class ColamdRenderer {
     const pdfPage = await this.browser!.newPage();
     await pdfPage.setContent(html, { waitUntil: "load", timeout: 30000 });
 
-    // Emulate screen media to preserve theme colors
-    await pdfPage.emulateMediaType("screen");
+    // NOTE: Do NOT use emulateMediaType("screen") here.
+    // The CSS template includes comprehensive @media print rules (SECTION 6)
+    // with !important declarations and print-color-adjust: exact for proper styling.
+    // Using screen mode would prevent these print-specific styles from applying.
 
     const pdfBuffer = await pdfPage.pdf({
       format: options.format ?? "A4",
@@ -233,17 +306,26 @@ export class ColamdRenderer {
     return Buffer.from(pdfBuffer);
   }
 
-  /** Shut down the browser and local server. */
+  /** Shut down the browser and local server with proper resource cleanup. */
   async close(): Promise<void> {
-    if (this.browser) {
-      await this.browser.close();
-      this.browser = null;
-      this.page = null;
+    try {
+      // Explicitly close page first to prevent zombie processes
+      if (this.page) {
+        await this.page.close().catch(() => {});
+        this.page = null;
+      }
+
+      if (this.browser) {
+        await this.browser.close();
+        this.browser = null;
+      }
+    } finally {
       this.ready = false;
-    }
-    if (this.server) {
-      await this.server.close();
-      this.server = null;
+
+      if (this.server) {
+        await this.server.close();
+        this.server = null;
+      }
     }
   }
 }

package/src/theme-store.ts

@@ -2,15 +2,20 @@
  * Theme configuration persistence.
  *
  * Stores default theme and registered custom themes in ~/.colamd-themes/config.json
+ * Uses async file I/O to avoid blocking the event loop.
  */
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { mkdir, readFile, writeFile, access } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { join, basename } from "node:path";
 import { homedir } from "node:os";
 
 const CONFIG_DIR = join(homedir(), ".colamd-themes");
 const CONFIG_FILE = join(CONFIG_DIR, "config.json");
 
+/** Maximum allowed CSS file size (1MB) to prevent OOM attacks */
+const MAX_CSS_SIZE = 1024 * 1024;
+
 /** Built-in themes provided by @bytechain.cn/colamd */
 export const BUILTIN_THEMES = ["light", "dark", "elegant", "newsprint"] as const;
 export type BuiltinTheme = (typeof BUILTIN_THEMES)[number];
@@ -22,30 +27,35 @@ export interface ThemeConfig {
   themes: Record<string, string>;
 }
 
-function readConfig(): ThemeConfig {
-  if (!existsSync(CONFIG_FILE)) return { defaultTheme: "elegant", themes: {} };
+async function readConfig(): Promise<ThemeConfig> {
   try {
-    return JSON.parse(readFileSync(CONFIG_FILE, "utf-8")) as ThemeConfig;
+    await access(CONFIG_FILE);
+    const data = await readFile(CONFIG_FILE, "utf-8");
+    return JSON.parse(data) as ThemeConfig;
   } catch {
     return { defaultTheme: "elegant", themes: {} };
   }
 }
 
-function writeConfig(config: ThemeConfig): void {
-  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
-  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+async function writeConfig(config: ThemeConfig): Promise<void> {
+  try {
+    await access(CONFIG_DIR);
+  } catch {
+    await mkdir(CONFIG_DIR, { recursive: true });
+  }
+  await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
 }
 
 /** Get the full config. */
-export function getConfig(): ThemeConfig {
+export async function getConfig(): Promise<ThemeConfig> {
   return readConfig();
 }
 
 /** Set the default theme (built-in name or registered custom name). */
-export function setDefaultTheme(name: string): void {
-  const config = readConfig();
+export async function setDefaultTheme(name: string): Promise<void> {
+  const config = await readConfig();
   config.defaultTheme = name;
-  writeConfig(config);
+  await writeConfig(config);
 }
 
 /**
@@ -53,21 +63,64 @@ export function setDefaultTheme(name: string): void {
  * @param name  Unique name (will be prefixed with "custom:" when applied)
  * @param cssPath  Absolute path to the CSS file
  */
-export function registerTheme(name: string, cssPath: string): void {
-  const config = readConfig();
+export async function registerTheme(name: string, cssPath: string): Promise<void> {
+  const config = await readConfig();
   config.themes[name] = cssPath;
-  writeConfig(config);
+  await writeConfig(config);
 }
 
 /** Remove a registered custom theme. */
-export function unregisterTheme(name: string): boolean {
-  const config = readConfig();
+export async function unregisterTheme(name: string): Promise<boolean> {
+  const config = await readConfig();
   if (!(name in config.themes)) return false;
   delete config.themes[name];
-  writeConfig(config);
+  await writeConfig(config);
   return true;
 }
 
+/**
+ * Sanitize theme name from file path.
+ * Removes special characters and limits length to prevent injection.
+ */
+function sanitizeName(path: string): string {
+  return basename(path, ".css")
+    .replace(/[^a-zA-Z0-9_-]/g, "-")
+    .replace(/-+/g, "-")
+    .slice(0, 50) || "custom";
+}
+
+/**
+ * Validate CSS file before reading.
+ * Checks extension, size, and basic content validity.
+ */
+async function validateCssFile(filePath: string): Promise<void> {
+  // Check file extension
+  if (!filePath.toLowerCase().endsWith(".css")) {
+    throw new Error(`Theme file must have .css extension: ${filePath}`);
+  }
+
+  // Check file size (synchronous stat is acceptable for metadata)
+  let stats;
+  try {
+    stats = statSync(filePath);
+  } catch {
+    throw new Error(`Cannot access theme file: ${filePath}`);
+  }
+
+  if (stats.size > MAX_CSS_SIZE) {
+    throw new Error(
+      `Theme file too large (${(stats.size / 1024).toFixed(1)}KB). ` +
+      `Maximum size: ${(MAX_CSS_SIZE / 1024).toFixed(0)}MB`
+    );
+  }
+
+  // Read and validate content
+  const content = await readFile(filePath, "utf-8");
+  if (content.length < 10) {
+    throw new Error(`Theme file appears to be empty or invalid: ${filePath}`);
+  }
+}
+
 /**
  * Resolve a theme name to the arguments needed by the ColaMD renderer.
  *
@@ -75,20 +128,19 @@ export function unregisterTheme(name: string): boolean {
  * @returns { themeName, customCSS? } — themeName is either a built-in name
  *          or "custom:<name>"; customCSS is the CSS content for custom themes.
  */
-export function resolveTheme(name?: string): {
+export async function resolveTheme(name?: string): Promise<{
   themeName: string;
   customCSS?: string;
-} {
-  const config = readConfig();
+}> {
+  const config = await readConfig();
   const resolved = name ?? config.defaultTheme;
 
   // Check if it's a registered custom theme
   if (config.themes[resolved]) {
     const cssPath = config.themes[resolved];
-    if (!existsSync(cssPath)) {
-      throw new Error(`Custom theme CSS file not found: ${cssPath}`);
-    }
-    return { themeName: `custom:${resolved}`, customCSS: readFileSync(cssPath, "utf-8") };
+    await validateCssFile(cssPath);
+    const customCSS = await readFile(cssPath, "utf-8");
+    return { themeName: `custom:${resolved}`, customCSS };
   }
 
   // Check if it's a built-in theme
@@ -97,16 +149,22 @@ export function resolveTheme(name?: string): {
   }
 
   // Treat as a direct CSS file path
-  if (existsSync(resolved)) {
-    const nameFromPath = resolved.replace(/\.css$/i, "").split("/").pop() ?? "custom";
-    return {
-      themeName: `custom:${nameFromPath}`,
-      customCSS: readFileSync(resolved, "utf-8"),
-    };
+  try {
+    await access(resolved);
+  } catch {
+    throw new Error(
+      `Unknown theme: "${resolved}". Use a built-in theme (${BUILTIN_THEMES.join(", ")}), ` +
+      `a registered custom theme, or a path to a .css file.`
+    );
   }
 
-  throw new Error(
-    `Unknown theme: "${resolved}". Use a built-in theme (${BUILTIN_THEMES.join(", ")}), ` +
-    `a registered custom theme, or a path to a .css file.`
-  );
+  // Validate and read direct CSS file
+  await validateCssFile(resolved);
+  const nameFromPath = sanitizeName(resolved);
+  const customCSS = await readFile(resolved, "utf-8");
+
+  return {
+    themeName: `custom:${nameFromPath}`,
+    customCSS,
+  };
 }

package/src/utils/cli-utils.ts

@@ -0,0 +1,84 @@
+/**
+ * Shared utility functions for CLI commands.
+ * Provides consistent file path resolution and error handling.
+ */
+
+import { existsSync } from "node:fs";
+import { resolve, isAbsolute, basename } from "node:path";
+
+/**
+ * Resolve input file path with validation.
+ * Converts relative paths to absolute and checks existence.
+ *
+ * @param input  File path provided by user
+ * @returns Resolved absolute path
+ * @throws Error if file does not exist
+ */
+export function resolveInputPath(input: string): string {
+  const path = isAbsolute(input) ? input : resolve(process.cwd(), input);
+  if (!existsSync(path)) {
+    throw new Error(`File not found: ${path}`);
+  }
+  return path;
+}
+
+/**
+ * Resolve output file path with sensible defaults.
+ * If output path is not specified, derives it from input path by replacing extension.
+ *
+ * @param inputPath  Resolved absolute input path
+ * @param output  Optional explicit output path
+ * @param ext  Target extension (default: ".html")
+ * @returns Resolved absolute output path
+ */
+export function resolveOutputPath(inputPath: string, output?: string, ext = ".html"): string {
+  if (output) {
+    return isAbsolute(output) ? output : resolve(process.cwd(), output);
+  }
+  return inputPath.replace(/\.md$/i, ext);
+}
+
+/**
+ * Get base filename without extension for use as document title.
+ *
+ * @param filePath  Absolute or relative file path
+ * @returns Filename without extension
+ */
+export function getDocumentTitle(filePath: string): string {
+  return basename(filePath, ".md");
+}
+
+/**
+ * Standard error codes for CLI operations.
+ * Enables consistent error handling across all commands.
+ */
+export enum ErrorCode {
+  /** Input file not found */
+  FILE_NOT_FOUND = 1,
+  /** Theme resolution failed */
+  THEME_ERROR = 2,
+  /** Rendering/export failed */
+  RENDER_ERROR = 3,
+  /** Invalid arguments or configuration */
+  INVALID_INPUT = 4,
+  /** Unknown/unexpected error */
+  UNKNOWN = 99,
+}
+
+/**
+ * Custom error class for CLI operations with structured error codes.
+ * Replaces direct process.exit() calls for better error propagation.
+ */
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public code: ErrorCode = ErrorCode.UNKNOWN,
+    public cause?: Error
+  ) {
+    super(message);
+    this.name = "CLIError";
+    if (cause) {
+      this.stack = `${this.message}\nCaused by: ${cause.stack}`;
+    }
+  }
+}