@bytechain.cn/colamd-themes 0.3.1 → 0.5.0

package/mcp-server/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@bytechain.cn/colamd-themes-mcp",
+  "version": "0.2.0",
+  "description": "MCP Server for ColaMD-themes — expose theme extraction, export, and validation as MCP tools",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "colamd-themes-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0",
+    "tsx": "^4.0",
+    "typescript": "^5.5"
+  }
+}

package/mcp-server/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -1,36 +1,54 @@
-{
-  "name": "@bytechain.cn/colamd-themes",
-  "version": "0.3.1",
-  "description": "Theme development & export tool for ColaMD — extract formatting, generate themes, and export Markdown to HTML/PDF",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "colamd-themes": "./dist/cli.js",
-    "cthemes": "./dist/cli.js"
-  },
-  "scripts": {
-    "build": "tsc && node --input-type=commonjs -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\"",
-    "build:skills": "bash skills/build-skills.sh",
-    "dev": "tsx src/cli.ts",
-    "start": "node dist/cli.js"
-  },
-  "dependencies": {
-    "@bytechain.cn/colamd": "^1.5.2",
-    "axios": "^1.7",
-    "chalk": "^5.3",
-    "cheerio": "^1.0",
-    "commander": "^12.0",
-    "css-tree": "^3.0",
-    "handlebars": "^4.7",
-    "mammoth": "^1.8",
-    "ora": "^8.0",
-    "pdf-parse": "^1.1",
-    "puppeteer": "^24.0"
-  },
-  "devDependencies": {
-    "@types/css-tree": "^2.3",
-    "@types/node": "^22.0",
-    "tsx": "^4.0",
-    "typescript": "^5.5"
-  }
-}
+{
+  "name": "@bytechain.cn/colamd-themes",
+  "version": "0.5.0",
+  "description": "Theme development & export tool for ColaMD — extract formatting, generate themes, and export Markdown to HTML/PDF",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "colamd-themes": "./dist/cli.js",
+    "cthemes": "./dist/cli.js",
+    "colamd-themes-mcp": "./mcp-server/dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc && node --input-type=commonjs -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\"",
+    "build:skills": "bash skills/build-skills.sh",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js",
+    "build:mcp": "cd mcp-server && npm run build",
+    "build:all": "npm run build && npm run build:mcp",
+    "mcp": "node mcp-server/dist/index.js"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "colamd",
+    "themes",
+    "css",
+    "markdown",
+    "pdf",
+    "html",
+    "skill",
+    "ai-agent",
+    "agent-skill"
+  ],
+  "dependencies": {
+    "@bytechain.cn/colamd": "^1.5.2",
+    "axios": "^1.7",
+    "chalk": "^5.3",
+    "cheerio": "^1.0",
+    "commander": "^12.0",
+    "css-tree": "^3.0",
+    "handlebars": "^4.7",
+    "mammoth": "^1.8",
+    "ora": "^8.0",
+    "pdf-parse": "^1.1",
+    "pptxgenjs": "^4.0.1",
+    "puppeteer": "^24.0"
+  },
+  "devDependencies": {
+    "@types/css-tree": "^2.3",
+    "@types/node": "^22.0",
+    "tsx": "^4.0",
+    "typescript": "^5.5"
+  }
+}

package/skills/build-skills.sh

@@ -26,7 +26,7 @@ BODY=$(sed -n '/^$/,$ { /^# ColaMD/!p; }' "$SOURCE" | sed '1{/^$/d;}')
 FRONT_CLAUDE='---
 name: colamd-themes
 description: >
-  Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes.
+  Generate, validate, export, and manage ColaMD 2.7.7 contract CSS themes.
   Extract formatting from URLs, DOCX, or PDF sources; export Markdown to
   standalone HTML/PDF with themes applied; batch export; manage theme
   configuration.
@@ -36,7 +36,7 @@ FRONT_OPENCODE='---
 name: colamd-themes
 version: "1.0.0"
 description: >
