@zzclub/pipeline 0.2.0 → 0.4.0

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

@@ -0,0 +1,88 @@
+import { readFile } from "fs/promises";
+
+import { parseArgs, optionalArg, requireArg } from "../args";
+import { printResult, renderTaskShape } from "../output";
+import { readState, writeState, type BodyInputReceived } from "../state";
+import { getTaskByStatePath } from "../task-manager";
+import { reconcileStateArtifacts } from "../workflow-materials";
+
+function parseReceivedImages(raw: unknown): BodyInputReceived[] {
+  if (Array.isArray(raw)) {
+    return raw.flatMap((item) => {
+      if (!item || typeof item !== "object") {
+        return [];
+      }
+      const input = item as Record<string, unknown>;
+      const marker = typeof input.marker === "string" ? input.marker.trim() : "";
+      const path = typeof input.path === "string" ? input.path.trim() : "";
+      return marker && path ? [{ marker, path }] : [];
+    });
+  }
+
+  if (raw && typeof raw === "object") {
+    const input = raw as Record<string, unknown>;
+    if (Array.isArray(input.images)) {
+      return parseReceivedImages(input.images);
+    }
+    return Object.entries(input).flatMap(([marker, path]) => {
+      const normalizedMarker = marker.trim();
+      const normalizedPath = typeof path === "string" ? path.trim() : "";
+      return normalizedMarker && normalizedPath
+        ? [{ marker: normalizedMarker, path: normalizedPath }]
+        : [];
+    });
+  }
+
+  return [];
+}
+
+export async function attachBodyImages(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline attach-body-images [options]
+
+Options:
+  --state        Path to state JSON (required)
+  --images-file  JSON file mapping marker -> path or [{ marker, path }] (required)
+  --scope        article | newspic-longform (optional)
+  --layout       Layout hint such as staggered/editorial (optional)
+`.trim());
+    return;
+  }
+
+  const statePath = 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 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]));
+  for (const item of incoming) {
+    merged.set(item.marker, item.path);
+  }
+
+  state.images.body_inputs.received = [...merged.entries()].map(([marker, path]) => ({ marker, path }));
+  if (scope === "article" || scope === "newspic-longform") {
+    state.images.body_inputs.scope = scope;
+  }
+  if (layout) {
+    state.images.body_inputs.layout = layout;
+  }
+
+  await reconcileStateArtifacts(state);
+  await writeState(statePath, state);
+
+  const task = await getTaskByStatePath(statePath);
+  printResult(
+    {
+      summary: task.summary,
+      blockers: task.blockers,
+      next_action: task.next_action,
+    },
+    renderTaskShape,
+  );
+}

package/src/commands/attach-body.ts

@@ -0,0 +1,86 @@
+import { copyFile, mkdir, writeFile } from "fs/promises";
+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 { getTaskByStatePath } from "../task-manager";
+import { reconcileStateArtifacts } from "../workflow-materials";
+
+async function stageManagedBodyFile(
+  workspaceRoot: string,
+  runId: string,
+  sourcePath: string | null,
+  bodyText: string | null,
+): Promise<string> {
+  const tempRoot = resolveWorkspacePaths(workspaceRoot).tempRoot;
+  const extension = sourcePath ? extname(sourcePath) || ".md" : ".md";
+  const managedDir = join(tempRoot, runId);
+  const managedPath = join(managedDir, `source-body${extension}`);
+  await mkdir(managedDir, { recursive: true });
+
+  if (bodyText !== null) {
+    await writeFile(managedPath, bodyText, "utf-8");
+  } else if (sourcePath) {
+    if (resolve(sourcePath) !== resolve(managedPath)) {
+      await copyFile(sourcePath, managedPath);
+    }
+  } else {
+    throw new Error("Either sourcePath or bodyText must be provided");
+  }
+
+  return managedPath;
+}
+
+export async function attachBody(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline attach-body [options]
+
+Options:
+  --state      Path to state JSON (required)
+  --body       Path to markdown body file (optional)
+  --body-text  Inline markdown body text (optional)
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const bodyPath = optionalArg(parsed, "body");
+  const bodyText = optionalArg(parsed, "body-text");
+  if (!bodyPath && bodyText === undefined) {
+    throw new Error("Missing required argument: --body or --body-text");
+  }
+  if (bodyPath && bodyText !== undefined) {
+    throw new Error("Use either --body or --body-text, not both");
+  }
+
+  const state = await readState(statePath);
+  state.source_body_path = await stageManagedBodyFile(
+    state.workspace_root,
+    state.run_id,
+    bodyPath ?? null,
+    bodyText ?? null,
+  );
+  await reconcileStateArtifacts(state);
+  await writeState(statePath, state);
+
+  const task = await getTaskByStatePath(statePath);
+  printResult(
+    {
+      summary: {
+        run_id: task.summary.run_id,
+        mode: task.summary.mode,
+        phase: task.summary.phase,
+        route: task.summary.route,
+        metadata: task.summary.metadata,
+      },
+      blockers: task.blockers,
+      next_action: task.next_action,
+    },
+    renderTaskShape,
+  );
+}

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

@@ -0,0 +1,41 @@
+import { readFile } from "fs/promises";
+
+import { parseArgs, requireArg } from "../args";
+import { printResult, renderTaskShape } from "../output";
+import { normalizeNewspicRenderSpec, readState, writeState } from "../state";
+import { getTaskByStatePath } from "../task-manager";
+import { reconcileStateArtifacts } from "../workflow-materials";
+
+export async function attachNewspicSpec(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline attach-newspic-spec [options]
+
+Options:
+  --state  Path to state JSON (required)
+  --file   Path to newspic render spec JSON (required)
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const specPath = requireArg(parsed, "file", "newspic render spec file");
+
+  const state = await readState(statePath);
+  const spec = JSON.parse(await readFile(specPath, "utf-8")) as unknown;
+  state.intent.newspic_render = normalizeNewspicRenderSpec(spec);
+  await reconcileStateArtifacts(state);
+  await writeState(statePath, state);
+
+  const task = await getTaskByStatePath(statePath);
+  printResult(
+    {
+      summary: task.summary,
+      blockers: task.blockers,
+      next_action: task.next_action,
+    },
+    renderTaskShape,
+  );
+}

package/src/commands/checkpoint.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, writeFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+
+import { checkpoint } from "./checkpoint";
+import { defaultState, writeState } from "../state";
+
+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;
+}
+
+async function captureTextOutput(fn: () => Promise<void>): Promise<string> {
+  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 lines.join("\n").trim();
+}
+
+describe("checkpoint", () => {
+  test("reports validation passing for a well-formed prepare state", async () => {
+    const configPath = join(tmpdir(), `zzhub-test-checkpoint-${process.pid}-${Date.now()}.json`);
+    await writeFile(configPath, "{}", "utf-8");
+    process.env.ZZHUB_PIPELINE_CONFIG = configPath;
+
+    const workspace = await makeTempDir("zzhub-checkpoint-");
+    const statePath = join(workspace, "state.json");
+
+    const state = defaultState();
+    state.workspace_root = workspace;
+    state.state_path = statePath;
+    state.run_id = "run-checkpoint-1";
+    state.phase.current = "prepare";
+    await writeState(statePath, state);
+
+    const output = await captureJsonOutput<{
+      validation: { phase_checked: string; valid: boolean; errors: unknown[] };
+      next_action: { action: string };
+    }>(() => checkpoint(["--state", statePath]));
+
+    expect(output.validation.phase_checked).toBe("prepare");
+    expect(output.validation.valid).toBe(true);
+    expect(output.validation.errors).toEqual([]);
+    expect(output.next_action).toBeDefined();
+  });
+
+  test("agent view renders markdown with next action", async () => {
+    const configPath = join(tmpdir(), `zzhub-test-checkpoint-${process.pid}-${Date.now()}.json`);
+    await writeFile(configPath, "{}", "utf-8");
+    process.env.ZZHUB_PIPELINE_CONFIG = configPath;
+
+    const workspace = await makeTempDir("zzhub-checkpoint-view-");
+    const statePath = join(workspace, "state.json");
+
+    const state = defaultState();
+    state.workspace_root = workspace;
+    state.state_path = statePath;
+    state.run_id = "run-checkpoint-view";
+    state.route.primary = "wechat-article";
+    state.metadata.title = "Test Title";
+    await writeState(statePath, state);
+
+    const output = await captureTextOutput(() =>
+      checkpoint(["--state", statePath, "--view", "agent"]),
+    );
+
+    expect(output).toContain("# Current Task");
+    expect(output).toContain("## Next Action");
+  });
+});

package/src/commands/checkpoint.ts

@@ -0,0 +1,66 @@
+/**
+ * checkpoint — Read and validate state, report phase status.
+ *
+ * Used by orchestrator to check state at phase boundaries.
+ *
+ * Usage:
+ *   zzhub-pipeline checkpoint --state /path/to/state.json [--phase render]
+ *
+ * Output: JSON with state summary and validation errors.
+ */
+
+import { parseArgs, requireArg, optionalArg } from "../args";
+import { printResult, renderTaskShape } from "../output";
+import { getTaskByStatePath } from "../task-manager";
+import { parseTaskViewMode, renderTaskStatusMarkdown } from "../task-views";
+import type { PhaseName } from "../state";
+import { validateForPhase } from "../state";
+
+export async function checkpoint(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline checkpoint [options]
+
+Options:
+  --state    Path to state JSON (required)
+  --phase    Phase to validate for (optional; defaults to state.phase.current)
+  --view     json | markdown | agent (default: json)
+`.trim());
+    return;
+  }
+
+  const statePath = requireArg(parsed, "state", "state JSON path");
+  const phaseOverride = optionalArg(parsed, "phase") as PhaseName | undefined;
+  const view = parseTaskViewMode(optionalArg(parsed, "view"));
+
+  const task = await getTaskByStatePath(statePath);
+  const phase = phaseOverride ?? task.state.phase.current;
+  const errors = validateForPhase(task.state, phase);
+
+  const output = {
+    summary: task.summary,
+    validation: {
+      phase_checked: phase,
+      valid: errors.length === 0,
+      errors,
+    },
+    gaps: task.gaps,
+    blockers: task.blockers,
+    next_action: task.next_action,
+  };
+
+  if (view !== "json") {
+    console.log(renderTaskStatusMarkdown({
+      ...task,
+      validation: output.validation,
+    }, view));
+  } else {
+    printResult(output, renderTaskShape);
+  }
+
+  if (errors.length > 0) {
+    process.exit(1);
+  }
+}

