@zzclub/pipeline 0.13.2 → 0.16.0

package/src/wechat-preview/plugins/index.test.ts

@@ -0,0 +1,313 @@
+import { describe, expect, test } from "bun:test";
+import {
+  getAllPlugins,
+  getPluginDocs,
+  getCombinedMilkdownPlugins,
+  getCombinedDefaultCss,
+  getCombinedWechatRenderers,
+  registerPlugin,
+} from "./registry";
+import { remarkCallout } from "./builtin-callout";
+import { remarkKbd } from "./builtin-kbd";
+import { remarkBadge } from "./builtin-badge";
+
+
+describe("wechat-preview plugins system", () => {
+  test("loads all built-in plugins and documentation metadata", () => {
+    const plugins = getAllPlugins();
+    const ids = plugins.map((p) => p.doc.id);
+    expect(ids).toContain("highlight");
+    expect(ids).toContain("callout");
+    expect(ids).toContain("kbd");
+    expect(ids).toContain("badge");
+
+    const docs = getPluginDocs();
+    expect(docs.length).toBeGreaterThanOrEqual(4);
+    for (const doc of docs) {
+      expect(doc.id).toBeDefined();
+      expect(doc.name).toBeDefined();
+      expect(doc.category).toBeDefined();
+      expect(doc.sampleMarkdown).toBeDefined();
+      expect(doc.syntaxGuide).toBeDefined();
+    }
+  });
+
+  test("getCombinedMilkdownPlugins returns executable plugin list", () => {
+    const milkdownPlugins = getCombinedMilkdownPlugins();
+    expect(Array.isArray(milkdownPlugins)).toBe(true);
+    expect(milkdownPlugins.length).toBeGreaterThan(0);
+  });
+
+  test("getCombinedDefaultCss contains rules for all builtins", () => {
+    const css = getCombinedDefaultCss();
+    expect(css).toContain(".milkdown .editor mark");
+    expect(css).toContain(".wechat-callout");
+    expect(css).toContain(".wechat-kbd");
+    expect(css).toContain(".wechat-badge");
+  });
+
+  test("remarkCallout parses GFM alerts into callout nodes", () => {
+    const tree = {
+      type: "root",
+      children: [
+        {
+          type: "blockquote",
+          children: [
+            {
+              type: "paragraph",
+              children: [
+                {
+                  type: "text",
+                  value: "[!NOTE]\n这是一个测试提示",
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const transform = remarkCallout();
+    transform(tree);
+
+    const callout = tree.children[0] as any;
+    expect(callout.type).toBe("callout");
+    expect(callout.calloutType).toBe("note");
+    expect(callout.customTitle).toBe("");
+    expect(callout.children[0].children[0].value).toBe("这是一个测试提示");
+  });
+
+  test("remarkCallout parses GFM alerts with inline custom title and emoji", () => {
+    const tree = {
+      type: "root",
+      children: [
+        {
+          type: "blockquote",
+          children: [
+            {
+              type: "paragraph",
+              children: [
+                {
+                  type: "text",
+                  value: "[!TIP] 实用技巧\n这是一个技巧说明",
+                },
+              ],
+            },
+          ],
+        },
+        {
+          type: "blockquote",
+          children: [
+            {
+              type: "paragraph",
+              children: [
+                {
+                  type: "text",
+                  value: "[!WARNING] ⚠️ 重点防护\n这是一个警告说明",
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const transform = remarkCallout();
+    transform(tree);
+
+    const tipCallout = tree.children[0] as any;
+    expect(tipCallout.type).toBe("callout");
+    expect(tipCallout.calloutType).toBe("tip");
+    expect(tipCallout.customTitle).toBe("实用技巧");
+    expect(tipCallout.children[0].children[0].value).toBe("这是一个技巧说明");
+
+    const warnCallout = tree.children[1] as any;
+    expect(warnCallout.type).toBe("callout");
+    expect(warnCallout.calloutType).toBe("warning");
+    expect(warnCallout.customTitle).toBe("⚠️ 重点防护");
+    expect(warnCallout.children[0].children[0].value).toBe("这是一个警告说明");
+  });
+
+  test("remarkKbd parses [[kbd:Key]] into kbd nodes", () => {
+    const tree = {
+      type: "root",
+      children: [
+        {
+          type: "paragraph",
+          children: [
+            {
+              type: "text",
+              value: "按下 [[kbd:Cmd]] + [[kbd:C]] 复制",
+            },
+          ],
+        },
+      ],
+    };
+
+    const transform = remarkKbd();
+    transform(tree);
+
+    const paragraph = tree.children[0] as any;
+    expect(paragraph.children.length).toBe(5);
+    expect(paragraph.children[0].value).toBe("按下 ");
+    expect(paragraph.children[1].type).toBe("kbd");
+    expect(paragraph.children[1].children[0].value).toBe("Cmd");
+    expect(paragraph.children[2].value).toBe(" + ");
+    expect(paragraph.children[3].type).toBe("kbd");
+    expect(paragraph.children[3].children[0].value).toBe("C");
+    expect(paragraph.children[4].value).toBe(" 复制");
+  });
+
+  test("remarkBadge parses [badge:type|text] into badge nodes", () => {
+    const tree = {
+      type: "root",
+      children: [
+        {
+          type: "paragraph",
+          children: [
+            {
+              type: "text",
+              value: "状态：[badge:success|已上线]",
+            },
+          ],
+        },
+      ],
+    };
+
+    const transform = remarkBadge();
+    transform(tree);
+
+    const paragraph = tree.children[0] as any;
+    expect(paragraph.children.length).toBe(2);
+    expect(paragraph.children[0].value).toBe("状态：");
+    expect(paragraph.children[1].type).toBe("badge");
+    expect(paragraph.children[1].badgeType).toBe("success");
+    expect(paragraph.children[1].children[0].value).toBe("已上线");
+  });
+
+  test("calloutWechatRenderer prepares icon and title", () => {
+    const renderers = getCombinedWechatRenderers();
+    const callout = renderers.find((r) => r.kind === "callout");
+    expect(callout).toBeDefined();
+
+    // Mock document and element
+    const mockCreated: any[] = [];
+    const mockDocument: any = {
+      createElement: (tag: string) => {
+        const el = {
+          tagName: tag,
+          className: "",
+          attributes: {} as Record<string, string>,
+          children: [] as any[],
+          setAttribute: (name: string, val: string) => { el.attributes[name] = val; },
+          appendChild: (c: any) => { el.children.push(c); },
+          prepend: (c: any) => { el.children.unshift(c); },
+        };
+        mockCreated.push(el);
+        return el;
+      },
+    };
+
+    const element: any = {
+      attributes: { "data-callout-type": "tip" },
+      children: [],
+      getAttribute: (name: string) => element.attributes[name],
+      prepend: (c: any) => { element.children.unshift(c); },
+    };
+
+    const context: any = {
+      document: mockDocument,
+    };
+
+    callout?.prepare?.(element, context);
+    expect(element.children.length).toBe(1);
+    const header = element.children[0];
+    expect(header.attributes["data-wechat-node"]).toBe("callout-header");
+    expect(header.children[0].textContent).toBe("✨");
+    expect(header.children[1].textContent).toBe("建议");
+  });
+
+  test("calloutWechatRenderer handles custom title text and emoji", () => {
+    const renderers = getCombinedWechatRenderers();
+    const callout = renderers.find((r) => r.kind === "callout");
+
+    const mockDocument: any = {
+      createElement: (tag: string) => {
+        const el = {
+          tagName: tag,
+          className: "",
+          attributes: {} as Record<string, string>,
+          children: [] as any[],
+          setAttribute: (name: string, val: string) => { el.attributes[name] = val; },
+          appendChild: (c: any) => { el.children.push(c); },
+          prepend: (c: any) => { el.children.unshift(c); },
+        };
+        return el;
+      },
+    };
+
+    // Case 1: Custom title text without emoji (retains default emoji)
+    const el1: any = {
+      attributes: { "data-callout-type": "note", "data-callout-title": "核心注意项" },
+      children: [],
+      getAttribute: (name: string) => el1.attributes[name],
+      prepend: (c: any) => { el1.children.unshift(c); },
+    };
+    callout?.prepare?.(el1, { document: mockDocument } as any);
+    const header1 = el1.children[0];
+    expect(header1.children[0].textContent).toBe("💡");
+    expect(header1.children[1].textContent).toBe("核心注意项");
+
+    // Case 2: Custom title with leading emoji
+    const el2: any = {
+      attributes: { "data-callout-type": "tip", "data-callout-title": "🚀 快速上手" },
+      children: [],
+      getAttribute: (name: string) => el2.attributes[name],
+      prepend: (c: any) => { el2.children.unshift(c); },
+    };
+    callout?.prepare?.(el2, { document: mockDocument } as any);
+    const header2 = el2.children[0];
+    expect(header2.children[0].textContent).toBe("🚀");
+    expect(header2.children[1].textContent).toBe("快速上手");
+
+    // Case 3: Structure level preset override
+    const el3: any = {
+      attributes: { "data-callout-type": "warning" },
+      children: [],
+      getAttribute: (name: string) => el3.attributes[name],
+      prepend: (c: any) => { el3.children.unshift(c); },
+    };
+    callout?.prepare?.(el3, {
+      document: mockDocument,
+      structure: {
+        calloutPresets: {
+          warning: { title: "避坑指南", icon: "💣" },
+        },
+      },
+    } as any);
+    const header3 = el3.children[0];
+    expect(header3.children[0].textContent).toBe("💣");
+    expect(header3.children[1].textContent).toBe("避坑指南");
+  });
+
+  test("allows registering custom plugins", () => {
+    registerPlugin({
+      doc: {
+        id: "test-plugin",
+        name: "测试插件",
+        category: "component",
+        description: "自定义插件测试",
+        sampleMarkdown: ":::test\n自定义组件\n:::",
+        syntaxGuide: ":::test",
+      },
+      milkdownPlugins: [],
+      defaultCss: ".test-plugin { color: red; }",
+    });
+
+    const docs = getPluginDocs();
+    const found = docs.find((d) => d.id === "test-plugin");
+    expect(found).toBeDefined();
+    expect(found?.name).toBe("测试插件");
+    expect(getCombinedDefaultCss()).toContain(".test-plugin { color: red; }");
+  });
+});

package/src/wechat-preview/plugins/index.ts

@@ -0,0 +1,6 @@
+export * from "./types";
+export * from "./registry";
+export * from "./builtin-highlight";
+export * from "./builtin-callout";
+export * from "./builtin-kbd";
+export * from "./builtin-badge";

package/src/wechat-preview/plugins/registry.ts

@@ -0,0 +1,62 @@
+import type { MilkdownPlugin } from "@milkdown/kit/ctx";
+import type { WechatElementRenderer } from "../wechat-renderer";
+import type { WechatMarkdownPlugin, WechatPluginDoc } from "./types";
+import { builtinHighlightPlugin } from "./builtin-highlight";
+import { builtinCalloutPlugin } from "./builtin-callout";
+import { builtinKbdPlugin } from "./builtin-kbd";
+import { builtinBadgePlugin } from "./builtin-badge";
+
+const BUILTIN_PLUGINS: WechatMarkdownPlugin[] = [
+  builtinHighlightPlugin,
+  builtinCalloutPlugin,
+  builtinKbdPlugin,
+  builtinBadgePlugin,
+];
+
+const customPlugins: WechatMarkdownPlugin[] = [];
+
+export function registerPlugin(plugin: WechatMarkdownPlugin): void {
+  // Avoid duplicate plugin IDs
+  const existingIndex = customPlugins.findIndex((p) => p.doc.id === plugin.doc.id);
+  if (existingIndex >= 0) {
+    customPlugins[existingIndex] = plugin;
+  } else {
+    customPlugins.push(plugin);
+  }
+}
+
+export function getAllPlugins(): WechatMarkdownPlugin[] {
+  return [...BUILTIN_PLUGINS, ...customPlugins];
+}
+
+export function getPluginDocs(): WechatPluginDoc[] {
+  return getAllPlugins().map((p) => p.doc);
+}
+
+export function getCombinedMilkdownPlugins(): MilkdownPlugin[] {
+  const plugins: MilkdownPlugin[] = [];
+  for (const plugin of getAllPlugins()) {
+    plugins.push(...plugin.milkdownPlugins);
+  }
+  return plugins;
+}
+
+export function getCombinedWechatRenderers(): WechatElementRenderer[] {
+  const renderers: WechatElementRenderer[] = [];
+  for (const plugin of getAllPlugins()) {
+    if (plugin.wechatRenderer) {
+      renderers.push(plugin.wechatRenderer);
+    }
+  }
+  return renderers;
+}
+
+export function getCombinedDefaultCss(): string {
+  const cssBlocks: string[] = [];
+  for (const plugin of getAllPlugins()) {
+    if (plugin.defaultCss) {
+      cssBlocks.push(plugin.defaultCss);
+    }
+  }
+  return cssBlocks.join("\n\n");
+}

package/src/wechat-preview/plugins/types.ts

@@ -0,0 +1,31 @@
+import type { MilkdownPlugin } from "@milkdown/kit/ctx";
+import type { WechatElementRenderer } from "../wechat-renderer";
+
+export type WechatPluginCategory = "inline" | "block" | "container" | "component";
+
+export interface WechatPluginDoc {
+  /** 插件唯一 ID，如 "callout"、"highlight"、"kbd"、"badge" */
+  id: string;
+  /** 展示名称，如 "提示卡片 (Callout)" */
+  name: string;
+  /** 插件分类 */
+  category: WechatPluginCategory;
+  /** 简明说明 */
+  description: string;
+  /** 语法示例，点击展台可直接插入当前光标处 */
+  sampleMarkdown: string;
+  /** 语法规则速查说明 */
+  syntaxGuide: string;
+  /** 支持的可调节 CSS 类名或选择器，如 [data-callout-type="warning"] */
+  cssSelectors?: string[];
+}
+
+export interface WechatMarkdownPlugin {
+  doc: WechatPluginDoc;
+  /** 注入到 Milkdown 的插件集合（包含 Remark 解析器、ProseMirror Schema 等） */
+  milkdownPlugins: MilkdownPlugin[];
+  /** 注入到微信 HTML 生成链路的渲染器扩展（负责结构预处理、标签替换、微信兼容） */
+  wechatRenderer?: WechatElementRenderer;
+  /** 插件内置的微信/排版默认样式 */
+  defaultCss?: string;
+}

package/src/wechat-preview/server/http.ts

@@ -1,3 +1,5 @@
+import { existsSync, readFileSync, writeFileSync } from "fs";
+import { dirname, join } from "path";
 import {
   previewBaseUrl,
   resolvePreviewHost,
@@ -24,6 +26,10 @@ import {
 } from "./local-file";
 import { renderDashboardHtml, renderFailedEntryHtml } from "./ui";
 import { buildWechatPreviewShell } from "../index";
+import { getPluginDocs } from "../plugins/registry";
+import { getWechatPreviewTheme } from "../themes";
+import { loadConfig, saveConfig, getPipelineConfigPath, resolveConfigRelativePath } from "../../config";
+import { DIST_DIR, WECHAT_PREVIEW_DIR } from "../../runtime-paths";
 import type { PreviewRegisterInput } from "./types";
 
 export interface StartPreviewServerOptions {
@@ -87,14 +93,14 @@ export async function startPreviewServer(
     clearServerLock();
   }
 
-  const baseUrl = previewBaseUrl(host, port);
-
-  const server = Bun.serve({
+  let server: ReturnType<typeof Bun.serve>;
+  server = Bun.serve({
     hostname: host,
     port,
     async fetch(req) {
       const url = new URL(req.url);
       const { pathname } = url;
+      const baseUrl = previewBaseUrl(host, server?.port ?? port);
 
       if (pathname === "/api/health") {
         return json({ ok: true, service: "wechat-preview", url: baseUrl, pid: process.pid });
@@ -180,6 +186,157 @@ export async function startPreviewServer(
         }
       }
 
+      if (pathname === "/api/studio/config" && req.method === "GET") {
+        const config = loadConfig();
+        const configPath = getPipelineConfigPath();
+        const accountsData: Record<string, unknown> = {};
+
+        for (const [key, account] of Object.entries(config.wx.accounts)) {
+          let customCssContent = "";
+          if (account.customCss) {
+            const resolved = resolveConfigRelativePath(account.customCss, configPath);
+            if (resolved && existsSync(resolved)) {
+              try {
+                customCssContent = readFileSync(resolved, "utf-8");
+              } catch {
+                // ignore
+              }
+            }
+          }
+
+          const defaultTheme = getWechatPreviewTheme(key);
+
+          accountsData[key] = {
+            name: account.name || key,
+            customCssPath: account.customCss,
+            customCssContent,
+            theme: {
+              editorVars: { ...defaultTheme.editorVars, ...account.theme?.editorVars },
+              exportTheme: { ...defaultTheme.exportTheme, ...account.theme?.exportTheme },
+              syntaxPresets: account.theme?.syntaxPresets || {},
+              structure: account.theme?.structure || {},
+            },
+            articleTheme: account.articleTheme ?? null,
+          };
+        }
+
+        let sampleMarkdown = "";
+        const fixturePath = join(WECHAT_PREVIEW_DIR, "fixtures/all-nodes.md");
+        if (existsSync(fixturePath)) {
+          try {
+            sampleMarkdown = readFileSync(fixturePath, "utf-8");
+          } catch {
+            // ignore
+          }
+        }
+
+        return json({
+          defaultAccount: config.wx.defaultAccount || "default",
+          accounts: accountsData,
+          plugins: getPluginDocs(),
+          sampleMarkdown,
+        });
+      }
+
+      if (pathname === "/api/studio/save-config" && req.method === "POST") {
+        let body: any;
+        try {
+          body = await req.json();
+        } catch {
+          return json({ error: "invalid JSON body" }, 400);
+        }
+
+        const config = loadConfig();
+        const accountKey = String(body.account || config.wx.defaultAccount || "default");
+        if (!config.wx.accounts[accountKey]) {
+          config.wx.accounts[accountKey] = {
+            name: accountKey,
+            pat: "",
+            appId: "",
+            appSecret: "",
+            customCss: null,
+            theme: {
+              editorVars: {},
+              exportTheme: {},
+              syntaxPresets: {},
+            },
+          };
+        }
+
+        const account = config.wx.accounts[accountKey];
+        if (body.editorVars && typeof body.editorVars === "object") {
+          account.theme.editorVars = { ...account.theme.editorVars, ...body.editorVars };
+        }
+        if (body.exportTheme && typeof body.exportTheme === "object") {
+          account.theme.exportTheme = { ...account.theme.exportTheme, ...body.exportTheme };
+        }
+        if (body.syntaxPresets && typeof body.syntaxPresets === "object") {
+          account.theme.syntaxPresets = { ...account.theme.syntaxPresets, ...body.syntaxPresets };
+        }
+        if (body.structure && typeof body.structure === "object") {
+          account.theme.structure = { ...account.theme.structure, ...body.structure };
+        }
+
+        if (typeof body.customCss === "string") {
+          const configPath = getPipelineConfigPath();
+          let cssPath = account.customCss
+            ? resolveConfigRelativePath(account.customCss, configPath)
+            : null;
+
+          if (!cssPath) {
+            cssPath = join(dirname(configPath), `custom-css-${accountKey}.css`);
+            account.customCss = `custom-css-${accountKey}.css`;
+          }
+
+          try {
+            writeFileSync(cssPath, body.customCss, "utf-8");
+          } catch (err) {
+            return json({ error: `Failed to write custom CSS: ${String(err)}` }, 500);
+          }
+        }
+
+        try {
+          saveConfig(config);
+          return json({ ok: true, account: accountKey, message: "Configuration saved successfully" });
+        } catch (err) {
+          return json({ error: `Failed to save config: ${String(err)}` }, 500);
+        }
+      }
+
+      if (pathname === "/studio" || pathname === "/studio/" || pathname === "/studio/index.html") {
+        const studioHtmlPath = join(DIST_DIR, "src/wechat-preview/browser/studio/studio.html");
+        const fallbackPath = join(DIST_DIR, "studio.html");
+        const targetHtmlPath = existsSync(studioHtmlPath) ? studioHtmlPath : fallbackPath;
+        if (existsSync(targetHtmlPath)) {
+          return html(readFileSync(targetHtmlPath, "utf-8"));
+        }
+        return html("<h1>Studio not built. Run bun run build:wechat-preview first.</h1>", 500);
+      }
+
+      if (pathname === "/studio.js" || pathname === "/editor-export.js") {
+        const filePath = join(DIST_DIR, pathname.slice(1));
+        if (existsSync(filePath)) {
+          return new Response(readFileSync(filePath), {
+            headers: {
+              "content-type": "application/javascript; charset=utf-8",
+              "cache-control": "no-cache",
+            },
+          });
+        }
+      }
+
+      if (pathname.startsWith("/assets/")) {
+        const filePath = join(DIST_DIR, pathname.slice(1));
+        if (existsSync(filePath)) {
+          return new Response(readFileSync(filePath), {
+            headers: {
+              "content-type": guessContentType(filePath),
+              "cache-control": "public, max-age=3600",
+            },
+          });
+        }
+      }
+
       if (pathname === "/" || pathname === "/index.html") {
         return html(renderDashboardHtml(baseUrl));
       }

package/src/wechat-preview/server/paths.ts

@@ -57,13 +57,13 @@ export function ensurePreviewServerDirs(): void {
 }
 
 export function resolvePreviewPort(port?: number): number {
-  if (typeof port === "number" && Number.isFinite(port) && port > 0) {
+  if (typeof port === "number" && Number.isFinite(port) && port >= 0) {
     return Math.floor(port);
   }
   const env = process.env.ZZHUB_WECHAT_PREVIEW_PORT?.trim();
   if (env) {
     const n = Number(env);
-    if (Number.isFinite(n) && n > 0) return Math.floor(n);
+    if (Number.isFinite(n) && n >= 0) return Math.floor(n);
   }
   return DEFAULT_PREVIEW_PORT;
 }

package/src/wechat-preview/server/singleton.ts

@@ -86,18 +86,20 @@ export async function findExistingServer(
   }
 
   // Probe default/requested address without lock
-  const url = previewBaseUrl(host, port);
-  if (await probeHealth(url)) {
-    return {
-      kind: "running",
-      lock: {
-        pid: lock?.pid ?? 0,
-        host,
-        port,
-        url,
-        started_at: lock?.started_at ?? new Date().toISOString(),
-      },
-    };
+  if (port > 0) {
+    const url = previewBaseUrl(host, port);
+    if (await probeHealth(url)) {
+      return {
+        kind: "running",
+        lock: {
+          pid: lock?.pid ?? 0,
+          host,
+          port,
+          url,
+          started_at: lock?.started_at ?? new Date().toISOString(),
+        },
+      };
+    }
   }
 
   if (lock && !isProcessAlive(lock.pid)) {