@zzclub/pipeline 0.2.0 → 0.4.0

package/src/commands/reset.ts

@@ -0,0 +1,159 @@
+/**
+ * reset — Reset phases for revision re-entry.
+ *
+ * Implements the revision protocol from revision-protocol.md.
+ *
+ * Usage:
+ *   zzhub-pipeline reset --state /path/to/state.json --mode <mode>
+ *
+ * Modes:
+ *   content    — Reset prepare+render+publish (for re-writing body)
+ *   redo.style — Reset prepare+render+publish, start from style step
+ *   redo.format — Reset prepare+render+publish, start from format step
+ *   redo.metadata — Reset prepare+render+publish, start from metadata step
+ *   redo.route — Reset prepare+render+publish, start from route step
+ *   render     — Reset render+publish (for re-generating images)
+ *   publish    — Reset publish only (for re-publishing)
+ *   full       — Mark current as abandoned, prepare for full re-run
+ *
+ * Output: Updated state JSON summary.
+ */
+
+import { parseArgs, requireArg } from "../args";
+import { printResult, renderReset } from "../output";
+import { readState, writeState, defaultContentReview } from "../state";
+
+type ResetMode =
+  | "content"
+  | "redo.style"
+  | "redo.format"
+  | "redo.metadata"
+  | "redo.route"
+  | "render"
+  | "publish"
+  | "full";
+
+const VALID_MODES: ResetMode[] = [
+  "content",
+  "redo.style",
+  "redo.format",
+  "redo.metadata",
+  "redo.route",
+  "render",
+  "publish",
+  "full",
+];
+
+export async function reset(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline reset [options]
+
+Options:
+  --state    Path to state JSON (required)
+  --mode     Reset mode (required): ${VALID_MODES.join(" | ")}
+
+Modes:
+  content        Reset all phases (for body rewrite, requires writer re-run)
+  redo.style     From style step (skip writer)
+  redo.format    From format step
+  redo.metadata  From metadata step
+  redo.route     From route step
+  render         Reset render+publish (for image re-generation)
+  publish        Reset publish only (for re-publish)
+  full           Abandon current, prepare for full re-run
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const mode = requireArg(parsed, "mode", "reset mode") as ResetMode;
+
+  if (!VALID_MODES.includes(mode)) {
+    throw new Error(
+      `Invalid reset mode: ${mode}. Valid modes: ${VALID_MODES.join(", ")}`,
+    );
+  }
+
+  const state = await readState(statePath);
+
+  switch (mode) {
+    case "content":
+    case "redo.style":
+    case "redo.format":
+    case "redo.metadata":
+    case "redo.route":
+      // Reset prepare + render + publish
+      state.phase.prepare = { status: "pending", error: null };
+      state.phase.render = { status: "pending", error: null };
+      state.phase.publish = { status: "pending", error: null };
+      state.phase.current = "prepare";
+      state.mode = "active";
+      // Persist redo hint so orchestrator can recover start step even after context loss
+      state.redo_hint =
+        mode === "redo.style"
+          ? "style"
+          : mode === "redo.format"
+            ? "format"
+            : mode === "redo.metadata"
+              ? "asset-meta"
+              : mode === "redo.route"
+                ? "channel-route"
+                : "writer"; // content
+      // Reset content_review for content rewrite (writer will produce new body)
+      if (mode === "content") {
+        state.content_review = defaultContentReview();
+      }
+      break;
+
+    case "render":
+      // Reset render + publish, keep prepare done
+      state.phase.render = { status: "pending", error: null };
+      state.phase.publish = { status: "pending", error: null };
+      state.phase.current = "render";
+      state.mode = "active";
+      state.redo_hint = null;
+      // Reset image plan status
+      if (state.images.plan.needed) {
+        state.images.plan.status = "planned";
+      }
+      break;
+
+    case "publish":
+      // Reset publish only
+      state.phase.publish = { status: "pending", error: null };
+      state.phase.current = "publish";
+      state.mode = "active";
+      state.redo_hint = null;
+      // Don't change content_version or render_version
+      break;
+
+    case "full":
+      // Mark current state as failed/abandoned
+      state.mode = "failed";
+      state.phase.current = "failed";
+      state.content_review = defaultContentReview();
+      state.redo_hint = null;
+      break;
+  }
+
+  await writeState(statePath, state);
+
+  const output = {
+    state_path: statePath,
+    reset_mode: mode,
+    mode: state.mode,
+    phase: {
+      current: state.phase.current,
+      prepare: state.phase.prepare.status,
+      render: state.phase.render.status,
+      publish: state.phase.publish.status,
+    },
+    // redo_hint is persisted in state; also echoed here for convenience
+    start_step: state.redo_hint ?? null,
+  };
+
+  printResult(output, renderReset);
+}

