@zzclub/pipeline 0.2.0 → 0.4.0

package/src/adapter-loader.ts

@@ -0,0 +1,138 @@
+/**
+ * Adapter loader — resolves and validates rendering plugins.
+ *
+ * Priority:
+ * 1. User-provided plugin (via config.plugins, loaded via dynamic import)
+ * 2. Built-in adapter (builtin-imgx / builtin-wechat-preview)
+ */
+
+import type { PipelineConfig } from "./schema/config";
+import type {
+  ImageRenderPlugin,
+  MarkdownRenderPlugin,
+  PipelinePluginDoctorCheck,
+} from "./adapter-types";
+import { builtinImageRenderer } from "./adapters/builtin-image-renderer";
+import { builtinMarkdownRenderer } from "./adapters/builtin-markdown-renderer";
+
+// ── Validation ───────────────────────────────────────────────────
+
+function validateImageRenderPlugin(plugin: unknown, specifier: string): ImageRenderPlugin {
+  if (!plugin || typeof plugin !== "object") {
+    throw new Error(`image renderer plugin "${specifier}" must export an object`);
+  }
+  const p = plugin as Record<string, unknown>;
+  if (typeof p.name !== "string" || !p.name) {
+    throw new Error(`image renderer plugin "${specifier}" must have a string "name" property`);
+  }
+  if (typeof p.render !== "function") {
+    throw new Error(`image renderer plugin "${specifier}" must have a "render" function`);
+  }
+  return plugin as ImageRenderPlugin;
+}
+
+function validateMarkdownRenderPlugin(plugin: unknown, specifier: string): MarkdownRenderPlugin {
+  if (!plugin || typeof plugin !== "object") {
+    throw new Error(`markdown renderer plugin "${specifier}" must export an object`);
+  }
+  const p = plugin as Record<string, unknown>;
+  if (typeof p.name !== "string" || !p.name) {
+    throw new Error(`markdown renderer plugin "${specifier}" must have a string "name" property`);
+  }
+  if (typeof p.render !== "function") {
+    throw new Error(`markdown renderer plugin "${specifier}" must have a "render" function`);
+  }
+  return plugin as MarkdownRenderPlugin;
+}
+
+// ── Dynamic import ───────────────────────────────────────────────
+
+async function importPlugin(specifier: string): Promise<unknown> {
+  try {
+    const mod = await import(specifier);
+    // Support both default exports and named `plugin` exports
+    return mod.default ?? mod.plugin ?? mod;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`failed to load plugin "${specifier}": ${message}`);
+  }
+}
+
+// ── Public API ───────────────────────────────────────────────────
+
+/**
+ * Resolve the image renderer plugin.
+ * If config.plugins.imageRenderer is set, loads it via dynamic import.
+ * Otherwise returns the built-in imgx adapter.
+ */
+export async function resolveImageRenderer(
+  config: PipelineConfig,
+): Promise<ImageRenderPlugin> {
+  const specifier = config.plugins.imageRenderer;
+
+  if (specifier && specifier.trim()) {
+    const mod = await importPlugin(specifier.trim());
+    return validateImageRenderPlugin(mod, specifier.trim());
+  }
+
+  return builtinImageRenderer;
+}
+
+/**
+ * Resolve the markdown renderer plugin.
+ * If config.plugins.markdownRenderer is set, loads it via dynamic import.
+ * Otherwise returns the built-in wechat-preview adapter.
+ */
+export async function resolveMarkdownRenderer(
+  config: PipelineConfig,
+): Promise<MarkdownRenderPlugin> {
+  const specifier = config.plugins.markdownRenderer;
+
+  if (specifier && specifier.trim()) {
+    const mod = await importPlugin(specifier.trim());
+    return validateMarkdownRenderPlugin(mod, specifier.trim());
+  }
+
+  return builtinMarkdownRenderer;
+}
+
+/**
+ * Run doctor checks on resolved plugins.
+ */
+export async function runPluginDoctorChecks(
+  config: PipelineConfig,
+): Promise<PipelinePluginDoctorCheck[]> {
+  const checks: PipelinePluginDoctorCheck[] = [];
+
+  try {
+    const imageRenderer = await resolveImageRenderer(config);
+    if (imageRenderer.doctor) {
+      checks.push(...(await imageRenderer.doctor()));
+    } else {
+      checks.push({ name: imageRenderer.name, ok: true, message: "no doctor check defined" });
+    }
+  } catch (err) {
+    checks.push({
+      name: "image-renderer",
+      ok: false,
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  try {
+    const markdownRenderer = await resolveMarkdownRenderer(config);
+    if (markdownRenderer.doctor) {
+      checks.push(...(await markdownRenderer.doctor()));
+    } else {
+      checks.push({ name: markdownRenderer.name, ok: true, message: "no doctor check defined" });
+    }
+  } catch (err) {
+    checks.push({
+      name: "markdown-renderer",
+      ok: false,
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+
+  return checks;
+}

package/src/adapter-types.ts

@@ -0,0 +1,172 @@
+/**
+ * Adapter interfaces for pluggable rendering.
+ *
+ * These define the contract between the zzp core pipeline and the
+ * rendering subsystems (image rendering and markdown rendering).
+ *
+ * Built-in adapters wrap the existing imgx and wechat-preview modules.
+ * User-provided adapters can replace them via config.plugins.
+ */
+
+import type { RenderAsset, RoutePrimary, WorkflowState } from "./state";
+
+// ── Doctor check ──────────────────────────────────────────────────
+
+export interface PipelinePluginDoctorCheck {
+  name: string;
+  ok: boolean;
+  message?: string;
+  detail?: unknown;
+}
+
+// ── Image renderer adapter ────────────────────────────────────────
+
+/**
+ * Input for image rendering. Maps to the parameters currently passed
+ * to runRenderArticleCli and runRenderCardCli via CLI argv.
+ */
+export interface ImageRenderInput {
+  /** Workflow state providing context (route, metadata, etc.) */
+  state: WorkflowState;
+
+  /** Markdown body text to render */
+  bodyText: string;
+
+  /** Output directory for rendered images */
+  outputDir: string;
+
+  /** Page title */
+  title: string;
+
+  /** Route determines template selection */
+  route: RoutePrimary;
+
+  /**
+   * Optional explicit page specifications.
+   * For wechat-newspic: page markers, image layouts, fill ratios.
+   * For wechat-article: typically empty (auto-pagination).
+   */
+  pageSpecs?: Array<{
+    page: number;
+    imageMarkers?: string[];
+    imageLayout?: string | null;
+    targetFillRatio?: number | null;
+    note?: string | null;
+  }>;
+
+  /** Body images to embed in rendered pages */
+  bodyImages?: Array<{
+    marker: string;
+    path: string;
+  }>;
+
+  /** Minimum number of pages (for longform) */
+  minPages?: number;
+
+  /** Maximum number of pages (0 = no limit) */
+  maxPages?: number;
+
+  /** Account-specific visual params (footer text, colors, icon) */
+  accountVisualParams?: {
+    footer?: string;
+    bg?: string;
+    highlight?: string;
+    fallbackIcon?: string;
+  };
+
+  /** Theme name override */
+  theme?: string;
+
+  /** Template name override */
+  template?: string;
+}
+
+/**
+ * Output from image rendering.
+ */
+export interface ImageRenderOutput {
+  /** Rendered assets (cover image + page images) */
+  assets: RenderAsset[];
+
+  /** Number of pages rendered */
+  pageCount: number;
+
+  /** Per-page summary */
+  pages: Array<{
+    page: number;
+    imageCount: number;
+    imageSources: string[];
+  }>;
+}
+
+export interface ImageRenderPlugin {
+  name: string;
+  version?: string;
+
+  /** Environment checks (e.g., Chrome availability) */
+  doctor?: () => Promise<PipelinePluginDoctorCheck[]>;
+
+  /** Render images from markdown body */
+  render: (input: ImageRenderInput) => Promise<ImageRenderOutput>;
+}
+
+// ── Markdown renderer adapter ─────────────────────────────────────
+
+/**
+ * Input for markdown-to-HTML rendering.
+ * Maps to ExportMarkdownToWechatHtmlInput from wechat-preview.
+ */
+export interface MarkdownRenderInput {
+  /** Path to the markdown source file */
+  markdownPath: string;
+
+  /** Output path for the rendered HTML */
+  outPath: string;
+
+  /** WeChat account name (for theme/style selection) */
+  account: string;
+
+  /** Article title */
+  title?: string;
+
+  /** Optional path for preview shell HTML output */
+  previewShellOutPath?: string;
+
+  /** Path to custom CSS file for style overrides */
+  customCss?: string | null;
+
+  /** Workflow state for context */
+  state?: WorkflowState;
+}
+
+/**
+ * Output from markdown rendering.
+ * Maps to ExportMarkdownToWechatHtmlResult from wechat-preview.
+ */
+export interface MarkdownRenderOutput {
+  /** Rendered HTML content */
+  html: string;
+
+  /** Path to the written HTML file */
+  htmlPath: string;
+
+  /** Account used for rendering */
+  account: string;
+
+  /** CSS style used for preview */
+  previewStyle: string;
+
+  /** Path to preview shell HTML (if generated) */
+  previewShellPath?: string;
+}
+
+export interface MarkdownRenderPlugin {
+  name: string;
+  version?: string;
+
+  /** Environment checks */
+  doctor?: () => Promise<PipelinePluginDoctorCheck[]>;
+
+  /** Render markdown to WeChat-compatible HTML */
+  render: (input: MarkdownRenderInput) => Promise<MarkdownRenderOutput>;
+}

package/src/adapters/builtin-image-renderer.ts

@@ -0,0 +1,353 @@
+/**
+ * Built-in image renderer adapter — wraps imgx (runRenderCardCli + runRenderArticleCli).
+ *
+ * Implements ImageRenderPlugin interface. This is the default adapter used
+ * when no user-provided plugin is configured.
+ */
+
+import { mkdir, readdir, rm, rmdir, writeFile } from "fs/promises";
+import { join } from "path";
+
+import { runRenderArticleCli, runRenderCardCli } from "../imgx";
+import type { RenderArticleResult } from "../imgx";
+import {
+  removeIllustrationMarkers,
+  removePageMarkers,
+  compressBlankLines,
+  generateCoverTitle,
+} from "../text";
+import { getLongformTheme } from "../routes";
+import { resolveWorkspacePaths } from "../config";
+import type {
+  ImageRenderPlugin,
+  ImageRenderInput,
+  ImageRenderOutput,
+  PipelinePluginDoctorCheck,
+} from "../adapter-types";
+import type {
+  NewspicRenderSpec,
+  RenderAsset,
+  AccountVisualParams,
+} from "../state";
+
+// ── Helpers ──────────────────────────────────────────────────────
+
+function appendPosterVisualArgs(
+  cmdParts: string[],
+  visualParams: AccountVisualParams | null,
+  highlightWords: string[],
+): void {
+  if (visualParams) {
+    cmdParts.push("--highlight", visualParams.highlight);
+    cmdParts.push("--bg", visualParams.bg);
+    cmdParts.push("--footer", visualParams.footer);
+    cmdParts.push("--fallback-icon", visualParams.fallback_icon);
+  }
+  cmdParts.push("--highlight-words", highlightWords.join(","));
+}
+
+type ResolvedPageImageSpecFile = {
+  default_image_layout: string;
+  target_fill_ratio: number;
+  page_specs: Array<{
+    page: number;
+    image_layout?: string;
+    target_fill_ratio?: number;
+    images: Array<{ src: string; alt: string; caption: string }>;
+  }>;
+};
+
+function buildExplicitPageImageSpec(
+  spec: NewspicRenderSpec,
+  received: Array<{ marker: string; path: string }>,
+): ResolvedPageImageSpecFile | null {
+  if (!spec.page_specs || spec.page_specs.length === 0) {
+    return null;
+  }
+
+  const receivedMap = new Map(received.map((item) => [item.marker, item.path]));
+  const pageSpecs = spec.page_specs.map((pageSpec) => {
+    const images = pageSpec.image_markers
+      .map((marker) => {
+        const path = receivedMap.get(marker);
+        if (!path) return null;
+        return { src: path, alt: marker, caption: "" };
+      })
+      .filter((item): item is { src: string; alt: string; caption: string } => item !== null);
+
+    return {
+      page: pageSpec.page,
+      image_layout: pageSpec.image_layout ?? spec.default_image_layout,
+      target_fill_ratio: pageSpec.target_fill_ratio ?? spec.target_fill_ratio,
+      images,
+    };
+  });
+
+  return {
+    default_image_layout: spec.default_image_layout,
+    target_fill_ratio: spec.target_fill_ratio,
+    page_specs: pageSpecs,
+  };
+}
+
+function validateNewspicRenderResult(
+  spec: NewspicRenderSpec,
+  result: { pageCount: number; pages: Array<{ page: number; imageCount: number }> },
+): string[] {
+  const errors: string[] = [];
+
+  if (result.pageCount < spec.min_pages) {
+    errors.push(
+      `newspic render produced ${result.pageCount} page(s), but at least ${spec.min_pages} page(s) were requested`,
+    );
+  }
+
+  if (spec.require_image_every_page) {
+    const missingPages = result.pages
+      .filter((page) => page.imageCount < 1)
+      .map((page) => page.page);
+    if (missingPages.length > 0) {
+      errors.push(`pages without required body images: ${missingPages.join(", ")}`);
+    }
+  }
+
+  for (const pageSpec of spec.page_specs) {
+    if (pageSpec.image_markers.length === 0) continue;
+    const page = result.pages.find((item) => item.page === pageSpec.page);
+    if (!page) {
+      errors.push(
+        `page ${pageSpec.page} was explicitly configured but render only produced ${result.pageCount} page(s)`,
+      );
+      continue;
+    }
+    if (page.imageCount < pageSpec.image_markers.length) {
+      errors.push(
+        `page ${pageSpec.page} expected ${pageSpec.image_markers.length} body image(s), but render placed ${page.imageCount}`,
+      );
+    }
+  }
+
+  return errors;
+}
+
+// ── Render helpers ───────────────────────────────────────────────
+
+async function renderCover(
+  template: string,
+  title: string,
+  outputDir: string,
+  visualParams: AccountVisualParams | null,
+  highlightWords: string[],
+): Promise<RenderAsset> {
+  const coverOut = join(outputDir, "cover.png");
+  const route = template === "wechat-cover-split" ? "wechat-article" : "wechat-newspic";
+
+  if (template === "wechat-cover-split") {
+    const cmdParts = ["--template", "wechat-cover-split", "--text", title];
+    cmdParts.push("--highlight-words", highlightWords.join(","));
+    cmdParts.push("--out", coverOut);
+    runRenderCardCli(cmdParts);
+  } else {
+    const cmdParts = ["--template", "poster-3-4", "--text", title];
+    appendPosterVisualArgs(cmdParts, visualParams, highlightWords);
+    cmdParts.push("--out", coverOut);
+    runRenderCardCli(cmdParts);
+  }
+
+  return { kind: "cover", route: route as RenderAsset["route"], path: coverOut };
+}
+
+async function renderLongformPages(
+  input: ImageRenderInput,
+  outputDir: string,
+  newspicRenderSpec: NewspicRenderSpec,
+  bodyImages: Array<{ marker: string; path: string }>,
+  vp: AccountVisualParams | null,
+): Promise<{ assets: RenderAsset[]; pageCount: number; pages: ImageRenderOutput["pages"] }> {
+  const state = input.state;
+  const cleanBody = removeIllustrationMarkers(input.bodyText);
+
+  const explicitPageImageSpec = buildExplicitPageImageSpec(newspicRenderSpec, bodyImages);
+
+  let pageBody = cleanBody;
+  if (explicitPageImageSpec === null) {
+    pageBody = removePageMarkers(pageBody);
+  }
+  pageBody = compressBlankLines(pageBody);
+
+  const workspacePaths = resolveWorkspacePaths(state.workspace_root);
+  const tempRunDir = join(workspacePaths.tempRoot, state.run_id);
+  const tempDir = join(tempRunDir, "render-longform");
+  const tempBodyPath = join(tempDir, "body.md");
+  const tempPageImageSpecPath = join(tempDir, "page-images.json");
+  const keepTempFiles = process.env.ZZHUB_PIPELINE_KEEP_TMP === "1";
+  await mkdir(tempDir, { recursive: true });
+  await writeFile(tempBodyPath, pageBody, "utf-8");
+
+  const theme = input.theme ?? getLongformTheme(state.route.account);
+  const pageParts = [
+    "--title", input.title,
+    "--text-file", tempBodyPath,
+    "--out-dir", outputDir,
+    "--theme", theme,
+  ];
+
+  if (newspicRenderSpec.min_pages > 1) {
+    pageParts.push("--min-pages", String(newspicRenderSpec.min_pages));
+  }
+  if (newspicRenderSpec.max_pages > 0) {
+    pageParts.push("--max-pages", String(newspicRenderSpec.max_pages));
+  }
+
+  if (vp?.footer) {
+    pageParts.push("--footer", vp.footer);
+  }
+
+  const highlightWords = input.state.route.highlight_words ?? [];
+  if (highlightWords.length > 0) {
+    pageParts.push("--highlight-words", highlightWords.join(","));
+  }
+
+  if (explicitPageImageSpec) {
+    await writeFile(tempPageImageSpecPath, JSON.stringify(explicitPageImageSpec, null, 2), "utf-8");
+    pageParts.push("--page-image-spec-file", tempPageImageSpecPath);
+  }
+
+  if (bodyImages.length > 0 && !explicitPageImageSpec) {
+    for (const img of bodyImages) {
+      pageParts.push("--body-image", img.path);
+    }
+    pageParts.push(
+      "--image-layout",
+      newspicRenderSpec.default_image_layout,
+    );
+  }
+
+  let result: RenderArticleResult;
+  try {
+    result = runRenderArticleCli(pageParts);
+  } finally {
+    if (!keepTempFiles) {
+      await rm(tempDir, { recursive: true, force: true });
+      await rmdir(tempRunDir).catch(() => undefined);
+    }
+  }
+
+  const errors = validateNewspicRenderResult(newspicRenderSpec, result);
+  if (errors.length > 0) {
+    throw new Error(`newspic render constraints not satisfied: ${errors.join("; ")}`);
+  }
+
+  // Discover generated page files
+  const files = await readdir(outputDir);
+  const pageFiles = files.filter((f) => /^article-\d+\.png$/.test(f)).sort();
+
+  const assets: RenderAsset[] = [];
+  for (let i = 0; i < pageFiles.length; i++) {
+    assets.push({
+      kind: "page",
+      route: "wechat-newspic",
+      index: i + 1,
+      path: join(outputDir, pageFiles[i]),
+    });
+  }
+
+  return { assets, pageCount: result.pageCount, pages: result.pages };
+}
+
+// ── Plugin implementation ────────────────────────────────────────
+
+export const builtinImageRenderer: ImageRenderPlugin = {
+  name: "builtin-imgx",
+  version: "1.0.0",
+
+  async doctor(): Promise<PipelinePluginDoctorCheck[]> {
+    const checks: PipelinePluginDoctorCheck[] = [];
+
+    // Check @napi-rs/canvas
+    try {
+      await import("@napi-rs/canvas");
+      checks.push({ name: "@napi-rs/canvas", ok: true });
+    } catch {
+      checks.push({
+        name: "@napi-rs/canvas",
+        ok: false,
+        message:
+          "@napi-rs/canvas not installed. Install it with:\n" +
+          "  npm install @napi-rs/canvas\n" +
+          "  # or: bun add @napi-rs/canvas\n" +
+          "This is required for image rendering (poster, longform, cover).",
+      });
+    }
+
+    return checks;
+  },
+
+  async render(input: ImageRenderInput): Promise<ImageRenderOutput> {
+    const { state, outputDir, title, route } = input;
+    const highlightWords = state.route.highlight_words ?? [];
+
+    // Normalize visual params: adapter input uses camelCase, state uses snake_case
+    const adapterVp = input.accountVisualParams;
+    const stateVp = state.route.account_visual_params;
+    const vp: AccountVisualParams | null = adapterVp
+      ? {
+          footer: adapterVp.footer ?? "",
+          bg: adapterVp.bg ?? "",
+          highlight: adapterVp.highlight ?? "",
+          fallback_icon: adapterVp.fallbackIcon ?? "",
+        }
+      : stateVp;
+
+    await mkdir(outputDir, { recursive: true });
+
+    if (route === "wechat-article") {
+      // Article: cover only (wechat-cover-split)
+      const cover = await renderCover("wechat-cover-split", title, outputDir, null, highlightWords);
+      return { assets: [cover], pageCount: 1, pages: [{ page: 1, imageCount: 0, imageSources: [] }] };
+    }
+
+    if (route === "blog") {
+      return { assets: [], pageCount: 0, pages: [] };
+    }
+
+    // wechat-newspic: determine short vs long
+    const newspicRenderSpec: NewspicRenderSpec = {
+      pagination_mode: input.pageSpecs && input.pageSpecs.length > 0 ? "multi" : "single",
+      min_pages: input.minPages ?? 1,
+      max_pages: input.maxPages ?? 0,
+      require_image_every_page: false,
+      default_image_layout: "staggered",
+      target_fill_ratio: 0.8,
+      page_specs: (input.pageSpecs ?? []).map((ps) => ({
+        page: ps.page,
+        image_markers: ps.imageMarkers ?? [],
+        image_layout: ps.imageLayout ?? null,
+        target_fill_ratio: ps.targetFillRatio ?? null,
+        note: ps.note ?? null,
+      })),
+    };
+
+    const isLong = newspicRenderSpec.pagination_mode === "multi";
+
+    if (!isLong) {
+      // Short: single poster cover
+      const coverTitle = generateCoverTitle(title);
+      const cover = await renderCover("poster-3-4", coverTitle, outputDir, vp, highlightWords);
+      return { assets: [cover], pageCount: 1, pages: [{ page: 1, imageCount: 0, imageSources: [] }] };
+    }
+
+    // Long: cover + article pages
+    const coverTitle = generateCoverTitle(title);
+    const cover = await renderCover("poster-3-4", coverTitle, outputDir, vp, highlightWords);
+
+    const bodyImages = input.bodyImages ?? [];
+    const pageResult = await renderLongformPages(input, outputDir, newspicRenderSpec, bodyImages, vp);
+
+    return {
+      assets: [cover, ...pageResult.assets],
+      pageCount: pageResult.pageCount,
+      pages: pageResult.pages,
+    };
+  },
+};