@zzclub/pipeline 0.2.0 → 0.4.0

package/src/commands/prepare-finalize.ts

@@ -0,0 +1,348 @@
+/**
+ * prepare-finalize — Complete the Prepare phase:
+ *   1. channel-route 2nd pass: generate highlight_words from final title
+ *   2. asset-save: create asset directory, write post.md with frontmatter, write canonical state
+ *
+ * Called after style (if needed) and format are done.
+ * This is the boundary between temp run state and canonical asset state.
+ *
+ * Usage:
+ *   zzhub-pipeline prepare-finalize \
+ *     --state /path/to/state.json \
+ *     --body /path/to/body_formatted.md \
+ *     [--workspace /abs/workspace]
+ *
+ * Output: asset_path, canonical state_path
+ */
+
+import { access, copyFile, readFile, writeFile, mkdir } from "fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "path";
+import { parseArgs, requireArg, optionalArg } from "../args";
+import { printResult, renderPrepareFinalize } from "../output";
+import {
+  loadConfig,
+  renderPostsRelativePath,
+  resolveWorkspacePaths,
+  resolveWorkspaceRoot,
+} from "../config";
+import {
+  readState,
+  writeState,
+  getCanonicalStatePath,
+} from "../state";
+import {
+  extractHighlightWords,
+  buildFrontmatter,
+  formatArticle,
+  stripLeadingTitleHeading,
+  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);
+}
+
+function normalizeSafeRelativeAssetPath(rawPath: string): string | null {
+  const normalized = rawPath
+    .trim()
+    .replace(/^file:\/\//i, "")
+    .replaceAll("\\", "/")
+    .replace(/^[.]\//, "")
+    .replace(/[?#].*$/, "");
+
+  if (
+    !normalized ||
+    normalized.startsWith("/") ||
+    normalized.startsWith("../") ||
+    normalized.includes("/../")
+  ) {
+    return null;
+  }
+
+  return normalized;
+}
+
+function formatRelativeAssetRef(relativePath: string): string {
+  return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+}
+
+function uniqueRelativeAssetPath(
+  targetRelativePath: string,
+  sourcePath: string,
+  usedTargetPaths: Map<string, string>,
+): string {
+  const normalizedTarget = targetRelativePath.replaceAll("\\", "/");
+  const existingSource = usedTargetPaths.get(normalizedTarget);
+  if (!existingSource || existingSource === sourcePath) {
+    usedTargetPaths.set(normalizedTarget, sourcePath);
+    return normalizedTarget;
+  }
+
+  const fileName = basename(normalizedTarget);
+  const extensionIndex = fileName.lastIndexOf(".");
+  const name = extensionIndex > 0 ? fileName.slice(0, extensionIndex) : fileName;
+  const ext = extensionIndex > 0 ? fileName.slice(extensionIndex) : "";
+  const directory = dirname(normalizedTarget);
+
+  let suffix = 2;
+  while (true) {
+    const candidateLeaf = `${name}-${suffix}${ext}`;
+    const candidate = directory === "."
+      ? candidateLeaf
+      : join(directory, candidateLeaf).replaceAll("\\", "/");
+    const candidateSource = usedTargetPaths.get(candidate);
+    if (!candidateSource || candidateSource === sourcePath) {
+      usedTargetPaths.set(candidate, sourcePath);
+      return candidate;
+    }
+    suffix += 1;
+  }
+}
+
+async function materializeInlineAssets(options: {
+  body: string;
+  bodySourceDir: string;
+  assetPath: string;
+}): Promise<string> {
+  const usedTargetPaths = new Map<string, string>();
+  const copyJobs = new Map<string, { sourcePath: string; targetRelativePath: string }>();
+
+  const registerAsset = (rawSource: string): string | null => {
+    const trimmed = rawSource.trim();
+    if (!trimmed || isExternalAssetRef(trimmed)) {
+      return null;
+    }
+
+    const sourcePath = trimmed.startsWith("file://")
+      ? new URL(trimmed).pathname
+      : isAbsolute(trimmed)
+        ? trimmed
+        : resolve(options.bodySourceDir, trimmed);
+
+    const safeRelativePath = normalizeSafeRelativeAssetPath(trimmed);
+    const targetRelativePath = uniqueRelativeAssetPath(
+      safeRelativePath ?? join("_inline-assets", basename(sourcePath)).replaceAll("\\", "/"),
+      sourcePath,
+      usedTargetPaths,
+    );
+
+    copyJobs.set(sourcePath, { sourcePath, targetRelativePath });
+    return targetRelativePath;
+  };
+
+  let rewritten = options.body.replace(
+    /!\[([^\]]*)\]\((<)?([^)]+?)(>)?\)/g,
+    (match, alt, open, src) => {
+      const targetRelativePath = registerAsset(String(src ?? ""));
+      if (!targetRelativePath) {
+        return match;
+      }
+      return `![${alt}](${open ? "<" : ""}${formatRelativeAssetRef(targetRelativePath)}${open ? ">" : ""})`;
+    },
+  );
+
+  rewritten = rewritten.replace(
+    /(<img\b[^>]*\bsrc=["'])([^"']+)(["'][^>]*>)/gi,
+    (match, prefix, src, suffix) => {
+      const targetRelativePath = registerAsset(String(src ?? ""));
+      if (!targetRelativePath) {
+        return match;
+      }
+      return `${prefix}${formatRelativeAssetRef(targetRelativePath)}${suffix}`;
+    },
+  );
+
+  for (const job of copyJobs.values()) {
+    const destinationPath = join(options.assetPath, job.targetRelativePath);
+    await mkdir(dirname(destinationPath), { recursive: true });
+    await copyFile(job.sourcePath, destinationPath);
+  }
+
+  return rewritten;
+}
+
+function appendSuffixToRelativePath(relativePath: string, suffix: number): string {
+  const normalized = relativePath.replace(/\\/g, "/");
+  const parent = dirname(normalized);
+  const leaf = normalized.split("/").filter(Boolean).pop() || "untitled";
+  const suffixedLeaf = `${leaf}-v${suffix}`;
+  return parent === "." ? suffixedLeaf : join(parent, suffixedLeaf);
+}
+
+export async function prepareFinalize(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline prepare-finalize [options]
+
+Options:
+  --state          Path to state JSON (required)
+  --body           Path to body text file (optional; defaults to state.formatted_body_path)
+  --workspace      Workspace root (optional; defaults to state.workspace_root)
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const explicitBodyPath = optionalArg(parsed, "body");
+  const workspaceOverride = optionalArg(parsed, "workspace");
+
+  const state = await readState(statePath);
+  if (state.content_review.status !== "passed") {
+    throw new Error(
+      `content_review must be passed before prepare-finalize (current: ${state.content_review.status})`,
+    );
+  }
+  const bodyPath = explicitBodyPath ?? state.formatted_body_path;
+  if (!bodyPath) {
+    throw new Error(
+      "Missing required argument: --body (body text file path). Run prepare first or pass --body explicitly.",
+    );
+  }
+  let body = await readFile(bodyPath, "utf-8");
+
+  // If style was applied but format wasn't re-applied, apply format now
+  // (format is idempotent, safe to re-apply)
+  body = formatArticle(body);
+  body = stripLeadingTitleHeading(body, state.metadata.title);
+
+  const config = loadConfig();
+  const workspace = resolveWorkspaceRoot(workspaceOverride ?? state.workspace_root, config);
+  const workspacePaths = resolveWorkspacePaths(workspace, config);
+
+  // ── Step 1: Channel route 2nd pass — highlight_words ──
+  // If highlight_words were already set explicitly via `prepare --highlight-words`,
+  // respect that and skip the auto-extract algorithm.
+  const highlightWords =
+    state.route.highlight_words && state.route.highlight_words.length > 0
+      ? state.route.highlight_words
+      : extractHighlightWords(state.metadata.title);
+  state.route.highlight_words = highlightWords;
+
+  // ── Step 2: Asset save ──
+
+  // Build asset path from configured posts pattern.
+  let assetPath = state.asset_path;
+  if (!assetPath) {
+    const patternUsesSlug = config.paths.postsPathPattern.includes("{slug}");
+    const patternUsesTitle = config.paths.postsPathPattern.includes("{title}");
+    const baseSlug = state.metadata.slug;
+    const baseTitle = state.metadata.title;
+    let nextSlug = baseSlug;
+    let nextTitle = baseTitle;
+    let relativePath = renderPostsRelativePath(config, {
+      date: state.metadata.date,
+      slug: nextSlug,
+      title: nextTitle,
+    });
+    let candidatePath = join(workspacePaths.postsRoot, relativePath);
+    let suffix = 2;
+
+    while (await pathExists(candidatePath)) {
+      if (patternUsesSlug) {
+        nextSlug = `${baseSlug}-v${suffix}`;
+        relativePath = renderPostsRelativePath(config, {
+          date: state.metadata.date,
+          slug: nextSlug,
+          title: baseTitle,
+        });
+      } else if (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;
+    }
+
+    if (patternUsesSlug && nextSlug !== state.metadata.slug) {
+      state.metadata.slug = nextSlug;
+    }
+    assetPath = candidatePath;
+  }
+
+  // Create directories
+  await mkdir(assetPath, { recursive: true });
+
+  const bodySourceDir = dirname(state.source_body_path ?? bodyPath);
+  body = await materializeInlineAssets({
+    body,
+    bodySourceDir,
+    assetPath,
+  });
+
+  // Create image directories based on route
+  if (
+    state.route.primary === "wechat-article" ||
+    state.route.extras.includes("wechat-article")
+  ) {
+    await mkdir(join(assetPath, "images", "wechat"), { recursive: true });
+  }
+  if (
+    state.route.primary === "wechat-newspic" ||
+    state.route.extras.includes("wechat-newspic")
+  ) {
+    await mkdir(join(assetPath, "images", "newspic"), { recursive: true });
+  }
+
+  // Build frontmatter
+  const frontmatter = buildFrontmatter({
+    title: state.metadata.title,
+    date: state.metadata.date,
+    platform: state.route.primary,
+    description: state.metadata.description,
+    tags: state.metadata.tags,
+  });
+
+  // Write post.md
+  const postContent = `${frontmatter}\n\n${removePageMarkers(body)}`;
+  const postPath = join(assetPath, "post.md");
+  await writeFile(postPath, postContent, "utf-8");
+
+  // Update state
+  state.asset_path = assetPath;
+  state.state_path = getCanonicalStatePath(assetPath);
+
+  // Phase transitions
+  state.phase.prepare = { status: "done", error: null };
+  state.phase.current = state.intent.requires.render ? "render" : 
+                         state.intent.requires.publish ? "publish" : "done";
+  
+  // Clear redo_hint — prepare sub-sequence is complete
+  state.redo_hint = null;
+
+  // Bump content version
+  state.artifacts.content_version += 1;
+
+  // Write canonical state
+  await writeState(state.state_path, state);
+
+  // Also update the temp run state to point to canonical
+  await writeState(statePath, state);
+
+  // Output summary
+  const output = {
+    asset_path: assetPath,
+    state_path: state.state_path,
+    post_path: postPath,
+    highlight_words: highlightWords,
+    phase: state.phase.current,
+    content_version: state.artifacts.content_version,
+  };
+  printResult(output, renderPrepareFinalize);
+}

package/src/commands/prepare.ts

@@ -0,0 +1,310 @@
+/**
+ * prepare — Execute deterministic Prepare phase steps:
+ *   1. channel-route (1st pass): route.primary, extras, account, content_profile, visual_params
+ *   2. authoring decision: rewrite_allowed, style_mode
+ *   3. format: apply text formatting rules to body
+ *   4. asset-meta: title, slug, date, description, tags
+ *
+ * Style step is NOT included — it requires LLM and stays as a skill.
+ * This command reads the run state, applies deterministic transforms,
+ * and writes back the updated state.
+ *
+ * Usage:
+ *   zzhub-pipeline prepare \
+ *     --state /path/to/state.json \
+ *     [--body /path/to/body_raw.md] \
+ *     [--title "Custom title"] \
+ *     [--intent-text "发公众号文章"] \
+ *     [--account default] \
+ *     [--route wechat-article] \
+ *     [--extras blog] \
+ *     [--style-request]
+ *
+ * Output: Updated state JSON. body_formatted is written to a managed temp file
+ *         unless --body-out is explicitly provided.
+ */
+
+import { copyFile, mkdir, readFile, writeFile } from "fs/promises";
+import { extname, join, resolve } from "path";
+import { parseArgs, requireArg, optionalArg, flagArg } from "../args";
+import { printResult, renderPrepare } from "../output";
+import { resolveWorkspacePaths } from "../config";
+import {
+  defaultBodyInputs,
+  readState,
+  writeState,
+} from "../state";
+import { resolveFullRoute } from "../routes";
+import { resolveAuthoring, hasStyleRequest } from "../profiles";
+import {
+  formatArticle,
+  generateSlug,
+  todayDate,
+  extractDescription,
+  findIllustrationMarkers,
+  stripFrontmatter,
+} from "../text";
+import type { RoutePrimary } from "../state";
+
+async function stageManagedBodyFile(
+  workspaceRoot: string,
+  runId: string,
+  sourcePath: string,
+): Promise<string> {
+  const tempRoot = resolveWorkspacePaths(workspaceRoot).tempRoot;
+  const extension = extname(sourcePath) || ".md";
+  const managedDir = join(tempRoot, runId);
+  const managedPath = join(managedDir, `source-body${extension}`);
+  await mkdir(managedDir, { recursive: true });
+  if (resolve(sourcePath) !== resolve(managedPath)) {
+    await copyFile(sourcePath, managedPath);
+  }
+  return managedPath;
+}
+
+function getManagedFormattedBodyPath(workspaceRoot: string, runId: string): string {
+  return join(resolveWorkspacePaths(workspaceRoot).tempRoot, runId, "formatted-body.md");
+}
+
+function shouldPreserveExistingRoute(params: {
+  intentText: string;
+  routeOverride?: RoutePrimary;
+  extrasRaw?: string;
+  accountOverride?: string;
+  assetPath: string;
+}): boolean {
+  return (
+    Boolean(params.assetPath) &&
+    !params.intentText.trim() &&
+    !params.routeOverride &&
+    !params.extrasRaw &&
+    !params.accountOverride
+  );
+}
+
+export async function prepare(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline prepare [options]
+
+Options:
+  --state          Path to state JSON (required)
+  --body           Path to body text file (body_raw or body_styled) (optional if body already attached)
+  --title          Override title (optional; defaults to first heading or first line)
+  --intent-text    Original user intent text for route resolution (optional)
+  --account        Override account (optional)
+  --route          Override primary route (optional)
+  --extras         Comma-separated extra routes (optional)
+  --style-request  Flag: user requested style processing
+  --body-out       Path to write formatted body (optional; defaults to managed temp path)
+  --suggested-title  Suggested title from writer (optional)
+  --suggested-slug   Suggested slug from writer (optional; English + hyphens, ≤50 chars; overrides auto-generated slug)
+  --highlight-words  Comma-separated highlight words for cover (optional; overrides auto-extract in prepare-finalize)
+`.trim());
+    return;
+  }
+
+  const statePath = 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 extrasRaw = optionalArg(parsed, "extras");
+  const isStyleRequest = flagArg(parsed, "style-request");
+  const bodyOutPath = optionalArg(parsed, "body-out");
+  const suggestedTitle = optionalArg(parsed, "suggested-title");
+  const suggestedSlug = optionalArg(parsed, "suggested-slug");
+  const highlightWordsRaw = optionalArg(parsed, "highlight-words");
+  const highlightWordsOverride = highlightWordsRaw
+    ? highlightWordsRaw.split(",").map((s) => s.trim()).filter(Boolean)
+    : undefined;
+
+  const extras = extrasRaw
+    ? (extrasRaw.split(",").map((s) => s.trim()) as RoutePrimary[])
+    : undefined;
+
+  // Read state and body
+  const state = await readState(statePath);
+  const intentText = optionalArg(parsed, "intent-text") ?? state.intent.intent_text ?? "";
+  const resolvedBodyPath = bodyPath
+    ? await stageManagedBodyFile(state.workspace_root, state.run_id, bodyPath)
+    : state.source_body_path;
+  if (!resolvedBodyPath) {
+    throw new Error("No body is attached yet. Use attach-body first or pass --body.");
+  }
+  const bodyRaw = await readFile(resolvedBodyPath, "utf-8");
+  const cleanBody = stripFrontmatter(bodyRaw);
+  state.source_body_path = resolvedBodyPath;
+  state.intent.intent_text = intentText || state.intent.intent_text;
+
+  // ── Step 1: Channel route (1st pass) ──
+  const route = shouldPreserveExistingRoute({
+    intentText,
+    routeOverride,
+    extrasRaw,
+    accountOverride,
+    assetPath: state.asset_path,
+  })
+    ? state.route
+    : resolveFullRoute(intentText, {
+        primary: routeOverride,
+        extras,
+        account: accountOverride,
+        contentForm: state.intent.content_form,
+        targets: state.intent.targets,
+      });
+
+  state.route = route;
+
+  // If caller provided explicit highlight words, store them now so prepare-finalize
+  // can skip the auto-extract algorithm.
+  if (highlightWordsOverride && highlightWordsOverride.length > 0) {
+    state.route.highlight_words = highlightWordsOverride;
+  }
+
+  // Re-derive requires.render and requires.publish based on resolved route.
+  // requires.research is intentional (set at init from user request), not touched here.
+  // Same for render/publish: if the orchestrator set them at init, keep that value.
+  // wechat-article always needs render regardless.
+  state.intent.requires.render =
+    state.intent.requires.render ||
+    route.primary === "wechat-article";
+  state.intent.requires.publish =
+    state.intent.requires.publish ||
+    state.intent.task_kind === "publish";
+
+  // ── Step 2: Author select ──
+  const styleRequest =
+    isStyleRequest || hasStyleRequest(intentText);
+
+  const authoring = resolveAuthoring({
+    contentOrigin: state.intent.content_origin,
+    styleHint: state.intent.style_hint,
+    hasStyleRequest: styleRequest,
+  });
+
+  state.authoring = authoring;
+
+  // Update requires.style based on authoring result
+  state.intent.requires.style =
+    authoring.rewrite_allowed && authoring.style_mode !== "none";
+
+  // ── Step 3: Format ──
+  // In the current workflow, Writer/Style already own the LLM rewrite.
+  // Prepare records the authoring snapshot, then always formats the final body.
+  const bodyFormatted = formatArticle(cleanBody);
+
+  // ── Step 4: Asset meta ──
+  // Determine title
+  let title = titleOverride ?? suggestedTitle ?? state.metadata.title.trim();
+  if (!title) {
+    // Extract from body: first heading or first line
+    const lines = cleanBody.split("\n");
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const headingMatch = trimmed.match(/^#{1,6}\s+(.+)/);
+      if (headingMatch) {
+        title = headingMatch[1].trim();
+        break;
+      }
+      // Use first non-empty line
+      title = trimmed;
+      break;
+    }
+  }
+
+  // Prefer editor-supplied slug; sanitize it defensively, then fall back to auto-generate
+  const slug = suggestedSlug
+    ? suggestedSlug
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80) || generateSlug(title)
+    : generateSlug(title);
+  const date = todayDate();
+
+  // Description: required for wechat-article, optional otherwise
+  let description: string | null = null;
+  if (route.primary === "wechat-article") {
+    description = extractDescription(bodyFormatted);
+  }
+
+  // Tags: required for blog (can be empty list)
+  const tags: string[] = [];
+
+  state.metadata = {
+    title,
+    slug,
+    date,
+    description,
+    tags,
+  };
+
+  // ── Scan for illustration markers (for article body_inputs) ──
+  const needsArticleInputs =
+    route.primary === "wechat-article" ||
+    route.extras.includes("wechat-article");
+  const keepsNewspicInputs =
+    route.primary === "wechat-newspic" ||
+    route.extras.includes("wechat-newspic");
+
+  if (needsArticleInputs) {
+    const markers = findIllustrationMarkers(cleanBody);
+    if (markers.length > 0) {
+      const previousInputs =
+        state.images.body_inputs.scope === "article"
+          ? 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: "article",
+        expected: markers.length,
+        received,
+        status:
+          received.length >= markers.length
+            ? "ready"
+            : "pending",
+        layout: previousInputs?.layout ?? "staggered",
+      };
+    } else {
+      state.images.body_inputs = defaultBodyInputs();
+    }
+  } else if (!keepsNewspicInputs || state.images.body_inputs.scope === "article") {
+    state.images.body_inputs = defaultBodyInputs();
+  }
+
+  // ── Write state ──
+  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 writeFile(formattedBodyPath, bodyFormatted, "utf-8");
+
+  // Output summary for orchestrator
+  const illustrationMarkers = findIllustrationMarkers(cleanBody);
+  const output = {
+    state_path: statePath,
+    route: {
+      primary: state.route.primary,
+      account: state.route.account,
+    },
+    metadata: {
+      title: state.metadata.title,
+      slug: state.metadata.slug,
+      date: state.metadata.date,
+    },
+    requires_style: state.intent.requires.style,
+    body_formatted_path: formattedBodyPath,
+    ...(illustrationMarkers.length > 0 ? { illustration_markers: illustrationMarkers } : {}),
+  };
+  printResult(output, renderPrepare);
+}