-  Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes.
+  Generate, validate, export, and manage ColaMD 2.7.7 contract CSS themes.
   Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
 user-invocable: true
 allowed-tools:
@@ -52,7 +52,7 @@ FRONT_OPENCLAW='---
 id: colamd-themes
 name: ColaMD Themes
 description: >
-  Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes.
+  Generate, validate, export, and manage ColaMD 2.7.7 contract CSS themes.
   Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
 version: "1.0.0"
 icon: "\U0001F3A8"
@@ -70,7 +70,7 @@ metadata:
 
 FRONT_HERMES='---
 name: colamd-themes
-description: "Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes."
+description: "Generate, validate, export, and manage ColaMD 2.7.7 contract CSS themes."
 version: 1.0.0
 author: bytechain
 license: MIT
@@ -81,6 +81,19 @@ prerequisites:
   commands: [node, npm]
 ---'
 
+FRONT_DSH='---
+name: colamd-themes
+version: "1.0.0"
+description: >
+  Generate, validate, export, and manage ColaMD 2.7.7 contract CSS themes.
+  Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
+metadata:
+  dsh:
+    tags: [colamd, themes, css, markdown, export, pdf, html]
+prerequisites:
+  commands: [node, npm]
+---'
+
 # ── Generator functions ──
 
 generate_claude() {
@@ -123,6 +136,16 @@ generate_hermes() {
   echo "  → $file"
 }
 
+generate_dsh() {
+  local dir=".dsh/skills/colamd-themes"
+  mkdir -p "$dir"
+  local file="$dir/SKILL.md"
+  echo "$FRONT_DSH" > "$file"
+  echo "" >> "$file"
+  echo "$BODY" >> "$file"
+  echo "  → $file"
+}
+
 generate_trae() {
   local dir=".trae/rules"
   mkdir -p "$dir"
@@ -148,16 +171,18 @@ case "$TARGET" in
   openclaw) generate_openclaw ;;
   hermes)   generate_hermes ;;
   trae)     generate_trae ;;
+  dsh)      generate_dsh ;;
   all)
     generate_claude
     generate_opencode
     generate_openclaw
     generate_hermes
     generate_trae
+    generate_dsh
     ;;
   *)
     echo "Unknown agent: $TARGET" >&2
-    echo "Usage: $0 [claude|opencode|openclaw|hermes|trae|all]" >&2
+    echo "Usage: $0 [claude|opencode|openclaw|hermes|trae|dsh|all]" >&2
     exit 1
     ;;
 esac

package/skills/colamd-themes/SKILL.md

