@zzclub/pipeline 0.9.0 → 0.10.0

package/src/commands/reset.ts

@@ -21,7 +21,14 @@
 
 import { parseArgs, requireArg } from "../args";
 import { printResult, renderReset } from "../output";
-import { readState, writeState, defaultContentReview } from "../state";
+import {
+  defaultContentReview,
+  readResolvedState,
+  reenterPrepare,
+  reenterPublish,
+  reenterRender,
+  writeState,
+} from "../state";
 
 type ResetMode =
   | "content"
@@ -68,7 +75,7 @@ Modes:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const mode = requireArg(parsed, "mode", "reset mode") as ResetMode;
 
   if (!VALID_MODES.includes(mode)) {
@@ -77,7 +84,9 @@ Modes:
     );
   }
 
-  const state = await readState(statePath);
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
 
   switch (mode) {
     case "content":
@@ -85,14 +94,10 @@ Modes:
     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 =
+      reenterPrepare(state, {
+        clearFormattedBody: mode === "content",
+        resetReview: mode === "content" || mode === "redo.style",
+        redoHint:
         mode === "redo.style"
           ? "style"
           : mode === "redo.format"
@@ -101,33 +106,21 @@ Modes:
               ? "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();
-      }
+                : "writer",
+      });
       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";
-      }
+      reenterRender(state);
       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
+      reenterPublish(state);
+      state.publish.results = state.publish.results.filter(
+        (result) =>
+          result.content_version !== state.artifacts.content_version ||
+          result.render_version !== state.artifacts.render_version,
+      );
       break;
 
     case "full":

package/src/commands/review.ts

@@ -17,7 +17,7 @@
 
 import { parseArgs, requireArg, optionalArg } from "../args";
 import { printResult, renderReview } from "../output";
-import { readState, writeState, type ContentReviewStatus } from "../state";
+import { readResolvedState, writeState, type ContentReviewStatus } from "../state";
 
 const VALID_STATUSES: ContentReviewStatus[] = [
   "passed",
@@ -43,7 +43,7 @@ Statuses:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const status = requireArg(parsed, "status", "review status") as ContentReviewStatus;
   const feedback = optionalArg(parsed, "feedback") ?? null;
 
@@ -59,7 +59,9 @@ Statuses:
     );
   }
 
-  const state = await readState(statePath);
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
 
   state.content_review = {
     status,

package/src/commands/sync-blog.ts

@@ -1,7 +1,11 @@
 import { parseArgs, requireArg, flagArg } from "../args";
 import { printResult, renderSyncBlog } from "../output";
 import { loadConfig, resolveWorkspacePaths } from "../config";
-import { readState, updateState } from "../state";
+import {
+  acquireStateOperationLock,
+  readResolvedState,
+  updateState,
+} from "../state";
 import { publishBlogRoute } from "../providers/blog";
 
 export async function syncBlog(args: string[]): Promise<void> {
@@ -18,13 +22,18 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const dryRun = flagArg(parsed, "dry-run");
 
   const config = loadConfig();
 
   // Run the actual publish (may have network side effects)
-  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;
 
   if (!state.asset_path) {
     throw new Error("asset_path not set. Run prepare-finalize first.");
@@ -38,6 +47,11 @@ Options:
     workspacePaths,
   });
 
+  if (dryRun) {
+    printResult({ ...result, mode: state.mode }, renderSyncBlog);
+    return;
+  }
+
   // Write result back to state
   const finalState = await updateState(statePath, (s) => {
     const idx = s.publish.results.findIndex((r) => r.route === "blog");
@@ -52,4 +66,7 @@ Options:
     ...result,
     mode: finalState.mode,
   }, renderSyncBlog);
+  } finally {
+    await releaseOperationLock();
+  }
 }

package/src/providers/blog.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from "bun:test";
 import { join } from "path";
