@zzclub/pipeline 0.10.0 → 0.10.2

package/src/commands/wechat-export.ts

@@ -1,13 +1,15 @@
-import { optionalArg, parseArgs, requireArg } from "../args";
+import { spawn } from "child_process";
+import { resolve } from "path";
+import { flagArg, optionalArg, parseArgs, requireArg } from "../args";
 import { printResult, renderWechatExport } from "../output";
-import { loadConfig } from "../config";
+import { loadConfig, resolveConfigRelativePath } from "../config";
 import { resolveMarkdownRenderer } from "../adapter-loader";
+import { WechatExportError } from "../wechat-preview";
+import { registerPreviewEntry } from "../wechat-preview/server";
 
 const CSS_DEMO = `
-Custom CSS is injected as a <style> tag after the built-in Milkdown styles
-and before the browser renders. WeChat requires inline styles, so the
-rendering pipeline captures computed styles from the DOM — your CSS
-cascades naturally and the final inline-styled HTML will reflect it.
+Custom CSS is cascaded after the built-in theme and converted to conservative
+inline styles. Use semantic selectors or stable data-wechat-node hooks.
 
 Example custom.css:
 
@@ -26,6 +28,32 @@ Example custom.css:
   }
 `.trim();
 
+export function resolveWechatExportCustomCss(
+  cliCustomCss: string | undefined,
+  accountCustomCss: string | null | undefined,
+  cwd: string = process.cwd(),
+  configPath?: string,
+): string | null {
+  return cliCustomCss
+    ? resolve(cwd, cliCustomCss)
+    : resolveConfigRelativePath(accountCustomCss, configPath);
+}
+
+async function openUrl(url: string): Promise<void> {
+  const opener =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "cmd"
+        : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(opener, args, { detached: true, stdio: "ignore" }).unref();
+  } catch {
+    // non-fatal
+  }
+}
+
 export async function wechatExport(args: string[]): Promise<void> {
   const parsed = parseArgs(args);
 
@@ -38,8 +66,14 @@ Options:
   --out                Path to exported html file (required)
   --account            Account/theme key (optional; default: default)
   --title              Page title for the render shell (optional)
-  --preview-shell-out  Path to full Milkdown preview html (optional)
-  --custom-css         Path to custom CSS file for style overrides (optional)
+  --preview-shell-out  Path to exact final-HTML preview (optional)
+  --custom-css         CSS override path; replaces account customCss (optional)
+  --timeout-ms         Chrome virtual-time-budget in ms (default: 15000)
+  --debug-dir          Write intermediate artifacts for debugging (optional)
+  --preview            Register result with local preview server (default: true)
+  --no-preview         Do not register with preview server
+  --preview-auto-start Auto-start preview server if needed (default: true)
+  --open               Open preview URL in browser after export
 
 ${CSS_DEMO}
 `.trim());
@@ -51,20 +85,122 @@ ${CSS_DEMO}
   const account = optionalArg(parsed, "account") ?? "default";
   const title = optionalArg(parsed, "title");
   const previewShellOutPath = optionalArg(parsed, "preview-shell-out");
-  const customCss = optionalArg(parsed, "custom-css");
+  const cliCustomCss = optionalArg(parsed, "custom-css");
+  const timeoutRaw = optionalArg(parsed, "timeout-ms");
+  const timeoutMs = timeoutRaw ? Number(timeoutRaw) : undefined;
+  const debugDir = optionalArg(parsed, "debug-dir");
+  const noPreview = flagArg(parsed, "no-preview");
+  // Default true unless --no-preview or --preview=false
+  const previewExplicit = parsed.preview;
+  const preview =
+    !noPreview &&
+    previewExplicit !== false &&
+    previewExplicit !== "false";
+  const previewAutoStartExplicit = parsed["preview-auto-start"];
+  const previewAutoStart =
+    previewAutoStartExplicit !== false &&
+    previewAutoStartExplicit !== "false";
+  const open = flagArg(parsed, "open");
 
   const config = loadConfig();
   const wxAccount = config.wx.accounts[account] ?? config.wx.accounts[config.wx.defaultAccount];
+  const customCss = resolveWechatExportCustomCss(
+    cliCustomCss,
+    wxAccount?.customCss,
+  );
   const markdownRenderer = await resolveMarkdownRenderer(config);
-  const result = await markdownRenderer.render({
-    markdownPath,
-    outPath,
-    account,
-    title,
-    previewShellOutPath,
-    customCss,
-    themeOverrides: wxAccount?.theme,
-  });
-
-  printResult(result, renderWechatExport);
+
+  const displayTitle = title ?? "Wechat Preview Export";
+
+  try {
+    const result = await markdownRenderer.render({
+      markdownPath,
+      outPath,
+      account,
+      title,
+      previewShellOutPath,
+      customCss,
+      themeOverrides: wxAccount?.theme,
+      timeoutMs: timeoutMs !== undefined && Number.isFinite(timeoutMs) ? timeoutMs : undefined,
+      debugDir: debugDir ? resolve(process.cwd(), debugDir) : undefined,
+    });
+
+    let preview_url: string | undefined;
+    let preview_dashboard_url: string | undefined;
+    let preview_register_error: string | undefined;
+
+    if (preview) {
+      const reg = await registerPreviewEntry(
+        {
+          title: displayTitle,
+          account: result.account,
+          status: "success",
+          duration_ms: result.durationMs ?? 0,
+          markdown_path: resolve(process.cwd(), markdownPath),
+          html_path: result.htmlPath,
+          preview_style: result.previewStyle,
+          html: result.html,
+          debug: {
+            bundle_rebuilt: result.bundleRebuilt,
+            bundle_stale: result.bundleStale,
+            debug_dir: result.debugDir,
+          },
+        },
+        { autoStart: previewAutoStart },
+      );
+      if (reg.ok) {
+        preview_url = reg.preview_url;
+        preview_dashboard_url = reg.dashboard_url;
+        if (open && preview_url) await openUrl(preview_url);
+      } else {
+        preview_register_error = reg.error;
+      }
+    }
+
+    // Keep semanticHtml out of default CLI output (large); it still lands in --debug-dir.
+    const { semanticHtml: _semanticHtml, ...resultRest } = result;
+    printResult(
+      {
+        ...resultRest,
+        preview_url,
+        preview_dashboard_url,
+        preview_register_error,
+      },
+      renderWechatExport,
+    );
+  } catch (error) {
+    if (preview && error instanceof WechatExportError) {
+      const reg = await registerPreviewEntry(
+        {
+          title: error.title ?? displayTitle,
+          account: error.account,
+          status: "failed",
+          duration_ms: error.durationMs,
+          markdown_path: error.markdownPath,
+          error: error.message,
+          error_kind: error.kind,
+          debug: error.debug,
+        },
+        { autoStart: previewAutoStart },
+      );
+      if (reg.ok) {
+        printResult(
+          {
+            ok: false,
+            error: error.message,
+            error_kind: error.kind,
+            duration_ms: error.durationMs,
+            debug: error.debug,
+            preview_url: reg.preview_url,
+            preview_dashboard_url: reg.dashboard_url,
+          },
+          renderWechatExport,
+        );
+        if (open && reg.preview_url) await openUrl(reg.preview_url);
+        process.exitCode = 1;
+        return;
+      }
+    }
+    throw error;
+  }
 }

package/src/commands/wechat-preview.ts

@@ -0,0 +1,160 @@
+import { spawn } from "child_process";
+import { flagArg, optionalArg, parseArgs } from "../args";
+import { printResult } from "../output";
+import {
+  clearPreviewEntries,
+  getPreviewServerStatus,
+  listPreviewEntries,
+  resolvePreviewHost,
+  resolvePreviewPort,
+  startPreviewServer,
+} from "../wechat-preview/server";
+
+async function openUrl(url: string): Promise<void> {
+  const opener =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "cmd"
+        : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    spawn(opener, args, { detached: true, stdio: "ignore" }).unref();
+  } catch {
+    // non-fatal
+  }
+}
+
+function printHelp(): void {
+  console.log(`
+Usage: zzhub-pipeline wechat-preview <subcommand> [options]
+
+Subcommands:
+  serve     Start the singleton local preview server (or print existing URL)
+  status    Show whether the preview server is running
+  open      Open the dashboard in a browser
+  list      List registered preview entries
+  clear     Clear all preview entries
+
+serve options:
+  --host    Bind host (default: 127.0.0.1, env ZZHUB_WECHAT_PREVIEW_HOST)
+  --port    Bind port (default: 18765, env ZZHUB_WECHAT_PREVIEW_PORT)
+  --open    Open the dashboard after start
+  --force   Fail if a server is already running (default: reuse existing)
+
+Environment:
+  ZZHUB_WECHAT_PREVIEW_DIR   Data/lock directory override
+`.trim());
+}
+
+export async function wechatPreview(args: string[]): Promise<void> {
+  const sub = args[0];
+  const rest = args.slice(1);
+  const parsed = parseArgs(rest);
+
+  if (!sub || sub === "help" || sub === "--help" || parsed.help) {
+    printHelp();
+    return;
+  }
+
+  if (sub === "serve") {
+    const host = optionalArg(parsed, "host");
+    const portRaw = optionalArg(parsed, "port");
+    const port = portRaw ? Number(portRaw) : undefined;
+    const open = flagArg(parsed, "open");
+    const force = flagArg(parsed, "force");
+
+    const result = await startPreviewServer({
+      host,
+      port: port !== undefined && Number.isFinite(port) ? port : undefined,
+      open,
+      reuseExisting: !force,
+    });
+
+    if (open) {
+      await openUrl(result.url);
+    }
+
+    printResult({
+      action: "serve",
+      url: result.url,
+      host: result.host,
+      port: result.port,
+      reused: result.reused,
+      message: result.reused
+        ? `Already running at ${result.url}`
+        : `Listening on ${result.url}`,
+    });
+
+    // Keep process alive when we own the server
+    if (!result.reused) {
+      await new Promise<void>(() => {
+        // blocked until SIGINT/SIGTERM
+      });
+    }
+    return;
+  }
+
+  if (sub === "status") {
+    const host = optionalArg(parsed, "host");
+    const portRaw = optionalArg(parsed, "port");
+    const port = portRaw ? Number(portRaw) : undefined;
+    const status = await getPreviewServerStatus({
+      host: host ?? resolvePreviewHost(),
+      port: port !== undefined && Number.isFinite(port) ? port : resolvePreviewPort(),
+    });
+    printResult({ action: "status", ...status });
+    return;
+  }
+
+  if (sub === "open") {
+    const status = await getPreviewServerStatus();
+    if (!status.running || !status.url) {
+      throw new Error(
+        "WeChat preview server is not running. Start with: wechat-preview serve",
+      );
+    }
+    await openUrl(status.url);
+    printResult({ action: "open", url: status.url });
+    return;
+  }
+
+  if (sub === "list") {
+    const status = await getPreviewServerStatus();
+    if (status.running) {
+      // Prefer live server list
+      try {
+        const res = await fetch(`${status.url}/api/entries`);
+        if (res.ok) {
+          printResult({ action: "list", entries: await res.json() });
+          return;
+        }
+      } catch {
+        // fall through to disk
+      }
+    }
+    printResult({ action: "list", entries: listPreviewEntries(), source: "disk" });
+    return;
+  }
+
+  if (sub === "clear") {
+    const status = await getPreviewServerStatus();
+    if (status.running && status.url) {
+      try {
+        const res = await fetch(`${status.url}/api/entries`, { method: "DELETE" });
+        if (res.ok) {
+          const body = (await res.json()) as { cleared?: number };
+          printResult({ action: "clear", cleared: body.cleared ?? 0, via: "server" });
+          return;
+        }
+      } catch {
+        // fall through
+      }
+    }
+    const cleared = clearPreviewEntries();
+    printResult({ action: "clear", cleared, via: "disk" });
+    return;
+  }
+
+  throw new Error(`Unknown wechat-preview subcommand: ${sub}`);
+}

package/src/config.ts

@@ -85,6 +85,18 @@ export function getPipelineConfigPath(): string {
   return join(getBaseConfigDir(PIPELINE_CONFIG_DIR), PIPELINE_CONFIG_FILE);
 }
 
+/** Resolve a file path stored in config relative to the config file directory. */
+export function resolveConfigRelativePath(
+  value: string | null | undefined,
+  configPath: string = getPipelineConfigPath(),
+): string | null {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  return isAbsolute(trimmed)
+    ? resolve(trimmed)
+    : resolve(dirname(configPath), trimmed);
+}
+
 export function getLegacyZCliConfigPath(): string {
   return join(getBaseConfigDir(LEGACY_ZCLI_CONFIG_DIR), PIPELINE_CONFIG_FILE);
 }

package/src/imgx/runtime.ts

@@ -304,10 +304,30 @@ export function screenshotHtml(options: {
   rmSync(tempShotDir, { recursive: true, force: true });
 }
 
+export class ChromeDumpError extends Error {
+  readonly stderr: string;
+  readonly tempHtmlPath?: string;
+  readonly exitCode: number | null;
+
+  constructor(message: string, options: {
+    stderr: string;
+    tempHtmlPath?: string;
+    exitCode: number | null;
+  }) {
+    super(message);
+    this.name = "ChromeDumpError";
+    this.stderr = options.stderr;
+    this.tempHtmlPath = options.tempHtmlPath;
+    this.exitCode = options.exitCode;
+  }
+}
+
 export function dumpHtmlDom(options: {
   chromePath: string;
   html: string;
   virtualTimeBudgetMs?: number;
+  /** When true, leave the temp shell HTML on disk if Chrome fails (caller must clean up). */
+  keepTempOnError?: boolean;
 }): string {
   const tempHtml = writeTempHtml(injectStaticRenderStyle(options.html));
   const fileUrl = pathToFileURL(tempHtml).href;
@@ -329,12 +349,20 @@ export function dumpHtmlDom(options: {
     stdout: "pipe",
     stderr: "pipe",
   });
-  cleanupTempFile(tempHtml);
   if (result.exitCode !== 0) {
     const stderr = new TextDecoder().decode(result.stderr);
-    throw new Error(`Chrome dump-dom failed:\n${stderr}`);
+    if (!options.keepTempOnError) {
+      cleanupTempFile(tempHtml);
+    }
+    throw new ChromeDumpError(`Chrome dump-dom failed (exit ${result.exitCode}):\n${stderr}`, {
+      stderr,
+      tempHtmlPath: options.keepTempOnError ? tempHtml : undefined,
+      exitCode: result.exitCode,
+    });
   }
-  return new TextDecoder().decode(result.stdout);
+  const dom = new TextDecoder().decode(result.stdout);
+  cleanupTempFile(tempHtml);
+  return dom;
 }
 
 export function cropTop(options: {

package/src/logger.test.ts

@@ -0,0 +1,56 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getDailyLogPath, getLogDir, runWithCommandLog } from "./logger";
+
+describe("pipeline daily logger", () => {
+  const previousLogDir = process.env.ZZHUB_PIPELINE_LOG_DIR;
+  let tempDir: string | null = null;
+
+  afterEach(() => {
+    if (previousLogDir === undefined) {
+      delete process.env.ZZHUB_PIPELINE_LOG_DIR;
+    } else {
+      process.env.ZZHUB_PIPELINE_LOG_DIR = previousLogDir;
+    }
+    if (tempDir) {
+      rmSync(tempDir, { recursive: true, force: true });
+      tempDir = null;
+    }
+  });
+
+  test("writes command start/ok markers and console output to the daily log", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "zzhub-pipeline-log-"));
+    process.env.ZZHUB_PIPELINE_LOG_DIR = tempDir;
+
+    await runWithCommandLog("status", ["--state", "/tmp/x.json"], async () => {
+      console.log("hello-from-status");
+    });
+
+    const logPath = getDailyLogPath();
+    expect(getLogDir()).toBe(tempDir);
+    expect(existsSync(logPath)).toBe(true);
+    const body = readFileSync(logPath, "utf-8");
+    expect(body).toContain("=== START command=status ===");
+    expect(body).toContain("=== OK command=status");
+    expect(body).toContain("[console.log] hello-from-status");
+    expect(body).toContain(`"--state"`);
+  });
+
+  test("records failure stack and rethrows", async () => {
+    tempDir = mkdtempSync(join(tmpdir(), "zzhub-pipeline-log-"));
+    process.env.ZZHUB_PIPELINE_LOG_DIR = tempDir;
+
+    await expect(
+      runWithCommandLog("publish", [], async () => {
+        throw new Error("boom-upload");
+      }),
+    ).rejects.toThrow("boom-upload");
+
+    const body = readFileSync(getDailyLogPath(), "utf-8");
+    expect(body).toContain("=== FAIL command=publish");
+    expect(body).toContain("Error: boom-upload");
+    expect(body).toContain("boom-upload");
+  });
+});

package/src/logger.ts

@@ -0,0 +1,178 @@
+/**
+ * Daily rolling file logger for zzhub-pipeline CLI commands.
+ *
+ * Layout (platform-aware, same base as wechat-preview config dir):
+ *   macOS:  ~/Library/Application Support/zzhub-pipeline/logs/pipeline-YYYY-MM-DD.log
+ *   Linux:  ~/.config/zzhub-pipeline/logs/pipeline-YYYY-MM-DD.log
+ *   Windows: %APPDATA%/zzhub-pipeline/logs/pipeline-YYYY-MM-DD.log
+ *
+ * Override with ZZHUB_PIPELINE_LOG_DIR.
+ */
+
+import { appendFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+
+const APP_DIR = "zzhub-pipeline";
+const LOG_DIR_NAME = "logs";
+const LOG_PREFIX = "pipeline-";
+const LOG_SUFFIX = ".log";
+/** Keep about two weeks of daily files. */
+const LOG_RETENTION_DAYS = 14;
+
+function getBaseConfigDir(): string {
+  const home = homedir();
+  const currentPlatform = platform();
+
+  if (currentPlatform === "win32") {
+    const appData = process.env.APPDATA;
+    if (appData) return join(appData, APP_DIR);
+    return join(home, "AppData", "Roaming", APP_DIR);
+  }
+
+  if (currentPlatform === "darwin") {
+    return join(home, "Library", "Application Support", APP_DIR);
+  }
+
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  if (xdgConfigHome && xdgConfigHome.trim().length > 0) {
+    return join(xdgConfigHome, APP_DIR);
+  }
+
+  return join(home, ".config", APP_DIR);
+}
+
+export function getLogDir(): string {
+  const override = process.env.ZZHUB_PIPELINE_LOG_DIR?.trim();
+  if (override) return override;
+  return join(getBaseConfigDir(), LOG_DIR_NAME);
+}
+
+function formatDateKey(date: Date = new Date()): string {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}
+
+export function getDailyLogPath(date: Date = new Date()): string {
+  return join(getLogDir(), `${LOG_PREFIX}${formatDateKey(date)}${LOG_SUFFIX}`);
+}
+
+function ensureLogDir(): string {
+  const dir = getLogDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+function pruneOldLogs(dir: string): void {
+  try {
+    const cutoff = Date.now() - LOG_RETENTION_DAYS * 24 * 60 * 60 * 1000;
+    for (const name of readdirSync(dir)) {
+      if (!name.startsWith(LOG_PREFIX) || !name.endsWith(LOG_SUFFIX)) continue;
+      const key = name.slice(LOG_PREFIX.length, -LOG_SUFFIX.length);
+      // YYYY-MM-DD
+      if (!/^\d{4}-\d{2}-\d{2}$/.test(key)) continue;
+      const stamp = Date.parse(`${key}T00:00:00`);
+      if (!Number.isFinite(stamp) || stamp >= cutoff) continue;
+      unlinkSync(join(dir, name));
+    }
+  } catch {
+    // pruning is best-effort
+  }
+}
+
+export function appendLogLine(message: string, date: Date = new Date()): void {
+  try {
+    const dir = ensureLogDir();
+    pruneOldLogs(dir);
+    const path = getDailyLogPath(date);
+    const line = message.endsWith("\n") ? message : `${message}\n`;
+    appendFileSync(path, line, "utf-8");
+  } catch {
+    // never break CLI for logging failures
+  }
+}
+
+function formatError(err: unknown): string {
+  if (err instanceof Error) {
+    return `${err.name}: ${err.message}${err.stack ? `\n${err.stack}` : ""}`;
+  }
+  return String(err);
+}
+
+type ConsoleMethod = "log" | "info" | "warn" | "error" | "debug";
+
+function installConsoleTee(write: (chunk: string) => void): () => void {
+  const methods: ConsoleMethod[] = ["log", "info", "warn", "error", "debug"];
+  const originals = new Map<ConsoleMethod, (...args: unknown[]) => void>();
+
+  for (const method of methods) {
+    const original = console[method].bind(console);
+    originals.set(method, original);
+    console[method] = (...args: unknown[]) => {
+      original(...args);
+      try {
+        const text = args
+          .map((arg) => {
+            if (typeof arg === "string") return arg;
+            try {
+              return JSON.stringify(arg);
+            } catch {
+              return String(arg);
+            }
+          })
+          .join(" ");
+        write(`[console.${method}] ${text}`);
+      } catch {
+        // ignore
+      }
+    };
+  }
+
+  return () => {
+    for (const method of methods) {
+      const original = originals.get(method);
+      if (original) console[method] = original as typeof console.log;
+    }
+  };
+}
+
+/**
+ * Run a CLI command with daily-file logging.
+ * Captures console output, start/end markers, duration, and full error stacks.
+ */
+export async function runWithCommandLog(
+  command: string,
+  args: string[],
+  handler: () => Promise<void>,
+): Promise<void> {
+  const startedAt = new Date();
+  const startedMs = Date.now();
+  const logPath = getDailyLogPath(startedAt);
+  const write = (message: string) => {
+    appendLogLine(`[${new Date().toISOString()}] ${message}`, startedAt);
+  };
+
+  write(`=== START command=${command} ===`);
+  write(`log_file=${logPath}`);
+  write(`cwd=${process.cwd()}`);
+  write(`argv=${JSON.stringify(args)}`);
+  if (process.env.ZZHUB_PIPELINE_ROOT) {
+    write(`ZZHUB_PIPELINE_ROOT=${process.env.ZZHUB_PIPELINE_ROOT}`);
+  }
+
+  const restoreConsole = installConsoleTee(write);
+  try {
+    await handler();
+    write(`=== OK command=${command} duration_ms=${Date.now() - startedMs} ===`);
+  } catch (err) {
+    write(`=== FAIL command=${command} duration_ms=${Date.now() - startedMs} ===`);
+    write(formatError(err));
+    throw err;
+  } finally {
+    restoreConsole();
+  }
+}

package/src/plugins.ts

@@ -25,6 +25,7 @@ import { syncBlog } from "./commands/sync-blog";
 import { tasks } from "./commands/tasks";
 import { topic } from "./commands/topic";
 import { wechatExport } from "./commands/wechat-export";
+import { wechatPreview } from "./commands/wechat-preview";
 import { wxDrafts } from "./commands/wx-drafts";
 import { wxDraftDelete } from "./commands/wx-draft-delete";
 
@@ -71,6 +72,7 @@ export function getCommandPlugins(): CommandPlugin[] {
         { name: "republish", summary: "Publish completed task to additional accounts/platforms", plugin: "ops", handler: republish },
         { name: "imgx", summary: "Run bundled imgx renderer subcommands", plugin: "ops", handler: imgxCommand },
         { name: "wechat-export", summary: "Render markdown to WeChat HTML with bundled preview styles", plugin: "ops", handler: wechatExport },
+        { name: "wechat-preview", summary: "Local singleton server to preview exported WeChat HTML", plugin: "ops", handler: wechatPreview },
         { name: "cos-upload", summary: "Upload a local image to configured COS CDN", plugin: "ops", handler: cosUpload },
         { name: "config", summary: "Read or update pipeline config", plugin: "ops", handler: configCommand },
         { name: "doctor", summary: "Inspect resolved paths and provider health", plugin: "ops", handler: doctor },