@@ -1,148 +1,180 @@
-# ColaMD Themes — Universal AI Agent Skill
-
-Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes. Extract formatting from URLs, DOCX, or PDF sources; export Markdown to standalone HTML/PDF with themes applied; batch export; manage theme configuration.
-
-## Prerequisites
-
-- Node.js ≥ 18
-- Project root: run `npm install && npm run build` before first use
-- Or run directly: `npx tsx src/cli.ts <command>`
-
-## Commands
-
-### Theme extraction
-
-```bash
-colamd-themes from-url <URL> [options]
-colamd-themes from-docx <file> [options]
-colamd-themes from-pdf <file> [options]
-colamd-themes extract <source> [options]
-```
-
-### Export to HTML / PDF
-
-```bash
-colamd-themes export-html <input.md> -t <theme> -o <output.html>
-colamd-themes export-pdf  <input.md> -t <theme> -o <output.pdf>
-colamd-themes export <inputs...> --format html|pdf -t <theme> -d <dir>
-```
-
-### Theme management
-
-```bash
-colamd-themes set-theme <name> --default
-colamd-themes set-theme <name> --css <file>
-colamd-themes set-theme <name> --css <file> --default
-colamd-themes set-theme <name> --remove
-```
-
-### Inspection
-
-```bash
-colamd-themes color-systems [-j]
-colamd-themes mermaid-presets [-j]
-colamd-themes list [-d <dir>]
-colamd-themes validate <file.css>
-```
-
-## Options
-
-### Extract options
-
-| Flag | Description |
-|------|-------------|
-| `-n, --name` | Theme name |
-| `-o, --output` | Output CSS file path |
-| `-d, --themes-dir` | Themes directory (default: `themes/`) |
-| `-c, --color-system` | Force a color system |
-| `-m, --mermaid-preset` | Force a Mermaid preset (light/dark/elegant) |
-| `-A, --auto-match` | Auto-match color system and Mermaid preset |
-
-### Export options
-
-| Flag | Description |
-|------|-------------|
-| `-t, --theme` | Theme: built-in name, custom name, or `.css` file path |
-| `-o, --output` | Output file path |
-| `-d, --output-dir` | Output directory for batch export |
-| `--format` | Batch: `html` or `pdf`; PDF: `A4`, `Letter`, `A3` |
-
-## Theme Resolution
-
-`-t, --theme` accepts:
-1. **Built-in**: `light`, `dark`, `elegant`, `newsprint`
-2. **Custom registered**: name set via `set-theme --css`
-3. **File path**: any `.css` file on disk
-
-Config: `~/.colamd-themes/config.json`
-
-## Color Systems (15 schemes)
-
-| Family | Schemes |
-|--------|---------|
-| 莫兰迪 (Morandi) | misty-rose, sage-green, dusky-blue |
-| 马卡龙 (Macaron) | strawberry, mint, lavender |
-| 北欧 (Nordic) | fjord-blue, pine-green, cloud-grey |
-| 复古 (Vintage) | amber, burgundy, forest |
-| 薄荷绿 (Mint) | matcha, spearmint, seafoam |
-
-## Mermaid Presets
-
-`light` — cool accent on light bg | `dark` — dark bg | `elegant` — warm accent on light bg
-
-## Workflow Examples
-
-### Create theme from source
-
-```bash
-colamd-themes extract <source> --name "my-theme" --auto-match
-```
-
-### Export with theme
-
-```bash
-colamd-themes export-html doc.md -t elegant -o output.html
-colamd-themes export-pdf doc.md -t my-brand -o output.pdf
-```
-
-### Batch export
-
-```bash
-colamd-themes export docs/ --format pdf -t dark -d output/
-```
-
-### Validate theme
-
-```bash
-colamd-themes validate themes/my-theme.css
-```
-
-## Rendering Pipeline
-
-Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
-
-1. Local HTTP server serves renderer ESM bundle (avoids CORS)
-2. Puppeteer navigates to server page (same-origin)
-3. `createColaMDEditor({ editable: false })` initializes Milkdown editor
-4. `applyTheme(name, customCSS?)` sets theme
-5. `setMarkdown(content)` loads document
-6. `ensureAllPluginsRendered()` waits for mermaid/KaTeX
-7. `buildExportHTML()` → standalone HTML with embedded CSS
-8. For PDF: `emulateMediaType('screen')` + `page.pdf()`
-
-## v3.0 Paradigm Constraints
-
-- No bare hex colors in selectors — use `var(--seed-*)`
-- No bare font sizes — use `var(--font-*)`
-- No Mermaid SVG selectors (handled by built-in `variables.css`)
-- `!important` only in `@media print`
-- Generated CSS ≤ 300 lines
-- Font stacks must include CJK fallback and end with generic family
-
-## Architecture
-
-```
-Source → Extractor → ThemeStyle → Color System + Mermaid Preset + Validators → CSS
-
-Markdown → Puppeteer + ColaMD Renderer → HTML / PDF
-```
+# ColaMD Themes — Universal AI Agent Skill
+
+Generate, validate, export, and manage ColaMD **2.7.7 contract** CSS themes. Extract formatting from URLs, DOCX, or PDF sources; export Markdown to standalone HTML/PDF with themes applied; batch export; manage theme configuration.
+
+## Prerequisites
+
+- Node.js ≥ 18
+- Project root: run `npm install && npm run build` before first use
+- Or run directly: `npx tsx src/cli.ts <command>`
+
+## Commands
+
+### Theme extraction
+
+```bash
+colamd-themes from-url <URL> [options]
+colamd-themes from-docx <file> [options]
+colamd-themes from-pdf <file> [options]
+colamd-themes extract <source> [options]
+```
+
+### Export to HTML / PDF
+
+```bash
+colamd-themes export-html <input.md> -t <theme> -o <output.html>
+colamd-themes export-pdf  <input.md> -t <theme> -o <output.pdf>
+colamd-themes export <inputs...> --format html|pdf -t <theme> -d <dir>
+```
+
+### Theme management
+
+```bash
+colamd-themes set-theme <name> --default
+colamd-themes set-theme <name> --css <file>
+colamd-themes set-theme <name> --css <file> --default
+colamd-themes set-theme <name> --remove
+```
+
+### Inspection
+
+```bash
+colamd-themes color-systems [-j]
+colamd-themes list [-d <dir>]
+colamd-themes validate <file.css>
+```
+
+## Options
+
+### Extract options
+
+| Flag | Description |
+|------|-------------|
+| `-n, --name` | Theme name |
+| `-o, --output` | Output CSS file path |
+| `-d, --themes-dir` | Themes directory (default: `themes/`) |
+| `-c, --color-system` | Force a color system |
+| `-A, --auto-match` | Auto-match a color system from the extracted palette |
+
+### Export options
+
+| Flag | Description |
+|------|-------------|
+| `-t, --theme` | Theme: built-in name, custom name, or `.css` file path |
+| `-o, --output` | Output file path |
+| `-d, --output-dir` | Output directory for batch export |
+| `--format` | Batch: `html` or `pdf`; PDF: `A4`, `Letter`, `A3` |
+
+## Theme Resolution
+
+`-t, --theme` accepts:
+1. **Built-in**: `light`, `dark`, `elegant`, `newsprint`
+2. **Custom registered**: name set via `set-theme --css`
+3. **File path**: any `.css` file on disk
+
+Config: `~/.colamd-themes/config.json`
+
+## Color Systems (15 schemes)
+
+| Family | Schemes |
+|--------|---------|
+| 莫兰迪 (Morandi) | misty-rose, sage-green, dusky-blue |
+| 马卡龙 (Macaron) | strawberry, mint, lavender |
+| 北欧 (Nordic) | fjord-blue, pine-green, cloud-grey |
+| 复古 (Vintage) | amber, burgundy, forest |
+| 薄荷绿 (Mint) | matcha, spearmint, seafoam |
+
+## Diagram Colors (Pele)
+
+Mermaid 20-variable presets are gone. ColaMD 2.7.7 draws diagrams with Pele, whose SVG embeds `var(--pele-*)` and resolves them in the document. Override the 9 `--pele-*` variables on `:root` if needed; defaults derive from `--code-block-bg` / `--code-block-text` / `--link-color`.
+
+## Workflow Examples
+
+### Create theme from source
+
+```bash
+colamd-themes extract <source> --name "my-theme" --auto-match
+```
+
+### Export with theme
+
+```bash
+colamd-themes export-html doc.md -t elegant -o output.html
+colamd-themes export-pdf doc.md -t my-brand -o output.pdf
+```
+
+### Batch export
+
+```bash
+colamd-themes export docs/ --format pdf -t dark -d output/
+```
+
+### Validate theme
+
+```bash
+colamd-themes validate themes/my-theme.css
+```
+
+## Rendering Pipeline
+
+Export uses Puppeteer (headless Chromium) with `@bytechain.cn/colamd/renderer`:
+
+1. Local HTTP server serves renderer ESM bundle (avoids CORS)
+2. Puppeteer navigates to server page (same-origin)
+3. `createColaMDEditor({ editable: false })` initializes Milkdown editor
+4. `applyTheme(name, customCSS?)` sets theme
+5. `setMarkdown(content)` loads document
+6. `ensureAllPluginsRendered()` waits for mermaid/KaTeX
+7. `buildExportHTML()` → standalone HTML with embedded CSS
+8. For PDF: `emulateMediaType('screen')` + `page.pdf()`
+
+## 2.7.7 Contract Constraints
+
+- Variables live in `:root`; anything in `body.theme-*` is ignored
+- Live variables only: `--bg-color --text-color --text-secondary --text-muted --border-color --link-color --code-bg --code-block-bg --code-block-text --blockquote-border --blockquote-bg --table-header-bg --selection-bg --highlight-bg --font-body --font-mono --editor-font-size --editor-column-width` + `--pele-*`
+- Dead variables are rejected: `--surface-color` `--surface-alt` `--text-dim` `--heading-color` `--accent-*` `--hr-color` `--code-color` `--code-block-color` `--table-border` `--scrollbar-thumb*` `--mermaid-*` `--radius-*` `--content-width` `--font-size-root` `--font-scale-*` `--line-height-*` `--font-heading` `--font-code` `--font-mermaid`
+- Editor selectors only: `#editor .cm-content` + `.cm-md-*` (CodeMirror 6 has no `<h1>` / `<blockquote>` elements)
+- No vertical padding on `.cm-md-blockquote` / `.cm-md-codeblock` (one div per line)
+- No `pt` units; use `px` / `em` / `rem`
+- No `!important` (except `print-color-adjust` in `@media print`)
+- Export DOM styling goes on `.colamd-document` (semantic tags), not `.cm-md-*`
+- 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. Reference `themes/template.css` and the upstream examples in `ColaMD-extend/resources/templates/themes/`.
+
+### 1. Root Block
+
+**Pitfall:** Declaring variables on `body.theme-custom`. **Correct:** `:root { ... }` — the editor inherits from the document root only.
+
+### 2. Body Text First-Line Indent
+
+**Pitfall:** `#write p` matches nothing. **Correct:** `#editor .cm-content .cm-line { text-indent: 2em; }`, then reset `text-indent: 0` on heading / quote / code / list / rule / mermaid lines.
+
+### 3. Indent Exclusion
+
+**Pitfall:** Indent leaks into quotes, code and lists because every markdown line is a `.cm-line`. **Correct:** enumerate all `.cm-md-*` line classes in the reset block (template §2.5).
+
+### 4. List Indentation
+
+**Pitfall:** Assuming `ul/ol/li` elements exist. **Correct:** CodeMirror marks list depth with `.cm-md-li-0` … `.cm-md-li-6` on the line; style those classes, never `li::before`.
+
+### 5. Quote / Code Block Padding
+
+**Pitfall:** Adding `padding: 12px 16px` to `.cm-md-blockquote`. **Correct:** only `padding-left` / `padding-right` — vertical padding is applied once per line.
+
+### 6. Pele Diagram Colors
+
+**Pitfall:** Writing `themeVariables` or Mermaid `classDef` in the theme. **Correct:** override `--pele-*` on `:root`; the SVG reads them at render time.
+
+## Architecture
+
+```
+Source → Extractor → ThemeStyle → Color System + Pele + Validators → CSS (2.7.7 contract)
+
+Markdown → Puppeteer + ColaMD renderer → HTML / PDF
+```
+
+> Export runs the 1.5.x Milkdown renderer library; the npm 2.x package (`@bytechain.cn/colamd@2.7.7`) is the Electron app distribution and no longer ships `dist/lib/colamd-renderer.js` — `renderer.ts` detects a 2.x install and asks for `@^1.5.2`. Generated CSS targets 2.7.7 (verified against the published 2.7.7 package), so it carries over unchanged.