@zzclub/pipeline 0.2.0 → 0.4.0

package/src/adapters/builtin-markdown-renderer.ts

@@ -0,0 +1,63 @@
+/**
+ * Built-in markdown renderer adapter — wraps wechat-preview (exportMarkdownToWechatHtml).
+ *
+ * Implements MarkdownRenderPlugin interface. This is the default adapter used
+ * when no user-provided plugin is configured.
+ */
+
+import { exportMarkdownToWechatHtml } from "../wechat-preview";
+import { findChrome } from "../imgx/runtime";
+import type {
+  MarkdownRenderPlugin,
+  MarkdownRenderInput,
+  MarkdownRenderOutput,
+  PipelinePluginDoctorCheck,
+} from "../adapter-types";
+
+export const builtinMarkdownRenderer: MarkdownRenderPlugin = {
+  name: "builtin-wechat-preview",
+  version: "1.0.0",
+
+  async doctor(): Promise<PipelinePluginDoctorCheck[]> {
+    const checks: PipelinePluginDoctorCheck[] = [];
+
+    // Check Chrome/Chromium
+    const chromePath = findChrome();
+    if (chromePath) {
+      checks.push({ name: "chrome", ok: true, message: chromePath });
+    } else {
+      checks.push({
+        name: "chrome",
+        ok: false,
+        message:
+          "Chrome/Chromium not found. Required for WeChat HTML export.\n" +
+          "Install one of:\n" +
+          "  macOS:   brew install --cask chromium\n" +
+          "  Ubuntu:  sudo apt install chromium-browser\n" +
+          "  Or install Google Chrome from https://www.google.com/chrome/\n" +
+          "  Or set CHROME_PATH environment variable to the binary path.",
+      });
+    }
+
+    return checks;
+  },
+
+  async render(input: MarkdownRenderInput): Promise<MarkdownRenderOutput> {
+    const result = await exportMarkdownToWechatHtml({
+      markdownPath: input.markdownPath,
+      outPath: input.outPath,
+      account: input.account,
+      title: input.title,
+      previewShellOutPath: input.previewShellOutPath,
+      customCss: input.customCss,
+    });
+
+    return {
+      html: result.html,
+      htmlPath: result.htmlPath,
+      account: result.account,
+      previewStyle: result.previewStyle,
+      previewShellPath: result.previewShellPath,
+    };
+  },
+};

package/src/adapters/index.ts

@@ -0,0 +1,2 @@
+export { builtinImageRenderer } from "./builtin-image-renderer";
+export { builtinMarkdownRenderer } from "./builtin-markdown-renderer";