-import { extractLocalImagePaths, replaceLocalImagePaths } from "./blog";
+import {
+  extractLocalImagePaths,
+  replaceLocalImagePaths,
+  resolveBlogPostPath,
+} from "./blog";
 
 describe("extractLocalImagePaths", () => {
   test("extracts local image paths from markdown", () => {
@@ -17,6 +21,22 @@ describe("extractLocalImagePaths", () => {
     expect(pathMap.has("./local.png")).toBe(true);
   });
 
+  test("skips non-file URI schemes", () => {
+    const content = "![inline](data:image/png;base64,abc)\n![blob](blob:https://example.com/id)";
+    expect(extractLocalImagePaths(content, "/workspace").size).toBe(0);
+  });
+
+  test("rejects paths that escape the canonical asset directory", () => {
+    expect(() => extractLocalImagePaths("![secret](../secret.png)", "/workspace/post"))
+      .toThrow("escapes asset directory");
+  });
+
+  test("handles angle-bracket paths and markdown titles", () => {
+    const content = '![cover](<images/my cover.png> "Cover")';
+    const pathMap = extractLocalImagePaths(content, "/workspace");
+    expect(pathMap.get("images/my cover.png")).toBe("/workspace/images/my cover.png");
+  });
+
   test("returns empty map for no images", () => {
     expect(extractLocalImagePaths("just text", "/workspace").size).toBe(0);
   });
@@ -56,3 +76,19 @@ describe("replaceLocalImagePaths", () => {
     expect(result).toBe("![my alt text](https://cdn.com/img.png)");
   });
 });
+
+describe("resolveBlogPostPath", () => {
+  test("builds the canonical dated blog path", () => {
+    expect(resolveBlogPostPath("/blog", "2026-07-12", "safe-slug")).toEqual({
+      directory: join("/blog", "content", "nezus", "2026", "07"),
+      path: join("/blog", "content", "nezus", "2026", "07", "safe-slug.md"),
+    });
+  });
+
+  test("rejects traversal in date or slug fields", () => {
+    expect(() => resolveBlogPostPath("/blog", "../../tmp", "safe"))
+      .toThrow("Invalid blog publish date");
+    expect(() => resolveBlogPostPath("/blog", "2026-07-12", "../../secret"))
+      .toThrow("Invalid blog publish slug");
+  });
+});

package/src/providers/blog.ts

@@ -1,5 +1,5 @@
 import { mkdir, readFile, writeFile } from "fs/promises";
-import { join, resolve } from "path";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
 import { PipelineConfig, ResolvedWorkspacePaths } from "../config";
 import { spawnSync } from "../spawn";
 import { PublishResult, WorkflowState } from "../state";
@@ -13,25 +13,63 @@ interface BlogPublishContext {
   workspacePaths: ResolvedWorkspacePaths;
 }
 
-// ![alt](path) — skips http(s):// URLs, captures [1]=alt [2]=rawPath
-const LOCAL_IMAGE_RE = /!\[([^\]]*)\]\((?!https?:\/\/)([^)]+)\)/g;
+const LOCAL_IMAGE_RE = /!\[([^\]]*)\]\((?![a-zA-Z][a-zA-Z0-9+.-]*:|\/\/)(?:<([^>]+)>|([^\s)]+))(?:\s+"[^"]*")?\)/g;
 
 export function extractLocalImagePaths(content: string, assetPath: string): Map<string, string> {
   const pathMap = new Map<string, string>();
   for (const match of content.matchAll(LOCAL_IMAGE_RE)) {
-    const rawPath = match[2].trim();
-    pathMap.set(rawPath, resolve(assetPath, rawPath));
+    const rawPath = (match[2] ?? match[3] ?? "").trim();
+    const assetRoot = resolve(assetPath);
+    const absolutePath = resolve(assetRoot, rawPath);
+    const relativePath = relative(assetRoot, absolutePath);
+    if (
+      relativePath === ".." ||
+      relativePath.startsWith(`..${/\\/.test(relativePath) ? "\\" : "/"}`) ||
+      isAbsolute(relativePath)
+    ) {
+      throw new Error(`Local blog image escapes asset directory: ${rawPath}`);
+    }
+    pathMap.set(rawPath, absolutePath);
   }
   return pathMap;
 }
 
 export function replaceLocalImagePaths(content: string, urlMap: Map<string, string>): string {
-  return content.replace(LOCAL_IMAGE_RE, (original, alt: string, rawPath: string) => {
-    const url = urlMap.get(rawPath.trim());
+  return content.replace(LOCAL_IMAGE_RE, (original, alt: string, anglePath: string, barePath: string) => {
+    const rawPath = (anglePath ?? barePath ?? "").trim();
+    const url = urlMap.get(rawPath);
     return url ? `![${alt}](${url})` : original;
   });
 }
 
+export function resolveBlogPostPath(
+  blogRoot: string,
+  date: string,
+  slug: string,
+): { directory: string; path: string } {
+  const dateMatch = date.match(/^(\d{4})-(\d{2})-\d{2}$/);
+  if (!dateMatch) {
+    throw new Error(`Invalid blog publish date: ${date}`);
+  }
+  if (!slug || /[\\/]/.test(slug) || slug === "." || slug === "..") {
+    throw new Error(`Invalid blog publish slug: ${slug}`);
+  }
+
+  const contentRoot = resolve(blogRoot, "content", "nezus");
+  const directory = resolve(contentRoot, dateMatch[1], dateMatch[2]);
+  const path = resolve(directory, `${slug}.md`);
+  const relativePath = relative(contentRoot, path);
+  if (
+    dirname(path) !== directory ||
+    relativePath === ".." ||
+    relativePath.startsWith(`..${/\\/.test(relativePath) ? "\\" : "/"}`) ||
+    isAbsolute(relativePath)
+  ) {
+    throw new Error(`Blog post path escapes content directory: ${date}/${slug}`);
+  }
+  return { directory, path };
+}
+
 async function uploadBlogImages(
   content: string,
   assetPath: string,
@@ -45,7 +83,7 @@ async function uploadBlogImages(
   }
 
   const cosPat = config.cos.pat;
-  if (!cosPat) {
+  if (!cosPat && !dryRun) {
     throw new Error("No COS PAT configured. Set cos.pat in config.");
   }
 
@@ -84,12 +122,12 @@ export async function publishBlogRoute({
 }: BlogPublishContext): Promise<PublishResult> {
   const postPath = join(state.asset_path, "post.md");
   const postContent = await readFile(postPath, "utf-8");
-  const category = "nezus";
   const blogRoot = workspacePaths.blogRoot;
-
-  const [year, month] = state.metadata.date.split("-");
-  const blogPostDir = join(blogRoot, "content", category, year, month);
-  const blogPostPath = join(blogPostDir, `${state.metadata.slug}.md`);
+  const { directory: blogPostDir, path: blogPostPath } = resolveBlogPostPath(
+    blogRoot,
+    state.metadata.date,
+    state.metadata.slug,
+  );
 
   const lines = ["---"];
   lines.push(`title: "${state.metadata.title.replace(/"/g, '\\"')}"`);

package/src/providers/cos.ts

@@ -90,28 +90,32 @@ async function requestSts(
   )) as StsApiResponse;
 
   const d = response?.data;
-  if (
-    !d?.TmpSecretId ||
-    !d?.TmpSecretKey ||
-    !d?.SessionToken ||
-    !d?.Bucket ||
-    !d?.Region ||
-    !d?.Key ||
-    d.StartTime === undefined ||
-    d.ExpiredTime === undefined
-  ) {
-    throw new Error(`COS STS response incomplete: ${JSON.stringify(response)}`);
+  const missing = [
+    ["TmpSecretId", d?.TmpSecretId],
+    ["TmpSecretKey", d?.TmpSecretKey],
+    ["SessionToken", d?.SessionToken],
+    ["Bucket", d?.Bucket],
+    ["Region", d?.Region],
+    ["Key", d?.Key],
+    ["StartTime", d?.StartTime],
+    ["ExpiredTime", d?.ExpiredTime],
+  ].filter(([, value]) => value === undefined || value === null || value === "");
+  if (missing.length > 0) {
+    throw new Error(
+      `COS STS response incomplete; missing: ${missing.map(([field]) => field).join(", ")}`,
+    );
   }
+  const data = d as Required<NonNullable<StsApiResponse["data"]>>;
 
   return {
-    TmpSecretId: d.TmpSecretId,
-    TmpSecretKey: d.TmpSecretKey,
-    SessionToken: d.SessionToken,
-    StartTime: d.StartTime,
-    ExpiredTime: d.ExpiredTime,
-    Bucket: d.Bucket,
-    Region: d.Region,
-    Key: d.Key,
+    TmpSecretId: data.TmpSecretId,
+    TmpSecretKey: data.TmpSecretKey,
+    SessionToken: data.SessionToken,
+    StartTime: data.StartTime,
+    ExpiredTime: data.ExpiredTime,
+    Bucket: data.Bucket,
+    Region: data.Region,
+    Key: data.Key,
   };
 }
 

package/src/providers/index.ts

@@ -47,7 +47,9 @@ async function publishWechatArticleRoute({
       state.images.body_inputs.received,
     );
     exportPostPath = join(state.asset_path, "post-wechat-draft.md");
-    await writeFile(exportPostPath, draftContent, "utf-8");
+    if (!dryRun) {
+      await writeFile(exportPostPath, draftContent, "utf-8");
+    }
 
     for (const img of state.images.body_inputs.received) {
       photos.push(img.path);
@@ -81,7 +83,7 @@ async function publishWechatArticleRoute({
       customCss: wxAccount?.customCss ?? null,
       themeOverrides: wxAccount?.theme,
     });
-    await createWechatDraft({
+    const response = await createWechatDraft({
       account,
       title: state.metadata.title,
       html,
@@ -92,6 +94,16 @@ async function publishWechatArticleRoute({
       nezusBaseUrl: process.env.ZZHUB_WX_BASE_URL || config.wx.baseUrl,
       nezusPat: process.env.ZZCLUB_PAT || config.wx.accounts[account]?.pat || config.wx.accounts[config.wx.defaultAccount]?.pat,
     });
+    return {
+      route: "wechat-article",
+      account,
+      status: "success",
+      detail: null,
+      external_id: typeof response.draftMediaId === "string" ? response.draftMediaId : null,
+      published_at: new Date().toISOString(),
+      content_version: state.artifacts.content_version,
+      render_version: state.artifacts.render_version,
+    };
   } catch (error) {
     return {
       route: "wechat-article",
@@ -104,15 +116,6 @@ async function publishWechatArticleRoute({
     };
   }
 
-  return {
-    route: "wechat-article",
-    account,
-    status: "success",
-    detail: null,
-    published_at: new Date().toISOString(),
-    content_version: state.artifacts.content_version,
-    render_version: state.artifacts.render_version,
-  };
 }
 
 async function publishWechatNewspicRoute({
@@ -126,7 +129,9 @@ async function publishWechatNewspicRoute({
   const bodyImageUrls = extractImageUrls(postContent);
   const cleanContent = prepareBodyForNewspic(postContent);
   const cleanPath = join(state.asset_path, "post-clean.md");
-  await writeFile(cleanPath, cleanContent, "utf-8");
+  if (!dryRun) {
+    await writeFile(cleanPath, cleanContent, "utf-8");
+  }
 
   const assets = (state.images.render_assets as RenderAsset[])
     .filter((asset) => asset.route === "wechat-newspic")
@@ -156,7 +161,7 @@ async function publishWechatNewspicRoute({
   }
 
   try {
-    await createWechatNewspic({
+    const response = await createWechatNewspic({
       account,
       title: state.metadata.title,
       content: cleanContent,
@@ -167,6 +172,16 @@ async function publishWechatNewspicRoute({
       nezusBaseUrl: process.env.ZZHUB_WX_BASE_URL || config.wx.baseUrl,
       nezusPat: process.env.ZZCLUB_PAT || config.wx.accounts[account]?.pat || config.wx.accounts[config.wx.defaultAccount]?.pat,
     });
+    return {
+      route: "wechat-newspic",
+      account,
+      status: "success",
+      detail: null,
+      external_id: typeof response.draftMediaId === "string" ? response.draftMediaId : null,
+      published_at: new Date().toISOString(),
+      content_version: state.artifacts.content_version,
+      render_version: state.artifacts.render_version,
+    };
   } catch (error) {
     return {
       route: "wechat-newspic",
@@ -179,15 +194,6 @@ async function publishWechatNewspicRoute({
     };
   }
 
-  return {
-    route: "wechat-newspic",
-    account,
-    status: "success",
-    detail: null,
-    published_at: new Date().toISOString(),
-    content_version: state.artifacts.content_version,
-    render_version: state.artifacts.render_version,
-  };
 }
 
 const PUBLISH_PROVIDERS: Record<RoutePrimary, PublishProvider> = {

package/src/providers/publish-core.ts

@@ -20,6 +20,7 @@ export interface ExecutePublishTargetsParams {
   dryRun: boolean;
   config: PipelineConfig;
   workspacePaths: ResolvedWorkspacePaths;
+  onResult?: (result: PublishResult) => Promise<void>;
 }
 
 export interface ExecutePublishTargetsResult {
@@ -66,13 +67,28 @@ export function filterIdempotent(
   });
 }
 
+export function upsertPublishResult(
+  state: WorkflowState,
+  result: PublishResult,
+): void {
+  const index = state.publish.results.findIndex(
+    (item) => item.route === result.route && item.account === result.account,
+  );
+  if (index >= 0) {
+    state.publish.results[index] = result;
+  } else {
+    state.publish.results.push(result);
+  }
+}
+
 /**
- * Execute publish for a list of targets in parallel.
+ * Execute publish targets sequentially so callers can persist each outcome
+ * before the next external side effect begins.
  */
 export async function executePublishTargets(
   params: ExecutePublishTargetsParams,
 ): Promise<ExecutePublishTargetsResult> {
-  const { state, targets, dryRun, config, workspacePaths } = params;
+  const { state, targets, dryRun, config, workspacePaths, onResult } = params;
 
   const deduped = dedupeTargets(targets);
   const filtered = filterIdempotent(
@@ -85,39 +101,44 @@ export async function executePublishTargets(
   const results: PublishResult[] = [];
   const errors: PublishTargetError[] = [];
 
-  // Execute in parallel
-  const promises = filtered.map(async (target) => {
-    const provider = getPublishProvider(target.route);
-    const ctx: PublishRouteContext = {
-      state,
-      dryRun,
-      config,
-      workspacePaths,
-      accountOverride: target.account,
-    };
-
+  for (const target of filtered) {
+    let result: PublishResult;
     try {
-      const result = await provider(ctx);
-      return { result, error: null };
+      const provider = getPublishProvider(target.route);
+      const ctx: PublishRouteContext = {
+        state,
+        dryRun,
+        config,
+        workspacePaths,
+        accountOverride: target.account,
+      };
+      const providerResult = await provider(ctx);
+      result = {
+        ...providerResult,
+        route: target.route,
+        account: target.account,
+        content_version: state.artifacts.content_version,
+        render_version: state.artifacts.render_version,
+      };
     } catch (err) {
       const error: PublishTargetError = {
         route: target.route,
         account: target.account,
         error: err instanceof Error ? err.message : String(err),
       };
-      return { result: null, error };
-    }
-  });
-
-  const outcomes = await Promise.all(promises);
-
-  for (const { result, error } of outcomes) {
-    if (result) {
-      results.push(result);
-    }
-    if (error) {
+      result = {
+        route: target.route,
+        account: target.account,
+        status: "failed",
+        detail: error.error,
+        published_at: null,
+        content_version: state.artifacts.content_version,
+        render_version: state.artifacts.render_version,
+      };
       errors.push(error);
     }
+    results.push(result);
+    await onResult?.(result);
   }
 
   return { results, errors };

package/src/providers/wechat.test.ts

@@ -8,8 +8,63 @@ import {
   replaceImageUrls,
   isRetryableTokenFetchError,
   resolveFilenameFromUrl,
+  resolveDraftMediaId,
+  readResponseBodyWithLimit,
 } from "./wechat";
 
+describe("resolveDraftMediaId", () => {
+  test("extracts media_id from a successful draft response", () => {
+    expect(resolveDraftMediaId({ code: 0, data: { media_id: "media-1" } }))
+      .toBe("media-1");
+  });
+
+  test("rejects business errors returned with HTTP 200", () => {
+    expect(() => resolveDraftMediaId({ errcode: 40001, errmsg: "invalid credential" }))
+      .toThrow("WeChat draft API error: 40001");
+  });
+
+  test("rejects string business error codes for draft updates", () => {
+    expect(() => resolveDraftMediaId(
+      { errcode: "40001", errmsg: "invalid credential" },
+      "existing-media",
+    )).toThrow("WeChat draft API error: 40001");
+  });
+
+  test("requires media_id for a newly created draft", () => {
+    expect(() => resolveDraftMediaId({ code: 0, data: {} }))
+      .toThrow("did not include media_id");
+  });
+
+  test("uses the existing media id for a successful update", () => {
+    expect(resolveDraftMediaId({ errcode: 0 }, "existing-media"))
+      .toBe("existing-media");
+  });
+});
+
+describe("readResponseBodyWithLimit", () => {
+  test("accepts a streamed response at the byte limit", async () => {
+    const response = new Response(new Uint8Array([1, 2, 3]));
+    const body = await readResponseBodyWithLimit(response, 3);
+    expect(new Uint8Array(body)).toEqual(new Uint8Array([1, 2, 3]));
+  });
+
+  test("rejects a streamed response as soon as it exceeds the byte limit", async () => {
+    const response = new Response(new Uint8Array([1, 2, 3, 4]));
+    await expect(readResponseBodyWithLimit(response, 3)).rejects.toThrow(
+      "Image exceeds 3 byte limit",
+    );
+  });
+
+  test("rejects an oversized content-length before reading the body", async () => {
+    const response = new Response(new Uint8Array([1]), {
+      headers: { "content-length": "4" },
+    });
+    await expect(readResponseBodyWithLimit(response, 3)).rejects.toThrow(
+      "Image exceeds 3 byte limit",
+    );
+  });
+});
+
 describe("normalizeAccountName", () => {
   test("accepts valid account names", () => {
     expect(normalizeAccountName("default")).toBe("default");