@zzclub/pipeline 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zzclub/pipeline",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "bin": {
     "zzp": "./src/cli.ts",

package/src/adapter-loader.ts

@@ -7,6 +7,8 @@
  */
 
 import type { PipelineConfig } from "./schema/config";
+import { isAbsolute, resolve } from "path";
+import { pathToFileURL } from "url";
 import type {
   ImageRenderPlugin,
   MarkdownRenderPlugin,
@@ -49,7 +51,10 @@ function validateMarkdownRenderPlugin(plugin: unknown, specifier: string): Markd
 
 async function importPlugin(specifier: string): Promise<unknown> {
   try {
-    const mod = await import(specifier);
+    const importSpecifier = specifier.startsWith(".") || isAbsolute(specifier)
+      ? pathToFileURL(resolve(specifier)).href
+      : specifier;
+    const mod = await import(importSpecifier);
     // Support both default exports and named `plugin` exports
     return mod.default ?? mod.plugin ?? mod;
   } catch (err) {

package/src/commands/analytics.test.ts

@@ -123,11 +123,12 @@ describe("analytics commands", () => {
 
     test("filters by days", async () => {
       const statePath = join(workspace, "state.json");
+      const today = new Date().toISOString().slice(0, 10);
       await writeFile(statePath, JSON.stringify({
         run_id: "run_001",
-        metadata: { title: "Article", date: "2026-06-11" },
+        metadata: { title: "Article", date: today },
         route: { primary: "wechat-article" },
-        publish: { results: { wechat: { status: "success", published_at: "2026-06-11T10:00:00Z" } } },
+        publish: { results: { wechat: { status: "success", published_at: `${today}T10:00:00Z` } } },
       }));
 
       await recordAnalytics({ statePath, reads: 1000 });

package/src/commands/analytics.ts

@@ -1,5 +1,5 @@
 import { readFile } from "fs/promises";
-import { dirname } from "path";
+import { dirname, isAbsolute, resolve } from "path";
 import { ensureDb } from "../db";
 import { AnalyticsSchema, type Analytics } from "../schema/analytics";
 import { parseArgs, requireArg, optionalArg } from "../args";
@@ -26,10 +26,27 @@ function resolveWorkspace(statePath: string): string {
 export async function recordAnalytics(
   input: RecordAnalyticsInput,
 ): Promise<Analytics> {
-  const stateContent = await readFile(input.statePath, "utf-8");
-  const state = JSON.parse(stateContent);
+  const requestedPath = resolve(input.statePath);
+  let statePath = requestedPath;
+  let state = JSON.parse(await readFile(statePath, "utf-8"));
+  if (typeof state.state_path === "string" && state.state_path.trim()) {
+    const candidatePath = isAbsolute(state.state_path)
+      ? resolve(state.state_path)
+      : resolve(dirname(statePath), state.state_path);
+    if (candidatePath !== statePath) {
+      try {
+        state = JSON.parse(await readFile(candidatePath, "utf-8"));
+        statePath = candidatePath;
+      } catch (error) {
+        const code = error instanceof Error && "code" in error
+          ? String((error as NodeJS.ErrnoException).code)
+          : "";
+        if (code !== "ENOENT") throw error;
+      }
+    }
+  }
 
-  const workspace = resolveWorkspace(input.statePath);
+  const workspace = state.workspace_root || resolveWorkspace(statePath);
   const db = ensureDb(workspace);
 
   try {

package/src/commands/attach-body-images.ts

@@ -2,7 +2,13 @@ import { readFile } from "fs/promises";
 
 import { parseArgs, optionalArg, requireArg } from "../args";
 import { printResult, renderTaskShape } from "../output";
-import { readState, writeState, type BodyInputReceived } from "../state";
+import {
+  readResolvedState,
+  reenterPublish,
+  reenterRender,
+  writeState,
+  type BodyInputReceived,
+} from "../state";
 import { getTaskByStatePath } from "../task-manager";
 import { reconcileStateArtifacts } from "../workflow-materials";
 
@@ -52,12 +58,15 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const imagesFile = requireArg(parsed, "images-file", "JSON file with marker/path data");
   const scope = optionalArg(parsed, "scope");
   const layout = optionalArg(parsed, "layout");
 
-  const state = await readState(statePath);
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
+  const prepareWasDone = state.phase.prepare.status === "done";
   const raw = JSON.parse(await readFile(imagesFile, "utf-8")) as unknown;
   const incoming = parseReceivedImages(raw);
   const merged = new Map(state.images.body_inputs.received.map((item) => [item.marker, item.path]));
@@ -74,6 +83,17 @@ Options:
   }
 
   await reconcileStateArtifacts(state);
+  if (prepareWasDone && state.images.body_inputs.scope === "newspic-longform") {
+    reenterRender(state);
+  } else if (
+    prepareWasDone &&
+    state.images.body_inputs.scope === "article" &&
+    (state.phase.current === "publish" ||
+      state.phase.current === "done" ||
+      state.phase.publish.status === "done")
+  ) {
+    reenterPublish(state);
+  }
   await writeState(statePath, state);
 
   const task = await getTaskByStatePath(statePath);

package/src/commands/attach-body.ts

@@ -4,7 +4,7 @@ import { extname, join, resolve } from "path";
 import { parseArgs, optionalArg, requireArg } from "../args";
 import { printResult, renderTaskShape } from "../output";
 import { resolveWorkspacePaths } from "../config";
-import { readState, writeState } from "../state";
+import { readResolvedState, reenterPrepare, writeState } from "../state";
 import { getTaskByStatePath } from "../task-manager";
 import { reconcileStateArtifacts } from "../workflow-materials";
 
@@ -48,7 +48,7 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const bodyPath = optionalArg(parsed, "body");
   const bodyText = optionalArg(parsed, "body-text");
   if (!bodyPath && bodyText === undefined) {
@@ -58,13 +58,22 @@ Options:
     throw new Error("Use either --body or --body-text, not both");
   }
 
-  const state = await readState(statePath);
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
   state.source_body_path = await stageManagedBodyFile(
     state.workspace_root,
     state.run_id,
     bodyPath ?? null,
     bodyText ?? null,
   );
+  reenterPrepare(state, {
+    clearFormattedBody: true,
+    resetReview: true,
+  });
+  if (state.handoff.review_policy === "trust_user") {
+    state.content_review = { status: "passed", feedback: null };
+  }
   await reconcileStateArtifacts(state);
   await writeState(statePath, state);
 

package/src/commands/attach-newspic-spec.ts

@@ -2,7 +2,12 @@ import { readFile } from "fs/promises";
 
 import { parseArgs, requireArg } from "../args";
 import { printResult, renderTaskShape } from "../output";
-import { normalizeNewspicRenderSpec, readState, writeState } from "../state";
+import {
+  normalizeNewspicRenderSpec,
+  readResolvedState,
+  reenterRender,
+  writeState,
+} from "../state";
 import { getTaskByStatePath } from "../task-manager";
 import { reconcileStateArtifacts } from "../workflow-materials";
 
@@ -20,13 +25,19 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const specPath = requireArg(parsed, "file", "newspic render spec file");
 
-  const state = await readState(statePath);
+  const resolved = await readResolvedState(requestedStatePath);
+  const statePath = resolved.path;
+  const state = resolved.state;
+  const prepareWasDone = state.phase.prepare.status === "done";
   const spec = JSON.parse(await readFile(specPath, "utf-8")) as unknown;
   state.intent.newspic_render = normalizeNewspicRenderSpec(spec);
   await reconcileStateArtifacts(state);
+  if (prepareWasDone) {
+    reenterRender(state);
+  }
   await writeState(statePath, state);
 
   const task = await getTaskByStatePath(statePath);

package/src/commands/config.ts

@@ -67,6 +67,7 @@ Options:
       wx: mergedWx,
       cos: { ...config.cos, ...(importedObj.cos ?? {}) },
       plugins: { ...config.plugins, ...(importedObj.plugins ?? {}) },
+      imgx: { ...config.imgx, ...(importedObj.imgx ?? {}) },
     };
     // Validate through Zod schema — strips unknown fields, applies defaults
     const merged = PipelineConfigSchema.parse(raw);

package/src/commands/ingest-handoff.ts

@@ -15,7 +15,7 @@ import {
   defaultState,
   generateRunId,
   getRunStatePath,
-  readState,
+  readResolvedState,
   writeState,
   type ContentForm,
   type HandoffAuthoringPolicy,
@@ -473,10 +473,16 @@ Options:
     handoff.mode === "resume"
       ? await resolveExistingStatePath(workspace, handoff)
       : getRunStatePath(workspace, generateRunId());
-  const state =
-    handoff.mode === "resume"
-      ? await readState(statePath)
-      : buildNewState(workspace, statePath, statePath.split("/").pop()?.replace(/\.json$/, "") ?? generateRunId());
+  const resolvedExisting = handoff.mode === "resume"
+    ? await readResolvedState(statePath)
+    : null;
+  const effectiveStatePath = resolvedExisting?.path ?? statePath;
+  const state = resolvedExisting?.state ??
+    buildNewState(
+      workspace,
+      effectiveStatePath,
+      effectiveStatePath.split("/").pop()?.replace(/\.json$/, "") ?? generateRunId(),
+    );
 
   if (handoff.mode === "new" && !state.run_id) {
     state.run_id = generateRunId();
@@ -484,7 +490,7 @@ Options:
   }
 
   await applyHandoffToState(state, handoff);
-  await writeState(state.state_path, state);
+  await writeState(state.state_path || effectiveStatePath, state);
 
   const task = await getTaskByStatePath(state.state_path);
   printResult({

package/src/commands/init.ts

@@ -28,17 +28,19 @@ import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
 import { printResult, renderInit } from "../output";
 import { loadConfig, resolveWorkspaceRoot } from "../config";
 import { resolveFullRoute } from "../routes";
+import {
+  parseAccountName,
+  parseContentForm,
+  parseContentOrigin,
+  parsePublishTargets,
+  parseTaskKind,
+} from "../publish-targets";
 import {
   defaultState,
   generateRunId,
   getRunStatePath,
   normalizeNewspicRenderSpec,
   writeState,
-  type ContentForm,
-  type ContentOrigin,
-  type PublishTarget,
-  type Target,
-  type TaskKind,
 } from "../state";
 
 export async function init(args: string[]): Promise<void> {
@@ -67,10 +69,10 @@ Options:
     return;
   }
 
-  const taskKind = requireArg(parsed, "task-kind", "task kind") as TaskKind;
-  const contentForm = requireArg(parsed, "content-form", "content form") as ContentForm;
+  const taskKind = parseTaskKind(requireArg(parsed, "task-kind", "task kind"));
+  const contentForm = parseContentForm(requireArg(parsed, "content-form", "content form"));
   const targetsRaw = requireArg(parsed, "targets", "publish targets");
-  const contentOrigin = requireArg(parsed, "content-origin", "content origin") as ContentOrigin;
+  const contentOrigin = parseContentOrigin(requireArg(parsed, "content-origin", "content origin"));
   const intentText = optionalArg(parsed, "intent-text") ?? "";
   const accountOverride = optionalArg(parsed, "account");
   const styleHint = optionalArg(parsed, "style-hint") ?? null;
@@ -80,31 +82,13 @@ Options:
   const config = loadConfig();
   const workspace = resolveWorkspaceRoot(optionalArg(parsed, "workspace"), config);
 
-  const targets = targetsRaw.split(",").map((t) => t.trim()) as Target[];
-
-  // Parse multi-target format: "route@account,route@account,..."
-  // Also supports RoutePrimary values (wechat-article, wechat-newspic, blog)
-  // which need to be mapped to Target enum (wechat, blog) for intent.targets.
-  const publishTargets: PublishTarget[] = [];
-  const targetParts = targetsRaw.split(",").map((t) => t.trim());
-  const defaultAccount = accountOverride || "default";
-  const mappedTargets: Target[] = [];
-
-  for (const part of targetParts) {
-    const atIdx = part.indexOf("@");
-    const route = atIdx !== -1 ? part.slice(0, atIdx).trim() : part;
-    const account = atIdx !== -1 ? part.slice(atIdx + 1).trim() : defaultAccount;
-    publishTargets.push({ route: route as any, account });
-    // Map RoutePrimary to Target enum: wechat-* → "wechat", blog → "blog"
-    mappedTargets.push(route.startsWith("wechat") ? "wechat" : route as Target);
-  }
-
-  // Single target: leave publish_targets empty (backward compat)
-  // Multi-target: populate publish_targets
-  const isMultiTarget = publishTargets.length > 1 || targetsRaw.includes("@");
-
-  // Use mapped targets (Target enum) for intent, not raw RoutePrimary values
-  const intentTargets = mappedTargets.length > 0 ? mappedTargets : targets;
+  const defaultAccount = parseAccountName(accountOverride ?? "default");
+  const parsedTargets = parsePublishTargets(targetsRaw, {
+    contentForm,
+    defaultAccount,
+  });
+  const publishTargets = parsedTargets.targets;
+  const intentTargets = parsedTargets.intentTargets;
 
   const runId = generateRunId();
   const statePath = getRunStatePath(workspace, runId);
@@ -121,16 +105,16 @@ Options:
   state.state_path = statePath;
   state.mode = "active";
   state.route = resolveFullRoute(intentText, {
-    account: accountOverride,
+    account: accountOverride ? defaultAccount : undefined,
     contentForm,
     targets: intentTargets,
   });
 
   // Set publish_targets if multi-target
-  if (isMultiTarget && publishTargets.length > 0) {
+  if (parsedTargets.explicit && publishTargets.length > 0) {
     state.publish_targets = publishTargets;
     // First target becomes primary route
-    state.route.primary = publishTargets[0].route as any;
+    state.route.primary = publishTargets[0].route;
     state.route.account = publishTargets[0].account;
   }
 

package/src/commands/prepare-finalize.ts

@@ -15,7 +15,7 @@
  * Output: asset_path, canonical state_path
  */
 
-import { access, copyFile, readFile, writeFile, mkdir } from "fs/promises";
+import { copyFile, readFile, writeFile, mkdir, rename, rm } from "fs/promises";
 import { basename, dirname, isAbsolute, join, resolve } from "path";
 import { parseArgs, requireArg, optionalArg } from "../args";
 import { printResult, renderPrepareFinalize } from "../output";
@@ -26,7 +26,8 @@ import {
   resolveWorkspaceRoot,
 } from "../config";
 import {
-  readState,
+  acquireStateOperationLock,
+  readResolvedState,
   writeState,
   getCanonicalStatePath,
 } from "../state";
@@ -38,15 +39,6 @@ import {
   removePageMarkers,
 } from "../text";
 
-async function pathExists(path: string): Promise<boolean> {
-  try {
-    await access(path);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function isExternalAssetRef(value: string): boolean {
   return /^(https?:|data:|blob:|\/\/)/i.test(value);
 }
@@ -140,13 +132,16 @@ async function materializeInlineAssets(options: {
   };
 
   let rewritten = options.body.replace(
-    /!\[([^\]]*)\]\((<)?([^)]+?)(>)?\)/g,
-    (match, alt, open, src) => {
-      const targetRelativePath = registerAsset(String(src ?? ""));
+    /!\[([^\]]*)\]\((?:<([^>]+)>|([^\s)]+))(\s+(?:"[^"]*"|'[^']*'))?\)/g,
+    (match, alt, angleSrc, bareSrc, titleSuffix) => {
+      const targetRelativePath = registerAsset(String(angleSrc ?? bareSrc ?? ""));
       if (!targetRelativePath) {
         return match;
       }
-      return `![${alt}](${open ? "<" : ""}${formatRelativeAssetRef(targetRelativePath)}${open ? ">" : ""})`;
+      const rewrittenSource = angleSrc
+        ? `<${formatRelativeAssetRef(targetRelativePath)}>`
+        : formatRelativeAssetRef(targetRelativePath);
+      return `![${alt}](${rewrittenSource}${titleSuffix ?? ""})`;
     },
   );
 
@@ -193,11 +188,16 @@ Options:
     return;
   }
 
-  const statePath = requireArg(parsed, "state", "state JSON path");
+  const requestedStatePath = requireArg(parsed, "state", "state JSON path");
   const explicitBodyPath = optionalArg(parsed, "body");
   const workspaceOverride = optionalArg(parsed, "workspace");
 
-  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.content_review.status !== "passed") {
     throw new Error(
       `content_review must be passed before prepare-finalize (current: ${state.content_review.status})`,
@@ -219,6 +219,18 @@ Options:
   const config = loadConfig();
   const workspace = resolveWorkspaceRoot(workspaceOverride ?? state.workspace_root, config);
   const workspacePaths = resolveWorkspacePaths(workspace, config);
+  state.workspace_root = workspace;
+
+  const missingMetadata = [
+    ["metadata.title", state.metadata.title],
+    ["metadata.slug", state.metadata.slug],
+    ["metadata.date", state.metadata.date],
+  ].filter(([, value]) => !value);
+  if (missingMetadata.length > 0) {
+    throw new Error(
+      `prepare-finalize requires complete metadata: ${missingMetadata.map(([field]) => field).join(", ")}`,
+    );
+  }
 
   // ── Step 1: Channel route 2nd pass — highlight_words ──
   // If highlight_words were already set explicitly via `prepare --highlight-words`,
@@ -240,45 +252,52 @@ Options:
     const baseTitle = state.metadata.title;
     let nextSlug = baseSlug;
     let nextTitle = baseTitle;
-    let relativePath = renderPostsRelativePath(config, {
+    const baseRelativePath = renderPostsRelativePath(config, {
       date: state.metadata.date,
       slug: nextSlug,
       title: nextTitle,
     });
-    let candidatePath = join(workspacePaths.postsRoot, relativePath);
-    let suffix = 2;
+    let suffix = 1;
 
-    while (await pathExists(candidatePath)) {
-      if (patternUsesSlug) {
+    while (true) {
+      if (suffix > 1 && patternUsesSlug) {
         nextSlug = `${baseSlug}-v${suffix}`;
-        relativePath = renderPostsRelativePath(config, {
-          date: state.metadata.date,
-          slug: nextSlug,
-          title: baseTitle,
-        });
-      } else if (patternUsesTitle) {
+      } else if (suffix > 1 && patternUsesTitle) {
         nextTitle = `${baseTitle}-v${suffix}`;
-        relativePath = renderPostsRelativePath(config, {
-          date: state.metadata.date,
-          slug: baseSlug,
-          title: nextTitle,
-        });
-      } else {
-        relativePath = appendSuffixToRelativePath(relativePath, suffix);
       }
-      candidatePath = join(workspacePaths.postsRoot, relativePath);
-      suffix += 1;
+      const relativePath = suffix === 1
+        ? baseRelativePath
+        : patternUsesSlug || patternUsesTitle
+          ? renderPostsRelativePath(config, {
+              date: state.metadata.date,
+              slug: nextSlug,
+              title: nextTitle,
+            })
+          : appendSuffixToRelativePath(baseRelativePath, suffix);
+      const candidatePath = join(workspacePaths.postsRoot, relativePath);
+      await mkdir(dirname(candidatePath), { recursive: true });
+      try {
+        await mkdir(candidatePath);
+        assetPath = candidatePath;
+        break;
+      } catch (error) {
+        const code = error instanceof Error && "code" in error
+          ? String((error as NodeJS.ErrnoException).code)
+          : "";
+        if (code !== "EEXIST") {
+          throw error;
+        }
+        suffix += 1;
+      }
     }
 
     if (patternUsesSlug && nextSlug !== state.metadata.slug) {
       state.metadata.slug = nextSlug;
     }
-    assetPath = candidatePath;
+  } else {
+    await mkdir(assetPath, { recursive: true });
   }
 
-  // Create directories
-  await mkdir(assetPath, { recursive: true });
-
   const bodySourceDir = dirname(state.source_body_path ?? bodyPath);
   body = await materializeInlineAssets({
     body,
@@ -312,7 +331,14 @@ Options:
   // Write post.md
   const postContent = `${frontmatter}\n\n${removePageMarkers(body)}`;
   const postPath = join(assetPath, "post.md");
-  await writeFile(postPath, postContent, "utf-8");
+  const postTempPath = `${postPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    await writeFile(postTempPath, postContent, "utf-8");
+    await rename(postTempPath, postPath);
+  } catch (error) {
+    await rm(postTempPath, { force: true }).catch(() => undefined);
+    throw error;
+  }
 
   // Update state
   state.asset_path = assetPath;
@@ -322,6 +348,7 @@ Options:
   state.phase.prepare = { status: "done", error: null };
   state.phase.current = state.intent.requires.render ? "render" : 
                          state.intent.requires.publish ? "publish" : "done";
+  state.mode = state.phase.current === "done" ? "done" : "active";
   
   // Clear redo_hint — prepare sub-sequence is complete
   state.redo_hint = null;
@@ -333,7 +360,9 @@ Options:
   await writeState(state.state_path, state);
 
   // Also update the temp run state to point to canonical
-  await writeState(statePath, state);
+  if (resolve(statePath) !== resolve(state.state_path)) {
+    await writeState(statePath, state);
+  }
 
   // Output summary
   const output = {
@@ -345,4 +374,7 @@ Options:
     content_version: state.artifacts.content_version,
   };
   printResult(output, renderPrepareFinalize);
+  } finally {
+    await releaseOperationLock();
+  }
 }