@zzclub/pipeline 0.2.0 → 0.4.0

package/src/commands/publish.ts

@@ -0,0 +1,147 @@
+/**
+ * publish — Execute publish routes.
+ *
+ * Reads state, determines which routes to publish, executes publish commands,
+ * records results. Supports idempotent skipping based on version matching.
+ *
+ * Usage:
+ *   zzhub-pipeline publish \
+ *     --state /path/to/state.json \
+ *     [--route wechat-article] (override: only publish this route)
+ *     [--dry-run]
+ *
+ * Output: Updated state with publish.results
+ */
+
+import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
+import { printResult, renderPublish } from "../output";
+import { loadConfig, resolveWorkspacePaths } from "../config";
+import { getPublishProvider } from "../providers";
+import {
+  readState,
+  validateForPhase,
+  writeState,
+  type PublishResult,
+  type RoutePrimary,
+} from "../state";
+
+export async function publish(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline publish [options]
+
+Options:
+  --state      Path to state JSON (required)
+  --route      Only publish this route (optional; default: all routes)
+  --dry-run    Print commands without executing (optional)
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const routeOverride = optionalArg(parsed, "route") as RoutePrimary | undefined;
+  const dryRun = flagArg(parsed, "dry-run");
+
+  const state = await readState(statePath);
+  const config = loadConfig();
+  const workspacePaths = resolveWorkspacePaths(state.workspace_root, config);
+  const validationErrors = validateForPhase(state, "publish");
+
+  if (!state.asset_path) {
+    throw new Error("asset_path not set. Cannot publish.");
+  }
+  if (validationErrors.length > 0) {
+    throw new Error(
+      `Publish validation failed: ${validationErrors.map((item) => `${item.field}: ${item.message}`).join("; ")}`,
+    );
+  }
+
+  // Collect all routes to publish
+  const routes: RoutePrimary[] = routeOverride
+    ? [routeOverride]
+    : [state.route.primary, ...state.route.extras];
+
+  const results: PublishResult[] = [...state.publish.results];
+  let hasUnfinishedPublish = false;
+
+  for (const route of routes) {
+    // ── Idempotency check ──
+    const existing = results.find((r) => r.route === route);
+    if (
+      existing &&
+      existing.status === "success" &&
+      existing.content_version === state.artifacts.content_version &&
+      existing.render_version === state.artifacts.render_version
+    ) {
+      console.error(`[publish] Skipping ${route}: already published at current version`);
+      continue;
+    }
+
+    try {
+      const provider = getPublishProvider(route);
+      const result = await provider({
+        state,
+        dryRun,
+        config,
+        workspacePaths,
+      });
+
+      // Upsert result
+      const idx = results.findIndex((r) => r.route === route);
+      if (idx >= 0) {
+        results[idx] = result;
+      } else {
+        results.push(result);
+      }
+
+      if (result.status !== "success" && result.status !== "skipped") {
+        hasUnfinishedPublish = true;
+      }
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      const failResult: PublishResult = {
+        route,
+        status: "failed",
+        detail,
+        published_at: null,
+        content_version: state.artifacts.content_version,
+        render_version: state.artifacts.render_version,
+      };
+      const idx = results.findIndex((r) => r.route === route);
+      if (idx >= 0) {
+        results[idx] = failResult;
+      } else {
+        results.push(failResult);
+      }
+      hasUnfinishedPublish = true;
+    }
+  }
+
+  // Update state
+  state.publish.results = results;
+
+  const allDone = routes.every((route) => {
+    const r = results.find((x) => x.route === route);
+    return r && (r.status === "success" || r.status === "skipped");
+  });
+
+  if (allDone) {
+    state.mode = "done";
+    state.phase.publish = { status: "done", error: null };
+    state.phase.current = "done";
+  } else if (hasUnfinishedPublish) {
+    state.mode = "active";
+    state.phase.publish = { status: "pending", error: null };
+    state.phase.current = "publish";
+  }
+
+  await writeState(statePath, state);
+
+  printResult({
+    publish_results: results,
+    mode: state.mode,
+    phase: state.phase.current,
+  }, renderPublish);
+}

package/src/commands/reconcile.ts

@@ -0,0 +1,36 @@
+import { parseArgs, requireArg } from "../args";
+import { printResult, renderTaskShape } from "../output";
+import { readState, writeState } from "../state";
+import { getTaskByStatePath } from "../task-manager";
+import { reconcileStateArtifacts } from "../workflow-materials";
+
+export async function reconcile(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline reconcile [options]
+
+Options:
+  --state  Path to state JSON (required)
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const state = await readState(statePath);
+  await reconcileStateArtifacts(state);
+  await writeState(statePath, state);
+
+  const task = await getTaskByStatePath(statePath);
+  printResult(
+    {
+      summary: task.summary,
+      validation: task.validation,
+      gaps: task.gaps,
+      blockers: task.blockers,
+      next_action: task.next_action,
+    },
+    renderTaskShape,
+  );
+}