package/src/commands/config.ts

@@ -0,0 +1,106 @@
+import { readFileSync } from "fs";
+import { parseArgs, optionalArg, flagArg } from "../args";
+import { printResult, renderConfig } from "../output";
+import {
+  configSummary,
+  getConfigValue,
+  loadConfig,
+  PipelineConfigSchema,
+  redactConfig,
+  redactConfigValue,
+  saveConfig,
+  setConfigValue,
+} from "../config";
+
+export async function configCommand(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline config [options]
+
+Options:
+  --key        Dot-path key to read or update
+  --value      New value for --key
+  --json       Force JSON output for scalar reads
+  --export     Print full config as JSON (secrets redacted; use --raw to show all)
+  --import     Path to a JSON file to merge into current config
+  --raw        Show secrets unredacted (use with --export)
+`.trim());
+    return;
+  }
+
+  const config = loadConfig();
+
+  // --export
+  if (flagArg(parsed, "export")) {
+    const raw = flagArg(parsed, "raw");
+    const output = raw ? config : redactConfig(config);
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  // --import
+  const importPath = optionalArg(parsed, "import");
+  if (importPath) {
+    let imported: unknown;
+    try {
+      imported = JSON.parse(readFileSync(importPath, "utf-8"));
+    } catch (err) {
+      throw new Error(`Failed to read import file: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    // Merge: existing values win, imported fills gaps
+    const importedObj = (typeof imported === "object" && imported !== null ? imported : {}) as Record<string, unknown>;
+    const mergedWx = {
+      ...config.wx,
+      ...(importedObj.wx as Record<string, unknown> ?? {}),
+      accounts: {
+        ...config.wx.accounts,
+        ...((importedObj.wx as Record<string, unknown>)?.accounts as Record<string, unknown> ?? {}),
+      },
+    };
+    const raw = {
+      paths: { ...config.paths, ...(importedObj.paths ?? {}) },
+      services: { ...config.services, ...(importedObj.services ?? {}) },
+      commands: { ...config.commands, ...(importedObj.commands ?? {}) },
+      wx: mergedWx,
+      cos: { ...config.cos, ...(importedObj.cos ?? {}) },
+      plugins: { ...config.plugins, ...(importedObj.plugins ?? {}) },
+    };
+    // Validate through Zod schema — strips unknown fields, applies defaults
+    const merged = PipelineConfigSchema.parse(raw);
+
+    saveConfig(merged);
+    printResult(configSummary(merged), renderConfig);
+    return;
+  }
+
+  // --key / --value
+  const key = optionalArg(parsed, "key");
+  const value = optionalArg(parsed, "value");
+  const forceJson = flagArg(parsed, "json");
+
+  if (!key) {
+    printResult(configSummary(config), renderConfig);
+    return;
+  }
+
+  if (value === undefined) {
+    const currentValue = getConfigValue(config, key);
+    const redactedValue = redactConfigValue(key, currentValue);
+    if (forceJson || typeof currentValue !== "string") {
+      printResult({ key, value: redactedValue }, renderConfig);
+      return;
+    }
+    printResult(String(redactedValue), renderConfig);
+    return;
+  }
+
+  const nextConfig = setConfigValue(config, key, value);
+  saveConfig(nextConfig);
+  printResult(
+    { key, value: redactConfigValue(key, getConfigValue(nextConfig, key)) },
+    renderConfig,
+  );
+}

