@zzclub/pipeline 0.9.0 → 0.10.0

package/src/commands/prepare.ts

@@ -25,17 +25,19 @@
  */
 
 import { copyFile, mkdir, readFile, writeFile } from "fs/promises";
-import { extname, join, resolve } from "path";
+import { dirname, extname, join, resolve } from "path";
 import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
 import { printResult, renderPrepare } from "../output";
 import { resolveWorkspacePaths } from "../config";
 import {
   defaultBodyInputs,
-  readState,
+  readResolvedState,
+  reenterPrepare,
   writeState,
 } from "../state";
 import { resolveFullRoute } from "../routes";
 import { resolveAuthoring, hasStyleRequest } from "../profiles";
+import { parseAccountName, parseRoutePrimary } from "../publish-targets";
 import {
   formatArticle,
   generateSlug,
@@ -106,11 +108,13 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const bodyPath = optionalArg(parsed, "body");
   const titleOverride = optionalArg(parsed, "title");
-  const accountOverride = optionalArg(parsed, "account");
-  const routeOverride = optionalArg(parsed, "route") as RoutePrimary | undefined;
+  const accountRaw = optionalArg(parsed, "account");
+  const accountOverride = accountRaw ? parseAccountName(accountRaw) : undefined;
+  const routeRaw = optionalArg(parsed, "route");
+  const routeOverride = routeRaw ? parseRoutePrimary(routeRaw) : undefined;
   const extrasRaw = optionalArg(parsed, "extras");
   const isStyleRequest = flagArg(parsed, "style-request");
   const bodyOutPath = optionalArg(parsed, "body-out");
@@ -122,11 +126,13 @@ Options:
     : undefined;
 
   const extras = extrasRaw
-    ? (extrasRaw.split(",").map((s) => s.trim()) as RoutePrimary[])
+    ? extrasRaw.split(",").map((value) => parseRoutePrimary(value.trim(), "extra route"))
     : undefined;
 
   // Read state and body
-  const state = await readState(statePath);
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
   const intentText = optionalArg(parsed, "intent-text") ?? state.intent.intent_text ?? "";
   const resolvedBodyPath = bodyPath
     ? await stageManagedBodyFile(state.workspace_root, state.run_id, bodyPath)
@@ -136,6 +142,13 @@ Options:
   }
   const bodyRaw = await readFile(resolvedBodyPath, "utf-8");
   const cleanBody = stripFrontmatter(bodyRaw);
+  reenterPrepare(state, {
+    redoHint: state.redo_hint,
+    resetReview: Boolean(bodyPath),
+  });
+  if (bodyPath && state.handoff.review_policy === "trust_user") {
+    state.content_review = { status: "passed", feedback: null };
+  }
   state.source_body_path = resolvedBodyPath;
   state.intent.intent_text = intentText || state.intent.intent_text;
 
@@ -151,7 +164,7 @@ Options:
     : resolveFullRoute(intentText, {
         primary: routeOverride,
         extras,
-        account: accountOverride,
+        account: accountOverride ?? (state.route?.account || undefined),
         contentForm: state.intent.content_form,
         targets: state.intent.targets,
       });
@@ -215,6 +228,9 @@ Options:
       break;
     }
   }
+  if (!title) {
+    throw new Error("Unable to derive a title from an empty body. Pass --title explicitly.");
+  }
 
   // Prefer editor-supplied slug; sanitize it defensively, then fall back to auto-generate
   const slug = suggestedSlug
@@ -224,11 +240,16 @@ Options:
         .replace(/^-+|-+$/g, "")
         .slice(0, 80) || generateSlug(title)
     : generateSlug(title);
-  const date = todayDate();
+  const date = state.asset_path && state.metadata.date
+    ? state.metadata.date
+    : todayDate();
 
   // Description: required for wechat-article, optional otherwise
   let description: string | null = null;