package/src/args.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, test } from "bun:test";
+import { parseArgs, requireArg, optionalArg, flagArg } from "./args";
+
+describe("parseArgs", () => {
+  test("handles --key value pairs", () => {
+    const parsed = parseArgs(["--state", "/path/to/file"]);
+    expect(parsed.state).toBe("/path/to/file");
+  });
+
+  test("handles --key=value form", () => {
+    const parsed = parseArgs(["--mode=content"]);
+    expect(parsed.mode).toBe("content");
+  });
+
+  test("handles boolean flags", () => {
+    const parsed = parseArgs(["--skip-render"]);
+    expect(parsed["skip-render"]).toBe(true);
+  });
+
+  test("handles --help", () => {
+    const parsed = parseArgs(["--help"]);
+    expect(parsed.help).toBe(true);
+  });
+
+  test("handles -h shorthand", () => {
+    const parsed = parseArgs(["-h"]);
+    expect(parsed.help).toBe(true);
+  });
+
+  test("normalizes underscores to hyphens", () => {
+    const parsed = parseArgs(["--requires_render", "true"]);
+    expect(parsed["requires-render"]).toBe("true");
+    expect(parsed["requires_render"]).toBe("true");
+  });
+
+  test("handles multiple arguments", () => {
+    const parsed = parseArgs(["--state", "/path", "--mode", "content", "--verbose"]);
+    expect(parsed.state).toBe("/path");
+    expect(parsed.mode).toBe("content");
+    expect(parsed.verbose).toBe(true);
+  });
+
+  test("collects positional arguments", () => {
+    const parsed = parseArgs(["positional1", "--state", "/path", "positional2"]);
+    const positional = JSON.parse(parsed._ as string) as string[];
+    expect(positional).toEqual(["positional1", "positional2"]);
+  });
+
+  test("handles empty args", () => {
+    const parsed = parseArgs([]);
+    expect(parsed.help).toBeUndefined();
+    expect(JSON.parse(parsed._ as string)).toEqual([]);
+  });
+
+  test("handles value that looks like a flag", () => {
+    const parsed = parseArgs(["--output", "--verbose"]);
+    expect(parsed.output).toBe(true);
+    expect(parsed.verbose).toBe(true);
+  });
+});
+
+describe("requireArg", () => {
+  test("returns string value when present", () => {
+    expect(requireArg({ state: "/path" }, "state", "state path")).toBe("/path");
+  });
+
+  test("throws for missing key", () => {
+    expect(() => requireArg({}, "state", "state path")).toThrow(
+      "Missing required argument: --state (state path)",
+    );
+  });
+
+  test("throws when value is boolean", () => {
+    expect(() => requireArg({ state: true }, "state", "state path")).toThrow(
+      "Missing required argument: --state (state path)",
+    );
+  });
+
+  test("throws when value is undefined", () => {
+    expect(() => requireArg({ state: undefined as unknown as string | boolean }, "state", "desc")).toThrow();
+  });
+});
+
+describe("optionalArg", () => {
+  test("returns string value when present", () => {
+    expect(optionalArg({ phase: "render" }, "phase")).toBe("render");
+  });
+
+  test("returns undefined for missing key", () => {
+    expect(optionalArg({}, "phase")).toBeUndefined();
+  });
+
+  test("returns undefined for boolean value", () => {
+    expect(optionalArg({ phase: true }, "phase")).toBeUndefined();
+  });
+});
+
+describe("flagArg", () => {
+  test("returns true for boolean true", () => {
+    expect(flagArg({ verbose: true }, "verbose")).toBe(true);
+  });
+
+  test("returns true for string 'true'", () => {
+    expect(flagArg({ verbose: "true" }, "verbose")).toBe(true);
+  });
+
+  test("returns false for missing key", () => {
+    expect(flagArg({}, "verbose")).toBe(false);
+  });
+
+  test("returns false for string 'false'", () => {
+    expect(flagArg({ verbose: "false" }, "verbose")).toBe(false);
+  });
+
+  test("returns false for other string values", () => {
+    expect(flagArg({ verbose: "yes" }, "verbose")).toBe(false);
+  });
+});

package/src/args.ts

@@ -0,0 +1,90 @@
+/**
+ * args.ts — Minimal argument parser for CLI subcommands.
+ * Uses Bun-native parseArgs when available, falls back to manual parsing.
+ */
+
+/**
+ * Parse CLI arguments into a key-value map.
+ * Supports: --key value, --key=value, --flag (boolean true)
+ */
+export function parseArgs(args: string[]): Record<string, string | boolean> {
+  const result: Record<string, string | boolean> = { _: "" };
+  let i = 0;
+  const positional: string[] = [];
+
+  const assignArg = (rawKey: string, value: string | boolean) => {
+    const normalizedKey = rawKey.replaceAll("_", "-");
+    result[normalizedKey] = value;
+    if (normalizedKey !== rawKey) {
+      result[rawKey] = value;
+    }
+  };
+
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg === "--help" || arg === "-h") {
+      result.help = true;
+      i++;
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      const eqIdx = arg.indexOf("=");
+      if (eqIdx !== -1) {
+        // --key=value
+        assignArg(arg.slice(2, eqIdx), arg.slice(eqIdx + 1));
+      } else if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+        // --key value
+        assignArg(arg.slice(2), args[i + 1]);
+        i++;
+      } else {
+        // --flag (boolean)
+        assignArg(arg.slice(2), true);
+      }
+    } else {
+      positional.push(arg);
+    }
+    i++;
+  }
+
+  result._ = JSON.stringify(positional);
+  return result;
+}
+
+/**
+ * Require a string argument, throw if missing.
+ */
+export function requireArg(
+  parsed: Record<string, string | boolean>,
+  key: string,
+  description: string,
+): string {
+  const val = parsed[key];
+  if (val === undefined || typeof val === "boolean") {
+    throw new Error(`Missing required argument: --${key} (${description})`);
+  }
+  return val;
+}
+
+/**
+ * Get optional string argument.
+ */
+export function optionalArg(
+  parsed: Record<string, string | boolean>,
+  key: string,
+): string | undefined {
+  const val = parsed[key];
+  if (val === undefined || typeof val === "boolean") return undefined;
+  return val;
+}
+
+/**
+ * Get boolean flag.
+ */
+export function flagArg(
+  parsed: Record<string, string | boolean>,
+  key: string,
+): boolean {
+  return parsed[key] === true || parsed[key] === "true";
+}