package/src/commands/review.ts

@@ -0,0 +1,77 @@
+/**
+ * review — Update content_review state after orchestrator quality check.
+ *
+ * The actual quality review is done by the orchestrator (LLM judgment).
+ * This command only persists the review decision to the state file.
+ *
+ * Usage:
+ *   zzhub-pipeline review --state /path/to/state.json --status passed
+ *   zzhub-pipeline review --state /path/to/state.json --status needs_revision --feedback "AI味过重，建议..."
+ *
+ * Statuses:
+ *   passed          — Content passed quality check, proceed to next step
+ *   needs_revision  — Content has issues, will be sent back to Writer
+ *
+ * Output: Updated content_review state as JSON.
+ */
+
+import { parseArgs, requireArg, optionalArg } from "../args";
+import { printResult, renderReview } from "../output";
+import { readState, writeState, type ContentReviewStatus } from "../state";
+
+const VALID_STATUSES: ContentReviewStatus[] = [
+  "passed",
+  "needs_revision",
+];
+
+export async function review(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline review [options]
+
+Options:
+  --state      Path to state JSON (required)
+  --status     passed | needs_revision (required)
+  --feedback   Revision feedback for Writer (required when status=needs_revision)
+
+Statuses:
+  passed          Content passed quality check
+  needs_revision  Content has issues, send back to Writer with feedback
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const status = requireArg(parsed, "status", "review status") as ContentReviewStatus;
+  const feedback = optionalArg(parsed, "feedback") ?? null;
+
+  if (!VALID_STATUSES.includes(status)) {
+    throw new Error(
+      `Invalid review status: ${status}. Valid statuses: ${VALID_STATUSES.join(", ")}`,
+    );
+  }
+
+  if (status === "needs_revision" && !feedback) {
+    throw new Error(
+      "Feedback is required when status is needs_revision (--feedback \"...\")",
+    );
+  }
+
+  const state = await readState(statePath);
+
+  state.content_review = {
+    status,
+    feedback: status === "needs_revision" ? feedback : null,
+  };
+
+  await writeState(statePath, state);
+
+  const output = {
+    state_path: statePath,
+    content_review: state.content_review,
+  };
+
+  printResult(output, renderReview);
+}

package/src/commands/status.ts