-  if (route.primary === "wechat-article") {
+  if (
+    route.primary === "wechat-article" ||
+    route.extras.includes("wechat-article")
+  ) {
     description = extractDescription(bodyFormatted);
   }
 
@@ -252,7 +273,7 @@ Options:
     route.extras.includes("wechat-newspic");
 
   if (needsArticleInputs) {
-    const markers = findIllustrationMarkers(cleanBody);
+    const markers = [...new Set(findIllustrationMarkers(cleanBody))];
     if (markers.length > 0) {
       const previousInputs =
         state.images.body_inputs.scope === "article"
@@ -279,18 +300,24 @@ Options:
     state.images.body_inputs = defaultBodyInputs();
   }
 
-  // ── Write state ──
+  if (
+    state.redo_hint === "format" ||
+    state.redo_hint === "asset-meta" ||
+    state.redo_hint === "channel-route"
+  ) {
+    state.redo_hint = null;
+  }
+
+  // Commit the formatted artifact before state starts pointing at it.
   state.formatted_body_path =
     bodyOutPath ?? getManagedFormattedBodyPath(state.workspace_root, state.run_id);
-  await writeState(statePath, state);
-
-  // ── Output formatted body ──
   const formattedBodyPath = state.formatted_body_path;
-  await mkdir(join(resolveWorkspacePaths(state.workspace_root).tempRoot, state.run_id), { recursive: true });
+  await mkdir(dirname(formattedBodyPath), { recursive: true });
   await writeFile(formattedBodyPath, bodyFormatted, "utf-8");
+  await writeState(statePath, state);
 
   // Output summary for orchestrator
-  const illustrationMarkers = findIllustrationMarkers(cleanBody);
+  const illustrationMarkers = [...new Set(findIllustrationMarkers(cleanBody))];
   const output = {
     state_path: statePath,
     route: {

package/src/commands/publish.ts

@@ -17,13 +17,23 @@ import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
 import { printResult, renderPublish } from "../output";
 import { loadConfig, resolveWorkspacePaths } from "../config";
 import {
-  readState,
+  acquireStateOperationLock,
+  readResolvedState,
   validateForPhase,
   writeState,
   type PublishTarget,
   type RoutePrimary,
 } from "../state";
-import { executePublishTargets } from "../providers/publish-core";
+import {
+  getStatePublishTargets,
+  parseRoutePrimary,
+  validatePublishTargetCompatibility,
+} from "../publish-targets";
+import {
+  executePublishTargets,
+  upsertPublishResult,
+} from "../providers/publish-core";
+import { reconcileStateArtifacts } from "../workflow-materials";
 
 export async function publish(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
@@ -40,36 +50,52 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
-  const routeOverride = optionalArg(parsed, "route") as RoutePrimary | undefined;
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
+  const routeRaw = optionalArg(parsed, "route");
+  const routeOverride: RoutePrimary | undefined = routeRaw
+    ? parseRoutePrimary(routeRaw)
+    : undefined;
   const dryRun = flagArg(parsed, "dry-run");
 
-  const state = await readState(statePath);
+  const initialResolved = await readResolvedState(requestedStatePath);
+  const releaseOperationLock = await acquireStateOperationLock(initialResolved.path);
+  try {
+  const resolved = await readResolvedState(initialResolved.path);
+  const statePath = resolved.path;
+  const state = resolved.state;
+  await reconcileStateArtifacts(state);
   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("; ")}`,
-    );
-  }
 
   // Determine targets
   let targets: PublishTarget[];
   if (routeOverride) {
     targets = [{ route: routeOverride, account: state.route.account }];
-  } else if (state.publish_targets.length > 0) {
-    targets = state.publish_targets;
   } else {
-    // Derive from route (backward compat)
-    targets = [{ route: state.route.primary, account: state.route.account }];
-    for (const extra of state.route.extras) {
-      targets.push({ route: extra, account: state.route.account });
-    }
+    targets = getStatePublishTargets(state);
+  }
+  validatePublishTargetCompatibility(targets, state.intent.content_form);
+  const validationState = {
+    ...state,
+    state_path: state.state_path || statePath,
+    publish_targets: targets,
+  };
+  const validationErrors = validateForPhase(validationState, "publish");
+  if (validationErrors.length > 0) {
+    throw new Error(
+      `Publish validation failed: ${validationErrors.map((item) => `${item.field}: ${item.message}`).join("; ")}`,
+    );
+  }
+
+  const wechatTargets = targets.filter((target) => target.route.startsWith("wechat-"));
+  if (state.intent.existing_draft_media_id && wechatTargets.length > 1) {
+    throw new Error(
+      "existing_draft_media_id can only be used with one WeChat publish target",
+    );
   }
 
   const { results, errors } = await executePublishTargets({
@@ -78,18 +104,23 @@ Options:
     dryRun,
     config,
     workspacePaths,
+    onResult: dryRun
+      ? undefined
+      : async (result) => {
+          upsertPublishResult(state, result);
+          await writeState(statePath, state);
+        },
   });
 
-  // Upsert results into state
-  for (const result of results) {
-    const idx = state.publish.results.findIndex(
-      (r) => r.route === result.route && r.account === result.account,
-    );
-    if (idx >= 0) {
-      state.publish.results[idx] = result;
-    } else {
-      state.publish.results.push(result);
-    }
+  if (dryRun) {
+    printResult({
+      publish_results: results,
+      mode: state.mode,
+      phase: state.phase.current,
+      dry_run: true,
+      ...(errors.length > 0 ? { errors } : {}),
+    }, renderPublish);
+    return;
   }
 
   // Check if all targets are done
@@ -97,7 +128,7 @@ Options:
     const r = state.publish.results.find(
       (x) => x.route === target.route && x.account === target.account,
     );
-    return r && (r.status === "success" || r.status === "skipped");
+    return r?.status === "success";
   });
 
   if (allDone) {
@@ -121,4 +152,7 @@ Options:
     output.errors = errors;
   }
   printResult(output, renderPublish);
+  } finally {
+    await releaseOperationLock();
+  }
 }

package/src/commands/reconcile.ts

@@ -1,6 +1,6 @@
 import { parseArgs, requireArg } from "../args";
 import { printResult, renderTaskShape } from "../output";
-import { readState, writeState } from "../state";
+import { readResolvedState, writeState } from "../state";
 import { getTaskByStatePath } from "../task-manager";
 import { reconcileStateArtifacts } from "../workflow-materials";
 
@@ -17,8 +17,10 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
-  const state = await readState(statePath);
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
   await reconcileStateArtifacts(state);
   await writeState(statePath, state);
 

package/src/commands/render.ts

@@ -14,7 +14,7 @@
  * Output: Updated state with images.plan, images.render_assets
  */
 
-import { readFile } from "fs/promises";
+import { access, readFile } from "fs/promises";
 import { join } from "path";
 
 import { parseArgs, requireArg, flagArg } from "../args";
@@ -22,11 +22,14 @@ import { printResult, renderRender } from "../output";
 import { loadConfig } from "../config";
 import { resolveImageRenderer } from "../adapter-loader";
 import {
+  acquireStateOperationLock,
   defaultBodyInputs,
   normalizeNewspicRenderSpec,
-  readState,
+  readResolvedState,
+  validateForPhase,
   writeState,
   type NewspicRenderSpec,
+  type WorkflowState,
 } from "../state";
 import {
   stripFrontmatter,
@@ -35,7 +38,7 @@ import {
 import { getLongformTheme } from "../routes";
 import { collectNewspicRequiredMarkers } from "../workflow-materials";
 
-function getNewspicRenderSpec(state: Awaited<ReturnType<typeof readState>>): NewspicRenderSpec {
+function getNewspicRenderSpec(state: WorkflowState): NewspicRenderSpec {
   const spec = normalizeNewspicRenderSpec(state.intent.newspic_render);
   return {
     ...spec,
@@ -57,14 +60,22 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const skipRender = flagArg(parsed, "skip-render");
 
-  const state = await readState(statePath);
+  const initialResolved = await readResolvedState(requestedStatePath);
+  const releaseOperationLock = await acquireStateOperationLock(initialResolved.path);
+  try {
+  const resolved = await readResolvedState(initialResolved.path);
+  const statePath = resolved.path;
+  const state = resolved.state;
 
   // Validate prerequisites
-  if (!state.asset_path) {
-    throw new Error("asset_path not set. Run prepare-finalize first.");
+  const validationErrors = validateForPhase(state, "render");
+  if (validationErrors.length > 0) {
+    throw new Error(
+      `Render validation failed: ${validationErrors.map((item) => `${item.field}: ${item.message}`).join("; ")}`,
+    );
   }
 
   const postPath = join(state.asset_path, "post.md");
@@ -89,6 +100,8 @@ Options:
     state.images.render_assets = [];
     state.phase.render = { status: "done", error: null };
     state.phase.current = state.intent.requires.publish ? "publish" : "done";
+    state.mode = state.phase.current === "done" ? "done" : "active";
+    state.redo_hint = null;
     await writeState(statePath, state);
     printResult({
       plan: state.images.plan,
@@ -224,21 +237,49 @@ Options:
     theme: routePrimary === "wechat-newspic" ? getLongformTheme(state.route.account) : undefined,
     template,
   });
+  const routeAssets = renderResult.assets.filter(
+    (asset) => asset.route === routePrimary && asset.path.trim().length > 0,
+  );
+  if (routeAssets.length === 0) {
+    throw new Error(
+      `Image renderer '${imageRenderer.name}' returned no assets for ${routePrimary}`,
+    );
+  }
+  if (
+    routePrimary === "wechat-article" &&
+    !routeAssets.some((asset) => asset.kind === "cover")
+  ) {
+    throw new Error(
+      `Image renderer '${imageRenderer.name}' did not return a WeChat article cover`,
+    );
+  }
+  for (const asset of routeAssets) {
+    await access(asset.path).catch(() => {
+      throw new Error(
+        `Image renderer '${imageRenderer.name}' returned a missing asset: ${asset.path}`,
+      );
+    });
+  }
 
   // ── Update state ────────────────────────────────────────────────
 
-  state.images.render_assets = renderResult.assets;
+  state.images.render_assets = routeAssets;
   state.images.plan.status = "rendered";
   state.phase.render = { status: "done", error: null };
   state.phase.current = state.intent.requires.publish ? "publish" : "done";
+  state.mode = state.phase.current === "done" ? "done" : "active";
+  state.redo_hint = null;
   state.artifacts.render_version += 1;
 
   await writeState(statePath, state);
 
   printResult({
     plan: state.images.plan,
-    render_assets: renderResult.assets,
+    render_assets: routeAssets,
     render_version: state.artifacts.render_version,
     phase: state.phase.current,
   }, renderRender);
+  } finally {
+    await releaseOperationLock();
+  }
 }

package/src/commands/republish.ts

@@ -18,12 +18,24 @@ import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
 import { printResult } from "../output";
 import { loadConfig, resolveWorkspacePaths } from "../config";
 import {
-  readState,
+  acquireStateOperationLock,
+  readResolvedState,
+  validateForPhase,
   writeState,
   type PublishTarget,
-  type RoutePrimary,
 } from "../state";
-import { executePublishTargets } from "../providers/publish-core";
+import {
+  getStatePublishTargets,
+  parseAccountName,
+  parseRoutePrimary,
+  validatePublishTargetCompatibility,
+} from "../publish-targets";
+import {
+  dedupeTargets,
+  executePublishTargets,
+  upsertPublishResult,
+} from "../providers/publish-core";
+import { reconcileStateArtifacts } from "../workflow-materials";
 
 export async function republish(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
@@ -54,12 +66,19 @@ Examples:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
-  const accountArg = optionalArg(parsed, "account");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
+  const accountRaw = optionalArg(parsed, "account");
+  const accountArg = accountRaw ? parseAccountName(accountRaw) : undefined;
   const targetsArg = optionalArg(parsed, "targets");
   const dryRun = flagArg(parsed, "dry-run");
 
-  const state = await readState(statePath);
+  const initialResolved = await readResolvedState(requestedStatePath);
+  const releaseOperationLock = await acquireStateOperationLock(initialResolved.path);
+  try {
+  const resolved = await readResolvedState(initialResolved.path);
+  const statePath = resolved.path;
+  const state = resolved.state;
+  await reconcileStateArtifacts(state);
   const config = loadConfig();
   const workspacePaths = resolveWorkspacePaths(state.workspace_root, config);
 
@@ -88,14 +107,14 @@ Examples:
     for (const part of parts) {
       const atIdx = part.indexOf("@");
       if (atIdx !== -1) {
-        const route = part.slice(0, atIdx).trim() as RoutePrimary;
-        const account = part.slice(atIdx + 1).trim();
+        const route = parseRoutePrimary(part.slice(0, atIdx).trim());
+        const account = parseAccountName(part.slice(atIdx + 1), `account in target '${part}'`);
         newTargets.push({ route, account });
       } else {
         // No @: use state.route.primary as route, part as account
         newTargets.push({
           route: state.route.primary,
-          account: part.trim(),
+          account: parseAccountName(part, "target account"),
         });
       }
     }
@@ -104,9 +123,40 @@ Examples:
   if (newTargets.length === 0) {
     throw new Error("No targets specified. Use --account or --targets.");
   }
+  if (
+    state.intent.existing_draft_media_id &&
+    newTargets.some((target) =>
+      target.route.startsWith("wechat-") &&
+      (target.route !== state.route.primary || target.account !== state.route.account))
+  ) {
+    throw new Error(
+      "existing_draft_media_id cannot be republished to a different WeChat target",
+    );
+  }
 
-  // Append to publish_targets (dedupe handled by executePublishTargets)
-  state.publish_targets = [...state.publish_targets, ...newTargets];
+  const mergedTargets = dedupeTargets([
+    ...getStatePublishTargets(state),
+    ...newTargets,
+  ]);
+  validatePublishTargetCompatibility(mergedTargets, state.intent.content_form);
+  const validationErrors = validateForPhase(
+    {
+      ...state,
+      state_path: state.state_path || statePath,
+      publish_targets: mergedTargets,
+    },
+    "publish",
+  );
+  if (validationErrors.length > 0) {
+    throw new Error(
+      `Republish validation failed: ${validationErrors.map((item) => `${item.field}: ${item.message}`).join("; ")}`,
+    );
+  }
+
+  if (!dryRun) {
+    state.publish_targets = mergedTargets;
+    await writeState(statePath, state);
+  }
 
   // Execute (executePublishTargets handles dedupe and idempotent filter)
   const { results, errors } = await executePublishTargets({
@@ -115,32 +165,25 @@ Examples:
     dryRun,
     config,
     workspacePaths,
+    onResult: dryRun
+      ? undefined
+      : async (result) => {
+          upsertPublishResult(state, result);
+          await writeState(statePath, state);
+        },
   });
 
-  // Upsert results
-  for (const result of results) {
-    const idx = state.publish.results.findIndex(
-      (r) => r.route === result.route && r.account === result.account,
-    );
-    if (idx >= 0) {
-      state.publish.results[idx] = result;
-    } else {
-      state.publish.results.push(result);
-    }
-  }
-
-  // Mode stays done (or whatever it was)
-  state.updated_at = new Date().toISOString();
-
-  await writeState(statePath, state);
-
-  const output: any = {
-    publish_results: state.publish.results,
+  const output: Record<string, unknown> = {
+    publish_results: dryRun ? results : state.publish.results,
     mode: state.mode,
     new_targets: newTargets,
+    ...(dryRun ? { dry_run: true } : {}),
   };
   if (errors.length > 0) {
     output.errors = errors;
   }
   printResult(output);
+  } finally {
+    await releaseOperationLock();
+  }
 }

package/src/commands/reset.test.ts

@@ -5,6 +5,7 @@ import { tmpdir } from "os";
 
 import { reset } from "./reset";
 import { defaultState, readState, writeState } from "../state";
+import { getTaskByStatePath } from "../task-manager";
 
 const TEST_CONFIG_PATH = join(tmpdir(), `zzhub-pipeline-test-config-reset-${process.pid}.json`);
 process.env.ZZHUB_PIPELINE_CONFIG = TEST_CONFIG_PATH;
@@ -45,6 +46,8 @@ describe("reset", () => {
     state.phase.publish = { status: "done", error: null };
     state.phase.current = "done";
     state.content_review = { status: "passed", feedback: null };
+    state.source_body_path = join(workspace, "source.md");
+    await writeFile(state.source_body_path, "Existing body", "utf-8");
     await writeState(statePath, state);
 
     const output = await captureJsonOutput<{ reset_mode: string; start_step: string | null }>(() =>
@@ -62,6 +65,7 @@ describe("reset", () => {
     expect(updated.mode).toBe("active");
     expect(updated.content_review.status).toBe("unchecked");
     expect(updated.redo_hint).toBe("writer");
+    expect((await getTaskByStatePath(statePath)).next_action.action).toBe("revise-content");
   });
 
   test("mode=render keeps prepare=done but resets render and publish", async () => {
@@ -148,4 +152,43 @@ describe("reset", () => {
       reset(["--state", statePath, "--mode", "bogus"]),
     ).rejects.toThrow("Invalid reset mode: bogus");
   });
+
+  test("mode=publish clears current-version success so publish can run again", async () => {
+    const workspace = await makeTempDir("zzhub-reset-publish-");
+    const statePath = join(workspace, "state.json");
+    const state = defaultState();
+    state.workspace_root = workspace;
+    state.state_path = statePath;
+    state.run_id = "run-reset-publish";
+    state.artifacts.content_version = 3;
+    state.artifacts.render_version = 2;
+    state.publish.results = [
+      {
+        route: "wechat-article",
+        account: "default",
+        status: "success",
+        detail: null,
+        published_at: "2026-07-12T00:00:00.000Z",
+        content_version: 3,
+        render_version: 2,
+      },
+      {
+        route: "blog",
+        account: "default",
+        status: "success",
+        detail: null,
+        published_at: "2026-07-11T00:00:00.000Z",
+        content_version: 2,
+        render_version: 2,
+      },
+    ];
+    await writeState(statePath, state);
+
+    await captureJsonOutput(() => reset(["--state", statePath, "--mode", "publish"]));
+
+    const updated = await readState(statePath);
+    expect(updated.publish.results).toHaveLength(1);
+    expect(updated.publish.results[0]?.route).toBe("blog");
+    expect(updated.phase.current).toBe("publish");
+  });
 });