package/src/commands/render.ts

@@ -0,0 +1,244 @@
+/**
+ * render — Execute Render phase: image-plan + adapter-based rendering.
+ *
+ * 1. Reads state + post.md
+ * 2. Runs image-plan logic (template selection, cover_title, output_dir)
+ * 3. Invokes image renderer adapter (pluggable via config.plugins)
+ * 4. Records render_assets and bumps render_version
+ *
+ * Usage:
+ *   zzhub-pipeline render \
+ *     --state /path/to/state.json \
+ *     [--skip-render]  (plan only, don't invoke renderer)
+ *
+ * Output: Updated state with images.plan, images.render_assets
+ */
+
+import { readFile } from "fs/promises";
+import { join } from "path";
+
+import { parseArgs, requireArg, flagArg } from "../args";
+import { printResult, renderRender } from "../output";
+import { loadConfig } from "../config";
+import { resolveImageRenderer } from "../adapter-loader";
+import {
+  defaultBodyInputs,
+  normalizeNewspicRenderSpec,
+  readState,
+  writeState,
+  type NewspicRenderSpec,
+} from "../state";
+import {
+  stripFrontmatter,
+  generateCoverTitle,
+} from "../text";
+import { getLongformTheme } from "../routes";
+import { collectNewspicRequiredMarkers } from "../workflow-materials";
+
+function getNewspicRenderSpec(state: Awaited<ReturnType<typeof readState>>): NewspicRenderSpec {
+  const spec = normalizeNewspicRenderSpec(state.intent.newspic_render);
+  return {
+    ...spec,
+    min_pages: Math.max(spec.min_pages, spec.pagination_mode === "multi" ? 2 : 1),
+  };
+}
+
+export async function render(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline render [options]
+
+Options:
+  --state        Path to state JSON (required)
+  --skip-render  Plan only, don't invoke renderer (optional)
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const skipRender = flagArg(parsed, "skip-render");
+
+  const state = await readState(statePath);
+
+  // Validate prerequisites
+  if (!state.asset_path) {
+    throw new Error("asset_path not set. Run prepare-finalize first.");
+  }
+
+  const postPath = join(state.asset_path, "post.md");
+  const postContent = await readFile(postPath, "utf-8");
+  const cleanBody = stripFrontmatter(postContent);
+
+  // ── Image Plan ──────────────────────────────────────────────────
+
+  const routePrimary = state.route.primary;
+
+  if (routePrimary === "blog") {
+    // Blog doesn't need images by default
+    state.images.plan = {
+      needed: false,
+      template: null,
+      cover_template: null,
+      cover_title: null,
+      output_dir: null,
+      preview_required: false,
+      status: "skipped",
+    };
+    state.images.render_assets = [];
+    state.phase.render = { status: "done", error: null };
+    state.phase.current = state.intent.requires.publish ? "publish" : "done";
+    await writeState(statePath, state);
+    printResult({
+      plan: state.images.plan,
+      render_assets: [],
+      phase: state.phase.current,
+    }, renderRender);
+    return;
+  }
+
+  let template: string;
+  let coverTemplate: string | null = null;
+  let coverTitle: string | null = null;
+  let outputDir: string;
+  const newspicRenderSpec = getNewspicRenderSpec(state);
+
+  if (routePrimary === "wechat-article") {
+    template = "wechat-cover-split";
+    outputDir = join(state.asset_path, "images", "wechat");
+  } else {
+    // wechat-newspic: determine short vs long
+    const isLong = newspicRenderSpec.pagination_mode === "multi";
+
+    if (isLong) {
+      template = "longform-3-4";
+      coverTemplate = "poster-3-4";
+      coverTitle = generateCoverTitle(state.metadata.title);
+    } else {
+      template = "poster-3-4";
+      coverTitle = generateCoverTitle(state.metadata.title);
+    }
+    outputDir = join(state.asset_path, "images", "newspic");
+  }
+
+  state.images.plan = {
+    needed: true,
+    template,
+    cover_template: coverTemplate,
+    cover_title: coverTitle,
+    output_dir: outputDir,
+    preview_required: false,
+    status: "planned",
+  };
+
+  // For longform, set up body_inputs
+  if (template === "longform-3-4") {
+    const markers = collectNewspicRequiredMarkers(cleanBody, state);
+    const previousInputs =
+      state.images.body_inputs.scope === "newspic-longform"
+        ? state.images.body_inputs
+        : null;
+    const markerSet = new Set(markers);
+    const received = previousInputs
+      ? previousInputs.received.filter((item) => markerSet.has(item.marker))
+      : [];
+    state.images.body_inputs = {
+      scope: "newspic-longform",
+      expected: markers.length,
+      received,
+      status:
+        markers.length === 0
+          ? "none"
+          : received.length >= markers.length
+            ? "ready"
+            : "pending",
+      layout: previousInputs?.layout ?? newspicRenderSpec.default_image_layout,
+    };
+
+    // If body inputs are pending, we need to pause for user
+    if (state.images.body_inputs.status === "pending") {
+      state.images.plan.status = "planned";
+      await writeState(statePath, state);
+      printResult({
+        plan: state.images.plan,
+        body_inputs: state.images.body_inputs,
+        newspic_render: newspicRenderSpec,
+        waiting_for_user: true,
+        message: `Waiting for ${markers.length} body image(s)`,
+        phase: state.phase.current,
+      }, renderRender);
+      return;
+    }
+  } else if (state.images.body_inputs.scope === "newspic-longform") {
+    state.images.body_inputs = defaultBodyInputs();
+  }
+
+  if (skipRender) {
+    await writeState(statePath, state);
+    printResult({
+      plan: state.images.plan,
+      newspic_render: routePrimary === "wechat-newspic" ? newspicRenderSpec : null,
+      skip_render: true,
+      phase: state.phase.current,
+    }, renderRender);
+    return;
+  }
+
+  // ── Invoke image renderer adapter ───────────────────────────────
+
+  const config = loadConfig();
+  const imageRenderer = await resolveImageRenderer(config);
+
+  const bodyImages = (
+    state.images.body_inputs.scope === "newspic-longform" &&
+    state.images.body_inputs.status === "ready"
+  )
+    ? state.images.body_inputs.received
+    : [];
+
+  const renderResult = await imageRenderer.render({
+    state,
+    bodyText: cleanBody,
+    outputDir,
+    title: state.metadata.title,
+    route: routePrimary,
+    pageSpecs: newspicRenderSpec.page_specs.map((ps) => ({
+      page: ps.page,
+      imageMarkers: ps.image_markers,
+      imageLayout: ps.image_layout ?? undefined,
+      targetFillRatio: ps.target_fill_ratio ?? undefined,
+      note: ps.note ?? undefined,
+    })),
+    bodyImages,
+    minPages: newspicRenderSpec.min_pages,
+    maxPages: newspicRenderSpec.max_pages,
+    accountVisualParams: state.route.account_visual_params
+      ? {
+          footer: state.route.account_visual_params.footer,
+          bg: state.route.account_visual_params.bg,
+          highlight: state.route.account_visual_params.highlight,
+          fallbackIcon: state.route.account_visual_params.fallback_icon,
+        }
+      : undefined,
+    theme: routePrimary === "wechat-newspic" ? getLongformTheme(state.route.account) : undefined,
+    template,
+  });
+
+  // ── Update state ────────────────────────────────────────────────
+
+  state.images.render_assets = renderResult.assets;
+  state.images.plan.status = "rendered";
+  state.phase.render = { status: "done", error: null };
+  state.phase.current = state.intent.requires.publish ? "publish" : "done";
+  state.artifacts.render_version += 1;
+
+  await writeState(statePath, state);
+
+  printResult({
+    plan: state.images.plan,
+    render_assets: renderResult.assets,
+    render_version: state.artifacts.render_version,
+    phase: state.phase.current,
+  }, renderRender);
+}

