@bytechain.cn/colamd-themes 0.3.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@bytechain.cn/colamd-themes",
+  "version": "0.3.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"
+  },
+  "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"
+  }
+}

package/skills/build-skills.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+#
+# Build agent-specific skill files from the canonical source.
+#
+# Usage:
+#   bash skills/build-skills.sh          # generate all
+#   bash skills/build-skills.sh claude   # generate for one agent
+#
+# Source:  skills/colamd-themes/SKILL.md
+# Output:  .{agent}/skills/colamd-themes/SKILL.md (or equivalent)
+
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+SOURCE="skills/colamd-themes/SKILL.md"
+if [[ ! -f "$SOURCE" ]]; then
+  echo "Error: Source skill not found: $SOURCE" >&2
+  exit 1
+fi
+
+# Read the body (everything after the first blank line following the heading)
+BODY=$(sed -n '/^$/,$ { /^# ColaMD/!p; }' "$SOURCE" | sed '1{/^$/d;}')
+
+# ── Frontmatter templates ──
+
+FRONT_CLAUDE='---
+name: colamd-themes
+description: >
+  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.
+---'
+
+FRONT_OPENCODE='---
+name: colamd-themes
+version: "1.0.0"
+description: >
+  Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes.
+  Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
+user-invocable: true
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+---'
+
+FRONT_OPENCLAW='---
+id: colamd-themes
+name: ColaMD Themes
+description: >
+  Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes.
+  Extract from URLs/DOCX/PDF; export Markdown to HTML/PDF; batch export.
+version: "1.0.0"
+icon: "\U0001F3A8"
+author: bytechain
+homepage: https://github.com/byteuser1977/ColaMD-themes
+user-invocable: true
+metadata:
+  openclaw:
+    os: [darwin, linux, win32]
+  clawdbot:
+    emoji: "\U0001F3A8"
+    requires:
+      bins: [node, npm]
+---'
+
+FRONT_HERMES='---
+name: colamd-themes
+description: "Generate, validate, export, and manage ColaMD v3.0 paradigm CSS themes."
+version: 1.0.0
+author: bytechain
+license: MIT
+metadata:
+  hermes:
+    tags: [colamd, themes, css, markdown, export, pdf, html]
+prerequisites:
+  commands: [node, npm]
+---'
+
+# ── Generator functions ──
+
+generate_claude() {
+  local dir=".claude/skills"
+  mkdir -p "$dir"
+  local file="$dir/colamd-themes.skill.md"
+  echo "$FRONT_CLAUDE" > "$file"
+  echo "" >> "$file"
+  echo "$BODY" >> "$file"
+  echo "  → $file"
+}
+
+generate_opencode() {
+  local dir=".opencode/skills/colamd-themes"
+  mkdir -p "$dir"
+  local file="$dir/SKILL.md"
+  echo "$FRONT_OPENCODE" > "$file"
+  echo "" >> "$file"
+  echo "$BODY" >> "$file"
+  echo "  → $file"
+}
+
+generate_openclaw() {
+  local dir=".openclaw/skills/colamd-themes"
+  mkdir -p "$dir"
+  local file="$dir/SKILL.md"
+  echo "$FRONT_OPENCLAW" > "$file"
+  echo "" >> "$file"
+  echo "$BODY" >> "$file"
+  echo "  → $file"
+}
+
+generate_hermes() {
+  local dir=".hermes/skills/tools/colamd-themes"
+  mkdir -p "$dir"
+  local file="$dir/SKILL.md"
+  echo "$FRONT_HERMES" > "$file"
+  echo "" >> "$file"
+  echo "$BODY" >> "$file"
+  echo "  → $file"
+}
+
+generate_trae() {
+  local dir=".trae/rules"
+  mkdir -p "$dir"
+  local file="$dir/colamd-themes.md"
+  # Trae uses plain Markdown, no YAML frontmatter
+  echo "# ColaMD Themes Skill Instructions" > "$file"
+  echo "" >> "$file"
+  echo "When the user asks to create, validate, export, or manage ColaMD themes, use the following CLI tool:" >> "$file"
+  echo "" >> "$file"
+  echo "$BODY" >> "$file"
+  echo "  → $file"
+}
+
+# ── Main ──
+
+TARGET="${1:-all}"
+echo "Building skill files from: $SOURCE"
+echo ""
+
+case "$TARGET" in
+  claude)   generate_claude ;;
+  opencode) generate_opencode ;;
+  openclaw) generate_openclaw ;;
+  hermes)   generate_hermes ;;
+  trae)     generate_trae ;;
+  all)
+    generate_claude
+    generate_opencode
+    generate_openclaw
+    generate_hermes
+    generate_trae
+    ;;
+  *)
+    echo "Unknown agent: $TARGET" >&2
+    echo "Usage: $0 [claude|opencode|openclaw|hermes|trae|all]" >&2
+    exit 1
+    ;;
+esac
+
+echo ""
+echo "Done. Skill files generated."

