@zzclub/pipeline 0.10.0 → 0.10.2

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

@@ -0,0 +1,164 @@
+import { spawn } from "child_process";
+import { resolve } from "path";
+import { PACKAGE_ROOT } from "../../runtime-paths";
+import {
+  DEFAULT_PREVIEW_HOST,
+  DEFAULT_PREVIEW_PORT,
+  previewBaseUrl,
+  resolvePreviewHost,
+  resolvePreviewPort,
+} from "./paths";
+import { findExistingServer, probeHealth } from "./singleton";
+import type { PreviewEntryMeta, PreviewRegisterInput } from "./types";
+
+export interface RegisterPreviewResult {
+  ok: boolean;
+  preview_url?: string;
+  dashboard_url?: string;
+  id?: string;
+  error?: string;
+}
+
+export interface EnsurePreviewServerOptions {
+  host?: string;
+  port?: number;
+  autoStart?: boolean;
+  /** Max wait for auto-started server readiness. */
+  waitMs?: number;
+}
+
+/**
+ * Ensure a preview server is reachable. Optionally spawn one in the background.
+ */
+export async function ensurePreviewServer(
+  options: EnsurePreviewServerOptions = {},
+): Promise<{ url: string; started: boolean }> {
+  const host = resolvePreviewHost(options.host);
+  const port = resolvePreviewPort(options.port);
+  const existing = await findExistingServer(host, port);
+  if (existing.kind === "running") {
+    return { url: existing.lock.url, started: false };
+  }
+
+  if (!options.autoStart) {
+    throw new Error(
+      `WeChat preview server is not running at ${previewBaseUrl(host, port)}. ` +
+        `Start it with: bun run src/cli.ts wechat-preview serve`,
+    );
+  }
+
+  const args = [
+    resolve(PACKAGE_ROOT, "src/cli.ts"),
+    "wechat-preview",
+    "serve",
+    "--host",
+    host,
+    "--port",
+    String(port),
+  ];
+
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      ZZHUB_WECHAT_PREVIEW_HOST: host,
+      ZZHUB_WECHAT_PREVIEW_PORT: String(port),
+    },
+  });
+  child.unref();
+
+  const url = previewBaseUrl(host, port);
+  const deadline = Date.now() + (options.waitMs ?? 8000);
+  while (Date.now() < deadline) {
+    if (await probeHealth(url, 400)) {
+      return { url, started: true };
+    }
+    await Bun.sleep(150);
+  }
+
+  throw new Error(
+    `Timed out waiting for WeChat preview server at ${url} (spawned pid ${child.pid ?? "?"})`,
+  );
+}
+
+export async function registerPreviewEntry(
+  input: PreviewRegisterInput,
+  options: EnsurePreviewServerOptions = {},
+): Promise<RegisterPreviewResult> {
+  try {
+    const { url } = await ensurePreviewServer({
+      autoStart: options.autoStart ?? true,
+      host: options.host,
+      port: options.port,
+      waitMs: options.waitMs,
+    });
+
+    const res = await fetch(`${url.replace(/\/$/, "")}/api/entries`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(input),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      return { ok: false, error: `register failed (${res.status}): ${text}` };
+    }
+    const body = (await res.json()) as PreviewEntryMeta & {
+      preview_url?: string;
+      dashboard_url?: string;
+    };
+    return {
+      ok: true,
+      id: body.id,
+      preview_url: body.preview_url ?? `${url}/e/${body.id}`,
+      dashboard_url: body.dashboard_url ?? url,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+export async function getPreviewServerStatus(options: {
+  host?: string;
+  port?: number;
+} = {}): Promise<{
+  running: boolean;
+  url?: string;
+  host?: string;
+  port?: number;
+  entries?: number;
+}> {
+  const host = resolvePreviewHost(options.host);
+  const port = resolvePreviewPort(options.port);
+  const existing = await findExistingServer(host, port);
+  if (existing.kind !== "running") {
+    return { running: false, host, port };
+  }
+  let entries: number | undefined;
+  try {
+    const res = await fetch(`${existing.lock.url}/api/entries`);
+    if (res.ok) {
+      const list = (await res.json()) as unknown[];
+      entries = Array.isArray(list) ? list.length : undefined;
+    }
+  } catch {
+    // ignore
+  }
+  return {
+    running: true,
+    url: existing.lock.url,
+    host: existing.lock.host,
+    port: existing.lock.port,
+    entries,
+  };
+}
+
+export function defaultPreviewListen(): { host: string; port: number } {
+  return {
+    host: DEFAULT_PREVIEW_HOST,
+    port: DEFAULT_PREVIEW_PORT,
+  };
+}

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

@@ -0,0 +1,229 @@
+import {
+  previewBaseUrl,
+  resolvePreviewHost,
+  resolvePreviewPort,
+} from "./paths";
+import {
+  clearPreviewEntries,
+  createPreviewEntry,
+  getPreviewEntry,
+  listPreviewEntries,
+} from "./registry";
+import {
+  buildLock,
+  clearServerLock,
+  findExistingServer,
+  readServerLock,
+  writeServerLock,
+} from "./singleton";
+import {
+  guessContentType,
+  readLocalFile,
+  resolveLocalFilePath,
+  rewriteHtmlLocalAssets,
+} from "./local-file";
+import { renderDashboardHtml, renderFailedEntryHtml } from "./ui";
+import { buildWechatPreviewShell } from "../index";
+import type { PreviewRegisterInput } from "./types";
+
+export interface StartPreviewServerOptions {
+  host?: string;
+  port?: number;
+  open?: boolean;
+  /** If true, return early when server already running instead of throwing. */
+  reuseExisting?: boolean;
+}
+
+export interface StartPreviewServerResult {
+  url: string;
+  host: string;
+  port: number;
+  reused: boolean;
+  stop?: () => void;
+}
+
+function json(data: unknown, status = 200): Response {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+function html(body: string, status = 200): Response {
+  return new Response(body, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+export async function startPreviewServer(
+  options: StartPreviewServerOptions = {},
+): Promise<StartPreviewServerResult> {
+  const host = resolvePreviewHost(options.host);
+  const port = resolvePreviewPort(options.port);
+  const existing = await findExistingServer(host, port);
+
+  if (existing.kind === "running") {
+    if (options.reuseExisting !== false) {
+      return {
+        url: existing.lock.url,
+        host: existing.lock.host,
+        port: existing.lock.port,
+        reused: true,
+      };
+    }
+    throw new Error(
+      `WeChat preview server already running at ${existing.lock.url} (pid ${existing.lock.pid})`,
+    );
+  }
+
+  if (existing.kind === "stale_lock") {
+    clearServerLock();
+  }
+
+  const baseUrl = previewBaseUrl(host, port);
+
+  const server = Bun.serve({
+    hostname: host,
+    port,
+    async fetch(req) {
+      const url = new URL(req.url);
+      const { pathname } = url;
+
+      if (pathname === "/api/health") {
+        return json({ ok: true, service: "wechat-preview", url: baseUrl, pid: process.pid });
+      }
+
+      if (pathname === "/api/entries" && req.method === "GET") {
+        return json(listPreviewEntries());
+      }
+
+      if (pathname === "/api/entries" && req.method === "POST") {
+        let body: PreviewRegisterInput;
+        try {
+          body = (await req.json()) as PreviewRegisterInput;
+        } catch {
+          return json({ error: "invalid JSON body" }, 400);
+        }
+        if (!body || typeof body !== "object") {
+          return json({ error: "body required" }, 400);
+        }
+        const entry = createPreviewEntry({
+          title: String(body.title ?? "Untitled"),
+          account: String(body.account ?? "default"),
+          status: body.status === "failed" ? "failed" : "success",
+          duration_ms: Number(body.duration_ms) || 0,
+          markdown_path: body.markdown_path,
+          html_path: body.html_path,
+          preview_style: body.preview_style,
+          html: body.html,
+          error: body.error,
+          error_kind: body.error_kind,
+          debug: body.debug,
+        });
+        return json({
+          ...entry,
+          html: undefined,
+          preview_url: `${baseUrl}/e/${entry.id}`,
+          dashboard_url: baseUrl,
+        }, 201);
+      }
+
+      if (pathname === "/api/entries" && req.method === "DELETE") {
+        const cleared = clearPreviewEntries();
+        return json({ cleared });
+      }
+
+      const entryApiMatch = pathname.match(/^\/api\/entries\/([^/]+)$/);
+      if (entryApiMatch && req.method === "GET") {
+        const id = decodeURIComponent(entryApiMatch[1] ?? "");
+        const entry = getPreviewEntry(id);
+        if (!entry) return json({ error: "not found" }, 404);
+        return json(entry);
+      }
+
+      const entryPageMatch = pathname.match(/^\/e\/([^/]+)$/);
+      if (entryPageMatch && req.method === "GET") {
+        const id = decodeURIComponent(entryPageMatch[1] ?? "");
+        const entry = getPreviewEntry(id);
+        if (!entry) return html("<h1>Not found</h1>", 404);
+        if (entry.status === "failed" || !entry.html) {
+          return html(renderFailedEntryHtml(entry));
+        }
+        const rewritten = rewriteHtmlLocalAssets(entry.html, baseUrl);
+        return html(buildWechatPreviewShell(rewritten, entry.title));
+      }
+
+      if (pathname === "/local-file" && req.method === "GET") {
+        const resolved = resolveLocalFilePath(url.searchParams.get("path"));
+        if (!resolved.ok) {
+          return json({ error: resolved.error }, resolved.status);
+        }
+        try {
+          const buf = readLocalFile(resolved.path);
+          return new Response(new Uint8Array(buf), {
+            headers: {
+              "content-type": guessContentType(resolved.path),
+              "cache-control": "private, max-age=60",
+            },
+          });
+        } catch (error) {
+          return json({
+            error: error instanceof Error ? error.message : String(error),
+          }, 500);
+        }
+      }
+
+      if (pathname === "/" || pathname === "/index.html") {
+        return html(renderDashboardHtml(baseUrl));
+      }
+
+      return json({ error: "not found" }, 404);
+    },
+  });
+
+  const boundPort = server.port;
+  if (typeof boundPort !== "number") {
+    server.stop(true);
+    throw new Error("WeChat preview server failed to bind a port");
+  }
+
+  const lock = buildLock(host, boundPort, process.pid);
+  writeServerLock(lock);
+
+  const stop = () => {
+    try {
+      server.stop(true);
+    } catch {
+      // ignore
+    }
+    const existingLock = readServerLock();
+    if (existingLock && existingLock.pid === process.pid) {
+      clearServerLock();
+    }
+  };
+
+  process.on("exit", stop);
+  process.on("SIGINT", () => {
+    stop();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    stop();
+    process.exit(0);
+  });
+
+  return {
+    url: lock.url,
+    host: lock.host,
+    port: lock.port,
+    reused: false,
+    stop,
+  };
+}

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

@@ -0,0 +1,33 @@
+export {
+  DEFAULT_PREVIEW_HOST,
+  DEFAULT_PREVIEW_PORT,
+  getPreviewServerDir,
+  previewBaseUrl,
+  resolvePreviewHost,
+  resolvePreviewPort,
+} from "./paths";
+export {
+  clearPreviewEntries,
+  createPreviewEntry,
+  getPreviewEntry,
+  listPreviewEntries,
+} from "./registry";
+export {
+  buildLock,
+  clearServerLock,
+  findExistingServer,
+  probeHealth,
+  readServerLock,
+} from "./singleton";
+export {
+  ensurePreviewServer,
+  getPreviewServerStatus,
+  registerPreviewEntry,
+} from "./client";
+export { startPreviewServer } from "./http";
+export type {
+  PreviewEntry,
+  PreviewEntryMeta,
+  PreviewRegisterInput,
+  PreviewServerLock,
+} from "./types";

package/src/wechat-preview/server/local-file.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test";
+import { homedir } from "os";
+import { join } from "path";
+import { resolveLocalFilePath, rewriteHtmlLocalAssets } from "./local-file";
+
+describe("resolveLocalFilePath", () => {
+  test("rejects empty path", () => {
+    expect(resolveLocalFilePath("")).toEqual({
+      ok: false,
+      status: 400,
+      error: "missing path",
+    });
+  });
+
+  test("rejects relative paths", () => {
+    const result = resolveLocalFilePath("relative/img.png");
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.status).toBe(400);
+  });
+
+  test("rejects path outside home (except /tmp)", () => {
+    const result = resolveLocalFilePath("/etc/passwd");
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.status).toBe(403);
+  });
+
+  test("accepts existing file under home", () => {
+    // package.json under repo may be outside home in some setups; use a file in home if possible
+    const candidate = join(homedir(), ".zshrc");
+    const result = resolveLocalFilePath(candidate);
+    if (result.ok) {
+      expect(result.path).toBe(candidate);
+    } else {
+      // .zshrc may not exist; still ensure absolute home path is not rejected for wrong reason
+      expect(result.status).not.toBe(403);
+    }
+  });
+});
+
+describe("rewriteHtmlLocalAssets", () => {
+  test("rewrites absolute img src to local-file proxy", () => {
+    const html = '<img src="/Users/me/pic.png" alt="x">';
+    const out = rewriteHtmlLocalAssets(html, "http://127.0.0.1:18765");
+    expect(out).toContain("/local-file?path=");
+    expect(out).toContain(encodeURIComponent("/Users/me/pic.png"));
+  });
+
+  test("leaves https sources alone", () => {
+    const html = '<img src="https://cdn.example.com/a.png">';
+    expect(rewriteHtmlLocalAssets(html, "http://127.0.0.1:18765")).toBe(html);
+  });
+});

package/src/wechat-preview/server/local-file.ts

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync, statSync } from "fs";
+import { homedir } from "os";
+import { isAbsolute, resolve } from "path";
+
+const HOME = homedir();
+
+/**
+ * Resolve a local filesystem path for the /local-file proxy.
+ * Rejects non-absolute paths, missing files, and paths outside $HOME (unless overridden).
+ */
+export function resolveLocalFilePath(
+  raw: string | null,
+  options: { allowOutsideHome?: boolean } = {},
+): { ok: true; path: string } | { ok: false; status: number; error: string } {
+  if (!raw || !raw.trim()) {
+    return { ok: false, status: 400, error: "missing path" };
+  }
+
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(raw.trim());
+  } catch {
+    return { ok: false, status: 400, error: "invalid path encoding" };
+  }
+
+  // Strip file:// prefix if present
+  if (decoded.startsWith("file://")) {
+    try {
+      decoded = new URL(decoded).pathname;
+      // macOS: file:///Users/... → /Users/...
+    } catch {
+      return { ok: false, status: 400, error: "invalid file URL" };
+    }
+  }
+
+  if (!isAbsolute(decoded)) {
+    return { ok: false, status: 400, error: "path must be absolute" };
+  }
+
+  const resolved = resolve(decoded);
+  if (resolved.includes("\0")) {
+    return { ok: false, status: 400, error: "invalid path" };
+  }
+
+  if (!options.allowOutsideHome && !resolved.startsWith(HOME + "/") && resolved !== HOME) {
+    // Also allow /tmp for debug artifacts
+    if (!resolved.startsWith("/tmp/") && resolved !== "/tmp") {
+      return { ok: false, status: 403, error: "path outside home directory" };
+    }
+  }
+
+  if (!existsSync(resolved)) {
+    return { ok: false, status: 404, error: "file not found" };
+  }
+
+  try {
+    const st = statSync(resolved);
+    if (!st.isFile()) {
+      return { ok: false, status: 400, error: "not a file" };
+    }
+  } catch {
+    return { ok: false, status: 404, error: "file not accessible" };
+  }
+
+  return { ok: true, path: resolved };
+}
+
+export function guessContentType(path: string): string {
+  const lower = path.toLowerCase();
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  if (lower.endsWith(".gif")) return "image/gif";
+  if (lower.endsWith(".webp")) return "image/webp";
+  if (lower.endsWith(".svg")) return "image/svg+xml";
+  if (lower.endsWith(".avif")) return "image/avif";
+  if (lower.endsWith(".html") || lower.endsWith(".htm")) return "text/html; charset=utf-8";
+  if (lower.endsWith(".css")) return "text/css; charset=utf-8";
+  if (lower.endsWith(".js")) return "text/javascript; charset=utf-8";
+  if (lower.endsWith(".json")) return "application/json; charset=utf-8";
+  return "application/octet-stream";
+}
+
+export function readLocalFile(path: string): Buffer {
+  return readFileSync(path);
+}
+
+/**
+ * Rewrite absolute / file:// image src attributes to the local-file proxy.
+ */
+export function rewriteHtmlLocalAssets(html: string, baseOrigin: string): string {
+  const proxy = (src: string): string => {
+    const trimmed = src.trim();
+    if (!trimmed) return src;
+    if (/^(?:https?:|data:|blob:|\/\/)/i.test(trimmed)) return src;
+    if (trimmed.startsWith("/local-file")) return src;
+
+    let abs = trimmed;
+    if (trimmed.startsWith("file://")) {
+      try {
+        abs = new URL(trimmed).pathname;
+      } catch {
+        return src;
+      }
+    }
+    if (!isAbsolute(abs)) return src;
+    return `${baseOrigin}/local-file?path=${encodeURIComponent(abs)}`;
+  };
+
+  return html
+    .replace(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/gi, (_m, pre, src, post) => {
+      return `${pre}${proxy(src)}${post}`;
+    })
+    .replace(/(<img\b[^>]*\bdata-src=["'])([^"']+)(["'])/gi, (_m, pre, src, post) => {
+      return `${pre}${proxy(src)}${post}`;
+    });
+}

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

@@ -0,0 +1,80 @@
+/**
+ * Data directory for the singleton WeChat preview server.
+ * Mirrors config base-dir resolution in src/config.ts.
+ */
+
+import { existsSync, mkdirSync } from "fs";
+import { homedir, platform } from "os";
+import { join } from "path";
+
+const APP_DIR = "zzhub-pipeline";
+const SERVER_DIR = "wechat-preview";
+
+export const DEFAULT_PREVIEW_HOST = "127.0.0.1";
+export const DEFAULT_PREVIEW_PORT = 18765;
+
+function getBaseConfigDir(appDir: string): string {
+  const home = homedir();
+  const currentPlatform = platform();
+
+  if (currentPlatform === "win32") {
+    const appData = process.env.APPDATA;
+    if (appData) return join(appData, appDir);
+    return join(home, "AppData", "Roaming", appDir);
+  }
+
+  if (currentPlatform === "darwin") {
+    return join(home, "Library", "Application Support", appDir);
+  }
+
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  if (xdgConfigHome && xdgConfigHome.trim().length > 0) {
+    return join(xdgConfigHome, appDir);
+  }
+
+  return join(home, ".config", appDir);
+}
+
+export function getPreviewServerDir(): string {
+  const override = process.env.ZZHUB_WECHAT_PREVIEW_DIR?.trim();
+  if (override) return override;
+  return join(getBaseConfigDir(APP_DIR), SERVER_DIR);
+}
+
+export function getPreviewServerLockPath(): string {
+  return join(getPreviewServerDir(), "server.json");
+}
+
+export function getPreviewEntriesDir(): string {
+  return join(getPreviewServerDir(), "entries");
+}
+
+export function ensurePreviewServerDirs(): void {
+  const root = getPreviewServerDir();
+  const entries = getPreviewEntriesDir();
+  if (!existsSync(root)) mkdirSync(root, { recursive: true });
+  if (!existsSync(entries)) mkdirSync(entries, { recursive: true });
+}
+
+export function resolvePreviewPort(port?: number): number {
+  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);
+  }
+  return DEFAULT_PREVIEW_PORT;
+}
+
+export function resolvePreviewHost(host?: string): string {
+  if (host && host.trim()) return host.trim();
+  const env = process.env.ZZHUB_WECHAT_PREVIEW_HOST?.trim();
+  if (env) return env;
+  return DEFAULT_PREVIEW_HOST;
+}
+
+export function previewBaseUrl(host: string, port: number): string {
+  return `http://${host}:${port}`;
+}