@@ -0,0 +1,68 @@
+import { parseArgs, optionalArg, requireArg } from "../args";
+import { printResult, renderTaskShape } from "../output";
+import { findTask, getTaskByStatePath } from "../task-manager";
+import { buildAgentTaskShape, parseTaskViewMode, renderTaskStatusMarkdown } from "../task-views";
+
+export async function status(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+  const positional = JSON.parse(String(parsed._ ?? "[]")) as string[];
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline status [options]
+
+Options:
+  --state      Path to state JSON
+  --run-id     Run id to resolve inside workspace
+  --workspace  Workspace root (optional; when used alone, resolves the current active task)
+  --full       Include the full state payload
+  --view       json | markdown | agent | agent-json (default: json)
+`.trim());
+    return;
+  }
+
+  if (positional.length > 0) {
+    throw new Error(`Unexpected positional arguments: ${positional.join(" ")}. Use --state or --run-id.`);
+  }
+
+  const statePath = optionalArg(parsed, "state");
+  const workspace = optionalArg(parsed, "workspace");
+  const includeFull = parsed.full === true || parsed.full === "true";
+  const view = parseTaskViewMode(optionalArg(parsed, "view"));
+
+  const task = statePath
+    ? await getTaskByStatePath(statePath)
+    : await findTask(
+        workspace,
+        optionalArg(parsed, "run-id")
+          ? { run_id: requireArg(parsed, "run-id", "run id") }
+          : { active_only: true },
+      );
+
+  if (!task) {
+    throw new Error("Task not found");
+  }
+
+  if (view === "agent-json") {
+    console.log(JSON.stringify(buildAgentTaskShape(task), null, 2));
+    return;
+  }
+
+  if (view !== "json") {
+    console.log(renderTaskStatusMarkdown(task, view));
+    return;
+  }
+
+  printResult(
+    includeFull
+      ? task
+      : {
+          summary: task.summary,
+          validation: task.validation,
+          gaps: task.gaps,
+          blockers: task.blockers,
+          next_action: task.next_action,
+        },
+    renderTaskShape,
+  );
+}

package/src/commands/sync-blog.ts

@@ -0,0 +1,39 @@
+import { parseArgs, requireArg, flagArg } from "../args";
+import { printResult, renderSyncBlog } from "../output";
+import { loadConfig, resolveWorkspacePaths } from "../config";
+import { readState } from "../state";
+import { publishBlogRoute } from "../providers/blog";
+
+export async function syncBlog(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline sync-blog [options]
+
+Options:
+  --state    Path to state JSON (required)
+  --dry-run  Print the target copy/publish command without executing
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const dryRun = flagArg(parsed, "dry-run");
+  const state = await readState(statePath);
+
+  if (!state.asset_path) {
+    throw new Error("asset_path not set. Run prepare-finalize first.");
+  }
+
+  const config = loadConfig();
+  const workspacePaths = resolveWorkspacePaths(state.workspace_root, config);
+  const result = await publishBlogRoute({
+    state,
+    dryRun,
+    config,
+    workspacePaths,
+  });
+
+  printResult(result, renderSyncBlog);
+}

package/src/commands/tasks.ts

@@ -0,0 +1,50 @@
+import { parseArgs, optionalArg } from "../args";
+import { printResult, renderTasks } from "../output";
+import { filterActiveTasks, listTasks } from "../task-manager";
+import { buildAgentTasksShape, parseTaskViewMode, renderTasksView } from "../task-views";
+
+export async function tasks(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline tasks [options]
+
+Options:
+  --workspace  Workspace root (optional)
+  --active     Only return in-flight tasks (active/handoff)
+  --full       Include the full state payload for every task
+  --view       json | markdown | agent | agent-json (default: json)
+`.trim());
+    return;
+  }
+
+  const workspace = optionalArg(parsed, "workspace");
+  const includeFull = parsed.full === true || parsed.full === "true";
+  const activeOnly = parsed.active === true || parsed.active === "true";
+  const view = parseTaskViewMode(optionalArg(parsed, "view"));
+  const allTasks = await listTasks(workspace);
+  const visibleTasks = activeOnly ? filterActiveTasks(allTasks) : allTasks;
+
+  if (view === "agent-json") {
+    console.log(JSON.stringify(buildAgentTasksShape(visibleTasks), null, 2));
+    return;
+  }
+
+  if (view !== "json") {
+    console.log(renderTasksView(visibleTasks, view));
+    return;
+  }
+
+  printResult(
+    includeFull
+      ? visibleTasks
+      : visibleTasks.map((task) => ({
+          summary: task.summary,
+          validation: task.validation,
+          blockers: task.blockers,
+          next_action: task.next_action,
+        })),
+    renderTasks,
+  );
+}

package/src/commands/wechat-export.ts