package/src/commands/cos-upload.ts

@@ -0,0 +1,62 @@
+import { optionalArg, parseArgs, requireArg } from "../args";
+import { loadConfig } from "../config";
+import { printHelp, printResult } from "../output";
+import { uploadFileToCos, type CosUploadResult } from "../providers/cos";
+
+type CosUploader = (input: {
+  localPath: string;
+  folder: string;
+  baseUrl: string;
+  cosPat: string;
+  publicBaseUrl: string;
+}) => Promise<CosUploadResult>;
+
+export function createCosUploadCommand(uploader: CosUploader = uploadFileToCos) {
+  return async function cosUploadCommand(args: string[]): Promise<void> {
+    const parsed = parseArgs(args);
+
+    if (parsed.help) {
+      printHelp(`
+Usage: zzhub-pipeline cos-upload --file <path> [options]
+
+Options:
+  --file             Local image file path
+  --folder           COS folder name, e.g. notes/note-id
+  --alt              Markdown image alt text
+  --base-url         Hub base URL for COS STS, defaults to wx.baseUrl
+  --pat              COS PAT, defaults to cos.pat
+  --public-base-url  Public CDN base URL
+`.trim());
+      return;
+    }
+
+    const config = loadConfig();
+    const localPath = requireArg(parsed, "file", "local image file path");
+    const folder = optionalArg(parsed, "folder") || "uploads";
+    const baseUrl = optionalArg(parsed, "base-url") || config.cos.baseUrl || config.wx.baseUrl;
+    const cosPat = optionalArg(parsed, "pat") || config.cos.pat;
+    const publicBaseUrl = optionalArg(parsed, "public-base-url") || config.cos.publicBaseUrl;
+    const alt = optionalArg(parsed, "alt") || "";
+
+    if (!cosPat) {
+      throw new Error("No COS PAT configured. Set cos.pat in config or pass --pat.");
+    }
+
+    const result = await uploader({
+      localPath,
+      folder,
+      baseUrl,
+      cosPat,
+      publicBaseUrl,
+    });
+
+    printResult({
+      local_path: result.localPath,
+      key: result.key,
+      url: result.url,
+      markdown: `![${alt}](${result.url})`,
+    });
+  };
+}
+
+export const cosUpload = createCosUploadCommand();