package/src/cli.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env bun
+
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { formatUsage, getCommandRegistry } from "./plugins";
+
+const COMMANDS = getCommandRegistry();
+
+function printVersion() {
+  const scriptDir = dirname(fileURLToPath(import.meta.url));
+  const pkgPath = join(scriptDir, "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  console.log(pkg.version);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+
+  if (!cmd || cmd === "--help" || cmd === "-h") {
+    printUsage();
+    process.exit(0);
+  }
+
+  if (cmd === "--version" || cmd === "-V") {
+    printVersion();
+    process.exit(0);
+  }
+
+  const command = COMMANDS[cmd];
+  if (!command) {
+    console.error(`Unknown command: ${cmd}`);
+    printUsage();
+    process.exit(1);
+  }
+
+  try {
+    await command.handler(args.slice(1));
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[zzhub-pipeline ${cmd}] Error: ${msg}`);
+    process.exit(1);
+  }
+}
+
+function printUsage() {
+  console.log(formatUsage());
+}
+
+main();

package/src/commands/abandon.test.ts

@@ -0,0 +1,104 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import { tmpdir } from "os";
+
+import { abandon } from "./abandon";
+import { defaultState, readState, writeState } from "../state";
+
+const TEST_CONFIG_PATH = join(tmpdir(), `zzhub-pipeline-test-config-abandon-${process.pid}.json`);
+process.env.ZZHUB_PIPELINE_CONFIG = TEST_CONFIG_PATH;
+
+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;
+}
+
+beforeEach(async () => {
+  await writeFile(TEST_CONFIG_PATH, "{}", "utf-8");
+});
+
+describe("abandon", () => {
+  test("abandon by --state sets mode to abandoned", async () => {
+    const workspace = await makeTempDir("zzhub-abandon-state-");
+    const statePath = join(workspace, "state.json");
+
+    const state = defaultState();
+    state.workspace_root = workspace;
+    state.state_path = statePath;
+    state.run_id = "run-abandon-1";
+    state.metadata.title = "To Abandon";
+    await writeState(statePath, state);
+
+    const output = await captureJsonOutput<Array<{ run_id: string; ok: boolean }>>(() =>
+      abandon(["--state", statePath]),
+    );
+
+    expect(output).toHaveLength(1);
+    expect(output[0].run_id).toBe("run-abandon-1");
+    expect(output[0].ok).toBe(true);
+
+    const updated = await readState(statePath);
+    expect(updated.mode).toBe("abandoned");
+  });
+
+  test("abandon by --run-id finds and abandons the correct task", async () => {
+    const workspace = await makeTempDir("zzhub-abandon-runid-");
+    const runRoot = join(workspace, ".zzhub-media", "runs");
+    await mkdir(runRoot, { recursive: true });
+
+    const statePath1 = join(runRoot, "run-keep.json");
+    const statePath2 = join(runRoot, "run-drop.json");
+
+    const state1 = defaultState();
+    state1.run_id = "run-keep";
+    state1.workspace_root = workspace;
+    state1.state_path = statePath1;
+    state1.metadata.title = "Keep";
+    await writeState(statePath1, state1);
+
+    const state2 = defaultState();
+    state2.run_id = "run-drop";
+    state2.workspace_root = workspace;
+    state2.state_path = statePath2;
+    state2.metadata.title = "Drop";
+    await writeState(statePath2, state2);
+
+    const output = await captureJsonOutput<Array<{ run_id: string; ok: boolean }>>(() =>
+      abandon(["--workspace", workspace, "--run-id", "run-drop"]),
+    );
+
+    expect(output).toHaveLength(1);
+    expect(output[0].run_id).toBe("run-drop");
+    expect(output[0].ok).toBe(true);
+
+    const kept = await readState(statePath1);
+    expect(kept.mode).toBe("active");
+
+    const dropped = await readState(statePath2);
+    expect(dropped.mode).toBe("abandoned");
+  });
+
+  test("abandon with non-existent --run-id throws", async () => {
+    const workspace = await makeTempDir("zzhub-abandon-miss-");
+    const runRoot = join(workspace, ".zzhub-media", "runs");
+    await mkdir(runRoot, { recursive: true });
+
+    expect(
+      abandon(["--workspace", workspace, "--run-id", "nonexistent"]),
+    ).rejects.toThrow("No task found with run_id: nonexistent");
+  });
+});

package/src/commands/abandon.ts

@@ -0,0 +1,202 @@
+/**
+ * abandon — Mark one or more tasks as abandoned.
+ *
+ * Non-interactive (Agent / script):
+ *   zzhub-pipeline abandon --run-id <id>
+ *   zzhub-pipeline abandon --state /path/to/workflow-state.json
+ *
+ * Interactive (TTY, no args):
+ *   zzhub-pipeline abandon
+ *   → Shows all active tasks. Space to toggle, Enter to confirm, q/Esc to cancel.
+ *
+ * Output: JSON list of { run_id, state_path, ok, error? }
+ */
+
+import * as readline from "readline";
+import { parseArgs, optionalArg } from "../args";
+import { printResult, renderAbandon } from "../output";
+import { filterActiveTasks, getTaskByStatePath, listTasks, type ListedTask } from "../task-manager";
+import { updateState } from "../state";
+
+// ── Result type ───────────────────────────────────────────────────────────────
+
+export interface AbandonResult {
+  run_id: string;
+  state_path: string;
+  ok: boolean;
+  error?: string;
+}
+
+// ── Core mutation ─────────────────────────────────────────────────────────────
+
+async function abandonTask(task: ListedTask): Promise<AbandonResult> {
+  const statePath = task.summary.state_path;
+  try {
+    await updateState(statePath, (state) => {
+      state.mode = "abandoned";
+    });
+    return { run_id: task.summary.run_id, state_path: statePath, ok: true };
+  } catch (err) {
+    return {
+      run_id: task.summary.run_id,
+      state_path: statePath,
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+// ── Interactive checkbox (raw TTY) ────────────────────────────────────────────
+
+interface CheckboxState {
+  items: ListedTask[];
+  selected: Set<number>;
+  cursor: number;
+}
+
+function renderCheckbox(state: CheckboxState): string {
+  const lines: string[] = [
+    "\x1b[1mAbandon tasks\x1b[0m  \x1b[2m(↑↓ move · space select · enter confirm · q cancel)\x1b[0m",
+    "",
+  ];
+  for (let i = 0; i < state.items.length; i++) {
+    const task = state.items[i];
+    const isCursor = i === state.cursor;
+    const isSelected = state.selected.has(i);
+    const box = isSelected ? "\x1b[31m[✗]\x1b[0m" : "\x1b[2m[ ]\x1b[0m";
+    const title = task.summary.metadata.title ?? task.summary.run_id;
+    const id = `\x1b[2m${task.summary.run_id}\x1b[0m`;
+    const prefix = isCursor ? "\x1b[36m▶\x1b[0m " : "  ";
+    lines.push(`${prefix}${box} ${title}  ${id}`);
+  }
+  if (state.items.length === 0) {
+    lines.push("  \x1b[2m(no active tasks)\x1b[0m");
+  }
+  return lines.join("\n");
+}
+
+function clearLines(count: number): void {
+  for (let i = 0; i < count; i++) {
+    process.stdout.write("\x1b[1A\x1b[2K");
+  }
+}
+
+async function runInteractive(items: ListedTask[]): Promise<ListedTask[]> {
+  if (items.length === 0) {
+    process.stdout.write("No active tasks to abandon.\n");
+    return [];
+  }
+
+  const state: CheckboxState = {
+    items,
+    selected: new Set(),
+    cursor: 0,
+  };
+
+  // Enter raw mode
+  const rl = readline.createInterface({ input: process.stdin });
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+
+  let rendered = renderCheckbox(state);
+  process.stdout.write(rendered + "\n");
+  let lineCount = rendered.split("\n").length;
+
+  return new Promise<ListedTask[]>((resolve) => {
+    process.stdin.on("data", (chunk: Buffer) => {
+      const key = chunk.toString();
+
+      if (key === "\x1b[A" || key === "k") {
+        state.cursor = Math.max(0, state.cursor - 1);
+      } else if (key === "\x1b[B" || key === "j") {
+        state.cursor = Math.min(items.length - 1, state.cursor + 1);
+      } else if (key === " ") {
+        if (state.selected.has(state.cursor)) {
+          state.selected.delete(state.cursor);
+        } else {
+          state.selected.add(state.cursor);
+        }
+      } else if (key === "\r" || key === "\n") {
+        cleanup();
+        const chosen = [...state.selected].map((i) => items[i]);
+        resolve(chosen);
+        return;
+      } else if (key === "q" || key === "\x03") {
+        cleanup();
+        resolve([]);
+        return;
+      } else if (key === "\x1b") {
+        return;
+      } else {
+        return;
+      }
+
+      clearLines(lineCount);
+      rendered = renderCheckbox(state);
+      process.stdout.write(rendered + "\n");
+      lineCount = rendered.split("\n").length;
+    });
+
+    function cleanup(): void {
+      process.stdin.setRawMode(false);
+      rl.close();
+    }
+  });
+}
+
+// ── Command entry point ───────────────────────────────────────────────────────
+
+export async function abandon(args: string[]): Promise<void> {
+  const parsed = parseArgs(args);
+
+  if (parsed.help) {
+    console.log(`
+Usage: zzhub-pipeline abandon [options]
+
+Without options (interactive TTY):
+  Lists all active tasks. Use ↑↓ to move, space to select,
+  enter to confirm abandonment, q/Esc to cancel.
+
+Options:
+  --run-id    Run ID of the task to abandon
+  --state     Path to the workflow-state.json to abandon
+  --workspace Workspace root (used when listing tasks interactively)
+`.trim());
+    return;
+  }
+
+  const runId = optionalArg(parsed, "run-id");
+  const statePath = optionalArg(parsed, "state");
+  const workspace = optionalArg(parsed, "workspace");
+
+  // ── Non-interactive: direct task identification ───────────────────────────
+  if (runId || statePath) {
+    let task: ListedTask;
+    if (statePath) {
+      task = await getTaskByStatePath(statePath);
+    } else {
+      const all = await listTasks(workspace);
+      const found = all.find((t) => t.summary.run_id === runId);
+      if (!found) {
+        throw new Error(`No task found with run_id: ${runId}`);
+      }
+      task = found;
+    }
+    const result = await abandonTask(task);
+    printResult([result], renderAbandon);
+    return;
+  }
+
+  // ── Interactive: TTY checkbox ─────────────────────────────────────────────
+  const all = await listTasks(workspace);
+  const active = filterActiveTasks(all);
+  const chosen = await runInteractive(active);
+
+  if (chosen.length === 0) {
+    process.stdout.write("No tasks abandoned.\n");
+    return;
+  }
+
+  const results = await Promise.all(chosen.map(abandonTask));
+  printResult(results, renderAbandon);
+}