@bytechain.cn/colamd-themes 0.3.0 → 0.3.2

package/dist/theme-store.js

@@ -2,58 +2,103 @@
  * 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"];
-function readConfig() {
-    if (!existsSync(CONFIG_FILE))
-        return { defaultTheme: "elegant", themes: {} };
+async function readConfig() {
     try {
-        return JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+        await access(CONFIG_FILE);
+        const data = await readFile(CONFIG_FILE, "utf-8");
+        return JSON.parse(data);
     }
     catch {
         return { defaultTheme: "elegant", themes: {} };
     }
 }
-function writeConfig(config) {
-    if (!existsSync(CONFIG_DIR))
-        mkdirSync(CONFIG_DIR, { recursive: true });
-    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), "utf-8");
+async function writeConfig(config) {
+    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() {
+export async function getConfig() {
     return readConfig();
 }
 /** Set the default theme (built-in name or registered custom name). */
-export function setDefaultTheme(name) {
-    const config = readConfig();
+export async function setDefaultTheme(name) {
+    const config = await readConfig();
     config.defaultTheme = name;
-    writeConfig(config);
+    await writeConfig(config);
 }
 /**
  * Register a custom theme.
  * @param name  Unique name (will be prefixed with "custom:" when applied)
  * @param cssPath  Absolute path to the CSS file
  */
-export function registerTheme(name, cssPath) {
-    const config = readConfig();
+export async function registerTheme(name, cssPath) {
+    const config = await readConfig();
     config.themes[name] = cssPath;
-    writeConfig(config);
+    await writeConfig(config);
 }
 /** Remove a registered custom theme. */
-export function unregisterTheme(name) {
-    const config = readConfig();
+export async function unregisterTheme(name) {
+    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) {
+    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) {
+    // 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.
  *
@@ -61,30 +106,35 @@ export function unregisterTheme(name) {
  * @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) {
-    const config = readConfig();
+export async function resolveTheme(name) {
+    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
     if (BUILTIN_THEMES.includes(resolved)) {
         return { themeName: resolved };
     }
     // 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,
+    };
 }
 //# sourceMappingURL=theme-store.js.map

package/dist/theme-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"theme-store.js","sourceRoot":"","sources":["../src/theme-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"theme-store.js","sourceRoot":"","sources":["../src/theme-store.ts"],"names":[],"mappings":"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"}

package/dist/utils/cli-utils.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Shared utility functions for CLI commands.
+ * Provides consistent file path resolution and error handling.
+ */
+/**
+ * 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 declare function resolveInputPath(input: string): string;
+/**
+ * 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 declare function resolveOutputPath(inputPath: string, output?: string, ext?: string): string;
+/**
+ * Get base filename without extension for use as document title.
+ *
+ * @param filePath  Absolute or relative file path
+ * @returns Filename without extension
+ */
+export declare function getDocumentTitle(filePath: string): string;
+/**
+ * Standard error codes for CLI operations.
+ * Enables consistent error handling across all commands.
+ */
+export declare 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 declare class CLIError extends Error {
+    code: ErrorCode;
+    cause?: Error | undefined;
+    constructor(message: string, code?: ErrorCode, cause?: Error | undefined);
+}

package/dist/utils/cli-utils.js

@@ -0,0 +1,80 @@
+/**
+ * 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) {
+    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, output, ext = ".html") {
+    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) {
+    return basename(filePath, ".md");
+}
+/**
+ * Standard error codes for CLI operations.
+ * Enables consistent error handling across all commands.
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    /** Input file not found */
+    ErrorCode[ErrorCode["FILE_NOT_FOUND"] = 1] = "FILE_NOT_FOUND";
+    /** Theme resolution failed */
+    ErrorCode[ErrorCode["THEME_ERROR"] = 2] = "THEME_ERROR";
+    /** Rendering/export failed */
+    ErrorCode[ErrorCode["RENDER_ERROR"] = 3] = "RENDER_ERROR";
+    /** Invalid arguments or configuration */
+    ErrorCode[ErrorCode["INVALID_INPUT"] = 4] = "INVALID_INPUT";
+    /** Unknown/unexpected error */
+    ErrorCode[ErrorCode["UNKNOWN"] = 99] = "UNKNOWN";
+})(ErrorCode || (ErrorCode = {}));
+/**
+ * Custom error class for CLI operations with structured error codes.
+ * Replaces direct process.exit() calls for better error propagation.
+ */
+export class CLIError extends Error {
+    code;
+    cause;
+    constructor(message, code = ErrorCode.UNKNOWN, cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = "CLIError";
+        if (cause) {
+            this.stack = `${this.message}\nCaused by: ${cause.stack}`;
+        }
+    }
+}
+//# sourceMappingURL=cli-utils.js.map

package/dist/utils/cli-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-utils.js","sourceRoot":"","sources":["../../src/utils/cli-utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;IACvE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAiB,EAAE,MAAe,EAAE,GAAG,GAAG,OAAO;IACjF,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,QAAQ,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAN,IAAY,SAWX;AAXD,WAAY,SAAS;IACnB,2BAA2B;IAC3B,6DAAkB,CAAA;IAClB,8BAA8B;IAC9B,uDAAe,CAAA;IACf,8BAA8B;IAC9B,yDAAgB,CAAA;IAChB,yCAAyC;IACzC,2DAAiB,CAAA;IACjB,+BAA+B;IAC/B,gDAAY,CAAA;AACd,CAAC,EAXW,SAAS,KAAT,SAAS,QAWpB;AAED;;;GAGG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAGxB;IACA;IAHT,YACE,OAAe,EACR,OAAkB,SAAS,CAAC,OAAO,EACnC,KAAa;QAEpB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHR,SAAI,GAAJ,IAAI,CAA+B;QACnC,UAAK,GAAL,KAAK,CAAQ;QAGpB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,CAAC,KAAK,GAAG,GAAG,IAAI,CAAC,OAAO,gBAAgB,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5D,CAAC;IACH,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytechain.cn/colamd-themes",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Theme development & export tool for ColaMD — extract formatting, generate themes, and export Markdown to HTML/PDF",
   "type": "module",
   "main": "dist/index.js",

package/skills/colamd-themes/SKILL.md

@@ -139,6 +139,36 @@ Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
 - Generated CSS ≤ 300 lines
 - Font stacks must include CJK fallback and end with generic family
 
+## CSS Pitfall Quick Reference
+
+> When adjusting themes, follow these rules strictly. For each step, reference the corresponding pattern in `academic-paper.css`.
+
+### 1. Screen & Print Must Stay in Sync
+
+Every rule in SECTION 5 must have a mirror copy in SECTION 6 `@media print`. Reference the `SECTION 5 / SECTION 6` correspondence in `academic-paper.css`.
+
+### 2. Body Text First-Line Indent
+
+**Pitfall:** `#write p` does not match. **Correct:** Reference `academic-paper.css` §5.3 directly — use `body.theme-custom p, body.theme-custom #write > p`, with `margin: 0` set beforehand.
+
+### 3. Indent Exclusion (Do Not Pollute Lists / Tables / Diagrams)
+
+**Pitfall:** The `p` selector hits paragraphs inside all nested containers. **Correct:** Reference the exclusion block below `swiss-design.css` §5.2.1 — apply `text-indent: 0` uniformly to `li / li p / td p / th p / blockquote p / .mermaid-block p / figure p / pre p`.
+
+### 4. List Indentation (Hardest Pitfall)
+
+**Pitfall:** `padding-left` does not move the bullet/number; missing the `#editor .ProseMirror` editor selector; missing `li::before` and `li > p` inline conversion.
+
+**Correct:** Reference `academic-paper.css` §5.7 directly — copy its full selector structure (`#editor .ProseMirror > ul/ol` + `#write > ul/ol:first-of-type` + `li::before` + `#editor .ProseMirror li > p`). Use `margin-left: 2em` for indentation instead of `padding-left`. For Swiss style, keep `list-style-position: outside` and do NOT change to `none`.
+
+### 5. Mermaid CJK Text Overflow
+
+**Pitfall:** Multi-line `<br/>` nodes have incorrect width/height calculations. **Correct:** ≤ 2 lines per node + `fontSize: 14px` + simplify text (use `·` instead of `/`, remove redundant modifiers).
+
+### 6. Mermaid classDef Does Not Inherit themeVariables
+
+**Pitfall:** Assuming `themeVariables` sets text color so you don't need to repeat it. **Correct:** `classDef` must explicitly declare all three properties: `fill / color / stroke`.
+
 ## Architecture
 
 ```