@@ -0,0 +1,68 @@
+import { optionalArg, parseArgs, requireArg } from "../args";
+import { printResult, renderWechatExport } from "../output";
+import { loadConfig } from "../config";
+import { resolveMarkdownRenderer } from "../adapter-loader";
+
+const CSS_DEMO = `
+Custom CSS is injected as a <style> tag after the built-in Milkdown styles
+and before the browser renders. WeChat requires inline styles, so the
+rendering pipeline captures computed styles from the DOM — your CSS
+cascades naturally and the final inline-styled HTML will reflect it.
+
+Example custom.css:
+
+  /* Tweak headings */
+  h1 { color: #1a1a2e; font-size: 22px; }
+  h2 { color: #333; border-bottom: 1px solid #eee; }
+
+  /* Wider paragraph spacing */
+  p { margin: 1.2em 0; line-height: 2; }
+
+  /* Subtle blockquote */
+  blockquote {
+    border-left: 3px solid #b35d85;
+    background: #fdf6f9;
+    padding: 8px 14px;
+  }
+`.trim();
+
+export async function wechatExport(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline wechat-export [options]
+
+Options:
+  --markdown           Path to markdown file (required)
+  --out                Path to exported html file (required)
+  --account            Account/theme key (optional; default: default)
+  --title              Page title for the render shell (optional)
+  --preview-shell-out  Path to full Milkdown preview html (optional)
+  --custom-css         Path to custom CSS file for style overrides (optional)
+
+${CSS_DEMO}
+`.trim());
+    return;
+  }
+
+  const markdownPath = requireArg(parsed, "markdown", "markdown file path");
+  const outPath = requireArg(parsed, "out", "html output path");
+  const account = optionalArg(parsed, "account") ?? "default";
+  const title = optionalArg(parsed, "title");
+  const previewShellOutPath = optionalArg(parsed, "preview-shell-out");
+  const customCss = optionalArg(parsed, "custom-css");
+
+  const config = loadConfig();
+  const markdownRenderer = await resolveMarkdownRenderer(config);
+  const result = await markdownRenderer.render({
+    markdownPath,
+    outPath,
+    account,
+    title,
+    previewShellOutPath,
+    customCss,
+  });
+
+  printResult(result, renderWechatExport);
+}

package/src/imgx/ascii-portrait.ts

@@ -0,0 +1,77 @@
+import { join } from "node:path";
+import {
+  escapeHtml,
+  FONTS_DIR,
+  ICONS_DIR,
+  readUtf8,
+  renderTemplate,
+  resolveInputPath,
+  screenshotHtml,
+  TEMPLATES_DIR,
+} from "./runtime";
+
+export type AsciiPortraitOptions = {
+  avatarPath: string;
+  bg: string;
+  chars: string;
+  columns: number;
+  fontSize: number;
+  lineHeight: number;
+  title?: string;
+  footer?: string;
+  iconPath?: string;
+  width?: number;
+  height?: number;
+  templateName?: "ascii-portrait-3-4" | "ascii-portrait-tile";
+};
+
+function serializeConfig(options: AsciiPortraitOptions): string {
+  return JSON.stringify({
+    avatarPath: options.avatarPath,
+    bgColor: options.bg,
+    chars: options.chars,
+    columns: options.columns,
+    fontSize: options.fontSize,
+    lineHeight: options.lineHeight,
+  })
+    .replaceAll("<", "\\u003c")
+    .replaceAll(">", "\\u003e")
+    .replaceAll("&", "\\u0026")
+    .replaceAll("</script", "<\\/script");
+}
+
+export function buildAsciiPortraitHtml(options: AsciiPortraitOptions): string {
+  const templateName = options.templateName ?? "ascii-portrait-3-4";
+  const template = readUtf8(join(TEMPLATES_DIR, `${templateName}.html`));
+  const width = options.width ?? 900;
+  const height = options.height ?? 1200;
+
+  return renderTemplate(template, {
+    "{{BG_COLOR}}": options.bg,
+    "{{TITLE}}": escapeHtml(options.title ?? "ASCII Portrait"),
+    "{{FOOTER_TEXT}}": escapeHtml(options.footer ?? "公众号 · 早早集市"),
+    "{{ICON_PATH}}": resolveInputPath(options.iconPath ?? join(ICONS_DIR, "logo.png")),
+    "{{AVATAR_PATH}}": resolveInputPath(options.avatarPath),
+    "{{ASCII_CONFIG_JSON}}": serializeConfig(options),
+    "{{FONT_PATH}}": join(FONTS_DIR, "AlimamaShuHeiTi-Bold.ttf"),
+    "{{BODY_FONT_PATH}}": join(FONTS_DIR, "LXGWWenKai-Regular.ttf"),
+    "{{CANVAS_WIDTH}}": String(width),
+    "{{CANVAS_HEIGHT}}": String(height),
+  });
+}
+
+export function renderAsciiPortraitPng(options: AsciiPortraitOptions & {
+  chromePath: string;
+  outPath: string;
+}): void {
+  const width = options.width ?? 900;
+  const height = options.height ?? 1200;
+  screenshotHtml({
+    chromePath: options.chromePath,
+    html: buildAsciiPortraitHtml(options),
+    outPath: options.outPath,
+    width,
+    height,
+    virtualTimeBudgetMs: 1800,
+  });
+}

package/src/imgx/assets/icons/logo.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" width="100" height="100">
+  <!-- Zigzag S logo - top chevron -->
+  <path d="M72 20 L30 44" stroke="#22a854" stroke-width="16" stroke-linecap="round" fill="none"/>
+  <!-- Zigzag S logo - bottom chevron -->
+  <path d="M30 56 L72 80" stroke="#22a854" stroke-width="16" stroke-linecap="round" fill="none"/>
+  <!-- Small connecting gap indicator -->
+  <line x1="30" y1="44" x2="30" y2="56" stroke="#22a854" stroke-width="4" stroke-linecap="round" fill="none" opacity="0.5"/>
+</svg>

package/{dist/assets → src}/imgx/assets/templates/longform-3-4.html

@@ -112,7 +112,7 @@
     position: absolute;
     object-fit: cover;
     border-radius: var(--image-radius);
-    box-shadow: 0 16px 30px rgb(27 26 24 / 0.12);
+    box-shadow: 0 var(--img-shadow-y, 16px) var(--img-shadow-blur, 30px) rgb(27 26 24 / 0.12);
     background: #ebe7de;
   }
   .body-caption {