package/src/commands/reset.test.ts

@@ -0,0 +1,151 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, writeFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+
+import { reset } from "./reset";
+import { defaultState, readState, writeState } from "../state";
+
+const TEST_CONFIG_PATH = join(tmpdir(), `zzhub-pipeline-test-config-reset-${process.pid}.json`);
+process.env.ZZHUB_PIPELINE_CONFIG = TEST_CONFIG_PATH;
+
+async function makeTempDir(prefix: string): Promise<string> {
+  return mkdtemp(join(tmpdir(), prefix));
+}
+
+async function captureJsonOutput<T>(fn: () => Promise<void>): Promise<T> {
+  const original = console.log;
+  const lines: string[] = [];
+  console.log = (...args: unknown[]) => {
+    lines.push(args.map((value) => String(value)).join(" "));
+  };
+  try {
+    await fn();
+  } finally {
+    console.log = original;
+  }
+  return JSON.parse(lines.join("\n").trim()) as T;
+}
+
+beforeEach(async () => {
+  await writeFile(TEST_CONFIG_PATH, "{}", "utf-8");
+});
+
+describe("reset", () => {
+  test("mode=content resets all three phases and clears content_review", async () => {
+    const workspace = await makeTempDir("zzhub-reset-content-");
+    const statePath = join(workspace, "state.json");
+
+    const state = defaultState();
+    state.workspace_root = workspace;
+    state.state_path = statePath;
+    state.run_id = "run-reset-content";
+    state.phase.prepare = { status: "done", error: null };
+    state.phase.render = { status: "done", error: null };
+    state.phase.publish = { status: "done", error: null };
+    state.phase.current = "done";
+    state.content_review = { status: "passed", feedback: null };
+    await writeState(statePath, state);
+
+    const output = await captureJsonOutput<{ reset_mode: string; start_step: string | null }>(() =>
+      reset(["--state", statePath, "--mode", "content"]),
+    );
+
+    expect(output.reset_mode).toBe("content");
+    expect(output.start_step).toBe("writer");
+
+    const updated = await readState(statePath);
+    expect(updated.phase.prepare.status).toBe("pending");
+    expect(updated.phase.render.status).toBe("pending");
+    expect(updated.phase.publish.status).toBe("pending");
+    expect(updated.phase.current).toBe("prepare");
+    expect(updated.mode).toBe("active");
+    expect(updated.content_review.status).toBe("unchecked");
+    expect(updated.redo_hint).toBe("writer");
+  });
+
+  test("mode=render keeps prepare=done but resets render and publish", async () => {
+    const workspace = await makeTempDir("zzhub-reset-render-");
+    const statePath = join(workspace, "state.json");
+
+    const state = defaultState();
+    state.workspace_root = workspace;
+    state.state_path = statePath;
+    state.run_id = "run-reset-render";
+    state.phase.prepare = { status: "done", error: null };
+    state.phase.render = { status: "done", error: null };
+    state.phase.publish = { status: "done", error: null };
+    state.phase.current = "done";
+    await writeState(statePath, state);
+
+    await captureJsonOutput(() => reset(["--state", statePath, "--mode", "render"]));
+
+    const updated = await readState(statePath);
+    expect(updated.phase.prepare.status).toBe("done");
+    expect(updated.phase.render.status).toBe("pending");
+    expect(updated.phase.publish.status).toBe("pending");
+    expect(updated.phase.current).toBe("render");
+    expect(updated.mode).toBe("active");
+    expect(updated.redo_hint).toBeNull();
+  });
+
+  test("mode=redo.style sets redo_hint to style", async () => {
+    const workspace = await makeTempDir("zzhub-reset-redo-");
+    const statePath = join(workspace, "state.json");
+
+    const state = defaultState();
+    state.workspace_root = workspace;
+    state.state_path = statePath;
+    state.run_id = "run-reset-redo";
+    state.phase.prepare = { status: "done", error: null };
+    state.phase.render = { status: "done", error: null };
+    await writeState(statePath, state);
+
+    const output = await captureJsonOutput<{ start_step: string | null }>(() =>
+      reset(["--state", statePath, "--mode", "redo.style"]),
+    );
+
+    expect(output.start_step).toBe("style");
+
+    const updated = await readState(statePath);
+    expect(updated.redo_hint).toBe("style");
+    expect(updated.phase.prepare.status).toBe("pending");
+    expect(updated.phase.render.status).toBe("pending");
+    expect(updated.phase.publish.status).toBe("pending");
+    expect(updated.phase.current).toBe("prepare");
+  });
+
+  test("mode=full marks state as failed", async () => {
+    const workspace = await makeTempDir("zzhub-reset-full-");
+    const statePath = join(workspace, "state.json");
+
+    const state = defaultState();
+    state.workspace_root = workspace;
+    state.state_path = statePath;
+    state.run_id = "run-reset-full";
+    state.phase.prepare = { status: "done", error: null };
+    await writeState(statePath, state);
+
+    await captureJsonOutput(() => reset(["--state", statePath, "--mode", "full"]));
+
+    const updated = await readState(statePath);
+    expect(updated.mode).toBe("failed");
+    expect(updated.phase.current).toBe("failed");
+    expect(updated.content_review.status).toBe("unchecked");
+    expect(updated.redo_hint).toBeNull();
+  });
+
+  test("invalid mode throws descriptive error", async () => {
+    const workspace = await makeTempDir("zzhub-reset-invalid-");
+    const statePath = join(workspace, "state.json");
+
+    const state = defaultState();
+    state.workspace_root = workspace;
+    state.state_path = statePath;
+    await writeState(statePath, state);
+
+    expect(
+      reset(["--state", statePath, "--mode", "bogus"]),
+    ).rejects.toThrow("Invalid reset mode: bogus");
+  });
+});