package/src/commands/doctor.ts

@@ -0,0 +1,66 @@
+import { existsSync } from "fs";
+import { parseArgs, optionalArg } from "../args";
+import { printResult, renderDoctor } from "../output";
+import {
+  configSummary,
+  getPipelineConfigPath,
+  getLegacyZCliConfigPath,
+  loadConfig,
+  resolveWorkspaceRoot,
+  resolveWorkspacePaths,
+} from "../config";
+import { listPublishProviders } from "../providers";
+import { resolveBunBinary } from "../spawn";
+import { runPluginDoctorChecks } from "../adapter-loader";
+
+export async function doctor(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline doctor [options]
+
+Options:
+  --workspace  Workspace root to resolve default paths against
+`.trim());
+    return;
+  }
+
+  const config = loadConfig();
+  const workspace = resolveWorkspaceRoot(optionalArg(parsed, "workspace"), config);
+  const paths = resolveWorkspacePaths(workspace, config);
+
+  let bunBinary: string | null = null;
+  let bunError: string | null = null;
+
+  try {
+    bunBinary = resolveBunBinary();
+  } catch (error) {
+    bunError = error instanceof Error ? error.message : String(error);
+  }
+
+  const pluginChecks = await runPluginDoctorChecks(config);
+
+  printResult(
+    {
+      ...configSummary(config),
+      config_path_exists: existsSync(getPipelineConfigPath()),
+      legacy_config_path_exists: existsSync(getLegacyZCliConfigPath()),
+      workspace,
+      resolved_paths: paths,
+      resolved_paths_exist: {
+        postsRoot: existsSync(paths.postsRoot),
+        tempRoot: existsSync(paths.tempRoot),
+        blogRoot: existsSync(paths.blogRoot),
+        zotepadExportHtml: existsSync(paths.zotepadExportHtml),
+      },
+      bundled_imgx: true,
+      bundled_wechat_preview: true,
+      bun_binary: bunBinary,
+      bun_error: bunError,
+      publish_providers: listPublishProviders(),
+      plugin_checks: pluginChecks,
+    },
+    renderDoctor,
+  );
+}

package/src/commands/find-run.ts

@@ -0,0 +1,55 @@
+import { parseArgs, optionalArg } from "../args";
+import { printResult, renderTaskShape } from "../output";
+import { findTask } from "../task-manager";
+import { buildAgentTaskShape, parseTaskViewMode, renderTaskStatusMarkdown } from "../task-views";
+
+export async function findRun(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline find-run [options]
+
+Options:
+  --workspace       Workspace root (optional)
+  --run-id          Exact run id
+  --route           Primary route filter
+  --account         Account filter
+  --mode            Mode filter
+  --phase           Current phase filter
+  --title-contains  Match title substring
+  --active          Prefer only in-flight tasks
+  --full            Include the full state payload
+  --view            json | markdown | agent | agent-json (default: json)
+`.trim());
+    return;
+  }
+
+  const includeFull = parsed.full === true || parsed.full === "true";
+  const view = parseTaskViewMode(optionalArg(parsed, "view"));
+  const task = await findTask(optionalArg(parsed, "workspace"), {
+    run_id: optionalArg(parsed, "run-id"),
+    route: optionalArg(parsed, "route"),
+    account: optionalArg(parsed, "account"),
+    mode: optionalArg(parsed, "mode"),
+    phase: optionalArg(parsed, "phase"),
+    title_contains: optionalArg(parsed, "title-contains"),
+    active_only: parsed.active === true || parsed.active === "true",
+  });
+
+  if (!task) {
+    throw new Error("No matching task found");
+  }
+
+  if (view === "agent-json") {
+    console.log(JSON.stringify(buildAgentTaskShape(task), null, 2));
+    return;
+  }
+
+  if (view !== "json") {
+    console.log(renderTaskStatusMarkdown(task, view));
+    return;
+  }
+
+  printResult(includeFull ? task : task.summary, renderTaskShape);
+}