package/skills/colamd-themes/SKILL.md

@@ -0,0 +1,148 @@
+# 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
+```

package/src/cli.ts

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join, isAbsolute } from "node:path";
+import chalk from "chalk";
+import ora from "ora";
+import { UrlExtractor } from "./extractors/url-extractor.js";
+import { DocxExtractor } from "./extractors/docx-extractor.js";
+import { PdfExtractor } from "./extractors/pdf-extractor.js";
+import type { Extractor } from "./extractors/base.js";
+import { writeThemeFile } from "./generator.js";
+import { COLOR_SYSTEMS, getColorSystem } from "./color-systems.js";
+import { MERMAID_PRESETS } from "./mermaid-presets.js";
+import { validateSeedPalette, summarizeIssues } from "./validators.js";
+import type { ThemeStyle } from "./models.js";
+import { registerExportCommands } from "./export-cli.js";
+
+const program = new Command();
+
+program
+  .name("colamd-themes")
+  .description("ColaMD Theme Development Tool — extract formatting and generate v3.0 paradigm CSS themes")
+  .version("0.2.0");
+
+// ── Shared extract options builder ──
+
+function addExtractOptions(cmd: Command): Command {
+  return cmd
+    .option("-n, --name <name>", "Theme name")
+    .option("-o, --output <path>", "Output CSS file path")
+    .option("-d, --themes-dir <dir>", "Themes directory", "themes")
+    .option("-c, --color-system <id>", "Force a color system (use `color-systems` to list)")
+    .option("-m, --mermaid-preset <id>", "Force a Mermaid preset (light/dark/elegant)")
+    .option("-A, --auto-match", "Auto-match color system and mermaid preset");
+}
+
+async function runExtraction(
+  extractor: Extractor,
+  source: string,
+  options: Record<string, string>
+) {
+  const spinner = ora("Extracting styles...").start();
+  try {
+    const style = await extractor.extract(source);
+    if (options.name) style.name = options.name;
+    if (options.colorSystem) {
+      const cs = getColorSystem(options.colorSystem);
+      if (!cs) { spinner.fail(`Unknown color system: ${options.colorSystem}`); process.exit(1); }
+      style.seed = { ...cs.palette };
+      style.colorSystemId = cs.id;
+    }
+    if (options.mermaidPreset) style.mermaidPresetId = options.mermaidPreset;
+    if (options.autoMatch) { style.colorSystemId = ""; style.mermaidPresetId = ""; }
+    spinner.text = "Generating CSS (v3.0 paradigm)...";
+    const outputPath = writeThemeFile(style, options.output || options.themesDir);
+    spinner.succeed(chalk.green(`Theme "${style.name}" generated: ${outputPath}`));
+    printSummary(style);
+  } catch (err) {
+    spinner.fail(chalk.red(`Failed: ${(err as Error).message}`));
+    process.exit(1);
+  }
+}
+
+// ── from-url ──
+addExtractOptions(
+  program.command("from-url")
+    .description("Extract theme from a web page URL")
+    .argument("<url>", "URL of the web page")
+).action(async (url: string, options: Record<string, string>) => {
+  await runExtraction(new UrlExtractor(), url, options);
+});
+
+// ── from-docx ──
+addExtractOptions(
+  program.command("from-docx")
+    .description("Extract theme from a .docx document")
+    .argument("<file>", "Path to the .docx file")
+).action(async (file: string, options: Record<string, string>) => {
+  if (!existsSync(file)) { console.error(chalk.red(`File not found: ${file}`)); process.exit(1); }
+  await runExtraction(new DocxExtractor(), file, options);
+});
+
+// ── from-pdf ──
+addExtractOptions(
+  program.command("from-pdf")
+    .description("Extract theme from a PDF document")
+    .argument("<file>", "Path to the PDF file")
+).action(async (file: string, options: Record<string, string>) => {
+  if (!existsSync(file)) { console.error(chalk.red(`File not found: ${file}`)); process.exit(1); }
+  await runExtraction(new PdfExtractor(), file, options);
+});
+
+// ── extract (auto-detect) ──
+addExtractOptions(
+  program.command("extract")
+    .description("Auto-detect source type and extract theme")
+    .argument("<source>", "URL, .docx file, or .pdf file")
+).action(async (source: string, options: Record<string, string>) => {
+  const extractors: Extractor[] = [new UrlExtractor(), new DocxExtractor(), new PdfExtractor()];
+  const ext = extractors.find((e) => e.canHandle(source));
+  if (!ext) { console.error(chalk.red(`Cannot detect source type for: ${source}`)); process.exit(1); }
+  await runExtraction(ext, source, options);
+});
+
+// ── color-systems ──
+program
+  .command("color-systems")
+  .description("List all 15 built-in color systems")
+  .option("-j, --json", "Output as JSON")
+  .action((options: Record<string, string>) => {
+    if (options.json) { console.log(JSON.stringify(COLOR_SYSTEMS, null, 2)); return; }
+    const families: Record<string, typeof COLOR_SYSTEMS> = {};
+    for (const cs of COLOR_SYSTEMS) {
+      const fam = cs.nameCN.split(" ")[0];
+      (families[fam] ??= []).push(cs);
+    }
+    for (const [fam, systems] of Object.entries(families)) {
+      console.log(chalk.bold(`\n${fam}`));
+      for (const cs of systems) {
+        console.log(`  ${chalk.cyan(cs.id.padEnd(24))} ${chalk.white(cs.nameCN.split(" ").slice(1).join(" "))}  ${chalk.dim(cs.palette.accent)}`);
+      }
+    }
+    console.log();
+  });
+
+// ── mermaid-presets ──
+program
+  .command("mermaid-presets")
+  .description("List Mermaid theme presets (light / dark / elegant)")
+  .option("-j, --json", "Output as JSON")
+  .action((options: Record<string, string>) => {
+    if (options.json) { console.log(JSON.stringify(MERMAID_PRESETS, null, 2)); return; }
+    for (const p of MERMAID_PRESETS) {
+      console.log(`  ${chalk.cyan(p.id.padEnd(12))} ${chalk.white(p.name)}  ${chalk.dim(p.description)}`);
+    }
+    console.log();
+  });
+
+// ── list ──
+program
+  .command("list")
+  .description("List all generated themes")
+  .option("-d, --themes-dir <dir>", "Themes directory", "themes")
+  .action((options: Record<string, string>) => {
+    const dirPath = isAbsolute(options.themesDir) ? options.themesDir : join(process.cwd(), options.themesDir);
+    if (!existsSync(dirPath)) { console.log(chalk.yellow(`No themes directory: ${dirPath}`)); return; }
+    const files = readdirSync(dirPath).filter((f) => f.endsWith(".css"));
+    if (files.length === 0) { console.log(chalk.yellow("No themes found.")); return; }
+    console.log(chalk.bold(`\nThemes in ${dirPath}/:`));
+    for (const f of files) console.log(`  ${chalk.cyan("●")} ${chalk.white(f.replace(".css", ""))}`);
+    console.log(`\n${files.length} theme(s) total.\n`);
+  });
+
+// ── validate ──
+program
+  .command("validate")
+  .description("Validate a theme CSS against v3.0 paradigm rules")
+  .argument("<file>", "Path to theme CSS file")
+  .action((file: string) => {
+    if (!existsSync(file)) { console.error(chalk.red(`File not found: ${file}`)); process.exit(1); }
+    const css = readFileSync(file, "utf-8");
+    const extract = (name: string) => {
+      const m = css.match(new RegExp(`${name}:\\s*([^;]+);`));
+      return m ? m[1].trim() : "";
+    };
+    const seed = {
+      accent: extract("--seed-accent"), accentLight: extract("--seed-accent-light"),
+      accentDark: extract("--seed-accent-dark"), surface: extract("--seed-surface"),
+      panel: extract("--seed-panel"), panelAlt: extract("--seed-panel-alt"),
+      ink: extract("--seed-ink"), inkMuted: extract("--seed-ink-muted"),
+      inkDim: extract("--seed-ink-dim"), border: extract("--seed-border"),
+      borderStrong: extract("--seed-border-strong"),
+    };
+    if (!seed.accent) { console.error(chalk.yellow("Not a v3.0 paradigm theme (no seed palette found).")); process.exit(0); }
+    console.log(chalk.bold("Seed palette:"));
+    for (const [k, v] of Object.entries(seed)) console.log(`  ${chalk.dim(k.padEnd(18))} ${v}`);
+    const issues = validateSeedPalette(seed);
+    console.log(chalk.bold(`\nParadigm validation (${issues.length} issues):`));
+    console.log(summarizeIssues(issues));
+    if (issues.filter((i) => i.level === "MUST" || i.level === "MUST_NOT").length > 0) process.exit(1);
+  });
+
+// ── Export commands (set-theme, export-html, export-pdf, export) ──
+registerExportCommands(program);
+
+// ── Summary ──
+
+function printSummary(style: ThemeStyle): void {
+  const s = style.seed;
+  console.log(chalk.dim("\n  Seed palette:"));
+  console.log(`  ${chalk.white("surface:")} ${s.surface}  ${chalk.white("ink:")} ${s.ink}  ${chalk.white("accent:")} ${s.accent}`);
+  console.log(`  ${chalk.white("panel:")} ${s.panel}  ${chalk.white("panel-alt:")} ${s.panelAlt}`);
+  if (style.colorSystemId) {
+    console.log(chalk.dim(`  Color system: ${style.colorSystemId}  Mermaid: ${style.mermaidPresetId}`));
+  }
+}
+
+export function main(): void { program.parse(); }
+main();