zerocut-cli 0.1.0

package/dist/skill/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: "zerocut-cli-tools"
+description: "Use ZeroCut CLI media and document tools. Invoke when user needs generate media, run ffmpeg/pandoc, sync resources, or save outputs."
+---
+
+# ZeroCut CLI Tools
+
+## Purpose
+
+This skill provides a single reference for using ZeroCut CLI commands:
+- image generation
+- video generation
+- music generation
+- text-to-speech
+- ffmpeg sandbox execution
+- pandoc sandbox execution
+
+## When To Invoke
+
+Invoke this skill when the user asks to:
+- generate image, video, music, or speech audio
+- run ffmpeg or ffprobe command in sandbox
+- run pandoc conversion in sandbox
+- sync local/remote resources into sandbox
+- save generated results to local output files
+
+## Command Reference
+
+### image
+
+Default action: `create`
+
+```bash
+zerocut image --prompt "a cat on a bike" --output out.png
+zerocut image create --prompt "a cat on a bike" --model seedream-5l --aspectRatio 1:1 --resolution 1K --refs ref1.png,ref2.jpg --output out.png
+```
+
+Options:
+- `--prompt <prompt>` required
+- `--model <model>`
+- `--aspectRatio <ratio>`
+- `--resolution <resolution>`
+- `--refs <refs>` comma-separated local paths or URLs
+- `--output <file>` save generated file
+
+### video
+
+Default action: `create`
+
+```bash
+zerocut video --prompt "city night drive" --video vidu --duration 8 --output out.mp4
+zerocut video create --prompt "city night drive" --video vidu --aspectRatio 1:1 --refs ref1.png,ref2.png --output out.mp4
+```
+
+Options:
+- `--prompt <prompt>` required
+- `--video <model>`
+- `--duration <seconds>`
+- `--seed <seed>`
+- `--firstFrame <image>`
+- `--lastFrame <image>`
+- `--refs <assets>`
+- `--resolution <resolution>`
+- `--aspectRatio <ratio>`
+- `--withAudio`
+- `--optimizeCameraMotion`
+- `--output <file>`
+
+### music
+
+Default action: `create`
+
+```bash
+zerocut music --prompt "lofi beat" --output music.mp3
+zerocut music create --prompt "lofi beat" --output music.mp3
+```
+
+Options:
+- `--prompt <prompt>` required
+- `--output <file>`
+
+### tts
+
+Default action: `create`
+
+```bash
+zerocut tts --text "你好，欢迎使用 ZeroCut" --voiceId voice_xxx --output speech.mp3
+zerocut tts create --prompt "calm tone" --text "Hello world" --voiceId voice_xxx --output speech.mp3
+```
+
+Options:
+- `--prompt <prompt>`
+- `--text <text>` required
+- `--voiceId <voiceId>`
+- `--output <file>`
+
+### ffmpeg
+
+```bash
+zerocut ffmpeg --args -i input.mp4 -vn output.mp3 --resources input.mp4
+zerocut ffmpeg --args -i input.mp4 -vf scale=1280:720 output.mp4 --resources input.mp4
+```
+
+Options:
+- `--args <args...>` required, arguments appended after `ffmpeg`
+- `--resources <resources...>` optional, files/URLs to sync into sandbox materials
+
+Behavior:
+- command is validated to only allow `ffmpeg` or `ffprobe`
+- for `ffmpeg`, `-y` is auto-injected when absent
+- output file is auto-downloaded from sandbox to local current directory
+
+### pandoc
+
+```bash
+zerocut pandoc --args input.md -o output.pdf --resources input.md
+zerocut pandoc --args input.md --output=output.docx --resources input.md template.docx
+```
+
+Options:
+- `--args <args...>` required, arguments appended after `pandoc`
+- `--resources <resources...>` optional, files/URLs to sync into sandbox materials
+
+Behavior:
+- command is validated to only allow `pandoc`
+- output file must be specified in args with `-o`, `--output`, or `--output=...`
+- output file is auto-downloaded from sandbox to local current directory
+
+## Output And Sync Rules
+
+- Media URLs from generation are synced to TOS when available.
+- `--output` saves files to an absolute path resolved from current working directory.
+- Missing parent directories for `--output` are created automatically.

package/dist/types/command.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+export interface CommandModule {
+    name: string;
+    description?: string;
+    register: (program: Command) => void;
+}

package/dist/types/command.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/progress.d.ts

@@ -0,0 +1 @@
+export declare function createProgressSpinner(label?: string): () => void;

package/dist/utils/progress.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProgressSpinner = createProgressSpinner;
+function createProgressSpinner(label = "inferencing") {
+    const frames = ["|", "/", "-", "\\"];
+    let si = 0;
+    const t0 = Date.now();
+    return () => {
+        const f = frames[si++ % frames.length];
+        const sec = Math.floor((Date.now() - t0) / 1000);
+        process.stdout.write(`\r${f} ${label}... ${sec}s`);
+    };
+}

package/eslint.config.js

@@ -0,0 +1,30 @@
+const tsParser = require("@typescript-eslint/parser");
+const tsPlugin = require("@typescript-eslint/eslint-plugin");
+const prettierPlugin = require("eslint-plugin-prettier");
+
+module.exports = [
+  {
+    ignores: ["dist", "node_modules"],
+  },
+  {
+    files: ["**/*.ts"],
+    languageOptions: {
+      parser: tsParser,
+      parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: "commonjs",
+        project: "./tsconfig.json",
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tsPlugin,
+      prettier: prettierPlugin,
+    },
+    rules: {
+      ...tsPlugin.configs.recommended.rules,
+      "@typescript-eslint/no-unused-vars": "warn",
+      "@typescript-eslint/no-explicit-any": "warn",
+      "prettier/prettier": "error",
+    },
+  },
+];

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "zerocut-cli",
+  "version": "0.1.0",
+  "description": "ZeroCut CLI: AI assistant CLI for creating and editing images/audio/video",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "zerocut": "dist/bin/zerocut.js",
+    "zerocut-cli": "dist/bin/zerocut.js"
+  },
+  "keywords": [
+    "cli",
+    "zerocut"
+  ],
+  "author": "liubei-ai",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/liubei-ai/zerocut-cli.git"
+  },
+  "homepage": "https://github.com/liubei-ai/zerocut-cli#readme",
+  "bugs": {
+    "url": "https://github.com/liubei-ai/zerocut-cli/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0"
+  },
+  "dependencies": {
+    "cerevox": "^4.22.0",
+    "commander": "^14.0.3",
+    "inquirer": "^13.2.2"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-skill-md.cjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint . --ext .ts",
+    "format": "prettier --write .",
+    "dev": "ts-node src/bin/zerocut.ts"
+  }
+}

package/scripts/copy-skill-md.cjs

@@ -0,0 +1,8 @@
+const fs = require("node:fs");
+const path = require("node:path");
+
+const src = path.resolve(__dirname, "../src/skill/SKILL.md");
+const dest = path.resolve(__dirname, "../dist/skill/SKILL.md");
+
+fs.mkdirSync(path.dirname(dest), { recursive: true });
+fs.copyFileSync(src, dest);

package/src/bin/zerocut.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from "../cli";
+run(process.argv);

package/src/cli.ts

@@ -0,0 +1,25 @@
+import { Command } from "commander";
+import { loadBuiltInCommands, loadExternalCommandsAsync } from "./services/commandLoader";
+import { applyConfigInterceptor } from "./services/config";
+
+export function createProgram(): Command {
+  const program = new Command();
+  program.name("zerocut").description("Zerocut CLI");
+
+  loadBuiltInCommands(program);
+  applyConfigInterceptor(program);
+  return program;
+}
+
+export async function run(argv: string[]): Promise<void> {
+  const args = argv.slice(2);
+  const program = createProgram();
+  await loadExternalCommandsAsync(program);
+
+  if (args.length === 0) {
+    await program.parseAsync([argv[0] ?? "node", argv[1] ?? "zerocut", "help"]);
+    return;
+  }
+
+  await program.parseAsync(argv);
+}

package/src/commands/config.ts

@@ -0,0 +1,130 @@
+import type { Command } from "commander";
+import readline from "node:readline";
+import { readConfigSync, setConfigValueSync } from "../services/config";
+
+export const name = "config";
+export const description = "Configuration management";
+
+async function ask(question: string, defaults?: string): Promise<string> {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const q = defaults ? `${question} [${defaults}]: ` : `${question}: `;
+  const answer = await new Promise<string>((resolve) => rl.question(q, (ans) => resolve(ans)));
+  rl.close();
+  const trimmed = answer.trim();
+  return trimmed.length > 0 ? trimmed : (defaults ?? "");
+}
+
+export function register(program: Command): void {
+  const parent = program
+    .command("config")
+    .description("Configuration management: set key, projectDir, and region")
+    .option("--ott <token>", "One-Time Token (OTT) for fetching API key")
+    .option("--region <region>", "Region for OTT exchange: cn|us")
+    .action(async function (this: Command, opts: { ott?: string; region?: string }) {
+      const ott = typeof opts.ott === "string" ? opts.ott.trim() : "";
+      const region = typeof opts.region === "string" ? opts.region.trim().toLowerCase() : "";
+      if (!ott) return; // no quick params; fall through to subcommands normally
+      if (region !== "cn" && region !== "us") {
+        process.stderr.write("Invalid or missing --region. Allowed: cn|us\n");
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const base = region === "cn" ? "https://api2.zerocut.cn" : "https://api2.zerocut.art";
+        const resp = await fetch(`${base}/api/open/ott/exchange`, {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ ott }),
+        });
+        if (!resp.ok) {
+          process.stderr.write(`OTT exchange failed: HTTP ${resp.status}\n`);
+          process.exitCode = 1;
+          return;
+        }
+        const json = (await resp.json()) as { data?: { apiKey?: string } };
+        const apiKey = json?.data?.apiKey;
+        if (typeof apiKey !== "string" || apiKey.length === 0) {
+          process.stderr.write("OTT exchange failed: missing data.apiKey in response\n");
+          process.exitCode = 1;
+          return;
+        }
+        setConfigValueSync("apiKey", apiKey);
+        setConfigValueSync("region", region);
+        process.stdout.write("apiKey set via OTT\n");
+      } catch (err) {
+        process.stderr.write(`OTT exchange failed: ${(err as Error).message}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  parent
+    .command("key [key]")
+    .description(
+      "Set API key. If omitted, exchange via One-Time Token (OTT) after choosing region."
+    )
+    .action(async (key?: string) => {
+      const direct = typeof key === "string" ? key.trim() : "";
+      if (direct.length > 0) {
+        setConfigValueSync("apiKey", direct);
+        process.stdout.write("apiKey set\n");
+        return;
+      }
+      const region = (await ask("Choose region (cn/us)", "us")).trim().toLowerCase();
+      if (region !== "cn" && region !== "us") {
+        process.stderr.write("Invalid region. Allowed: cn|us\n");
+        process.exitCode = 1;
+        return;
+      }
+      const ott = (await ask("Enter One-Time Token (OTT)")).trim();
+      if (!ott) {
+        process.stderr.write("OTT is required when no apiKey is provided\n");
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const base = region === "cn" ? "https://api2.zerocut.cn" : "https://api2.zerocut.art";
+        const resp = await fetch(`${base}/api/open/ott/exchange`, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+          },
+          body: JSON.stringify({ ott }),
+        });
+        if (!resp.ok) {
+          process.stderr.write(`OTT exchange failed: HTTP ${resp.status}\n`);
+          process.exitCode = 1;
+          return;
+        }
+        const json = (await resp.json()) as {
+          data?: { apiKey?: string };
+          [k: string]: unknown;
+        };
+        const apiKey = json?.data?.apiKey;
+        if (typeof apiKey !== "string" || apiKey.length === 0) {
+          process.stderr.write("OTT exchange failed: missing data.apiKey in response\n");
+          process.exitCode = 1;
+          return;
+        }
+        setConfigValueSync("apiKey", apiKey);
+        setConfigValueSync("region", region);
+        process.stdout.write("apiKey set via OTT\n");
+      } catch (err) {
+        process.stderr.write(`OTT exchange failed: ${(err as Error).message}\n`);
+        process.exitCode = 1;
+      }
+    });
+
+  parent
+    .command("list")
+    .description("List current configuration values")
+    .action(() => {
+      const cfg = readConfigSync() as Record<string, unknown>;
+      const masked = { ...cfg } as Record<string, unknown>;
+      const k = masked.apiKey;
+      if (typeof k === "string" && k.length > 0) {
+        const visible = k.slice(-4);
+        masked.apiKey = `${"*".repeat(Math.max(0, k.length - 4))}${visible}`;
+      }
+      process.stdout.write(`${JSON.stringify(masked, null, 2)}\n`);
+    });
+}

package/src/commands/ffmpeg.ts

@@ -0,0 +1,37 @@
+import type { Command } from "commander";
+import { getSessionFromCommand, runFFMpegCommand } from "../services/cerevox";
+
+export const name = "ffmpeg";
+export const description = "Run ffmpeg in sandbox";
+
+export function register(program: Command): void {
+  program
+    .command("ffmpeg")
+    .description("Run ffmpeg command in sandbox")
+    .allowUnknownOption(true)
+    .option("--args <args...>", "Arguments passed to ffmpeg")
+    .option("--resources <resources...>", "Resource files/urls to sync into sandbox")
+    .action(async function (
+      this: Command,
+      opts: {
+        args?: string[];
+        resources?: string[];
+      }
+    ) {
+      const session = getSessionFromCommand(this as unknown as Record<symbol, unknown>);
+      if (!session) {
+        process.stderr.write("No active session\n");
+        return;
+      }
+      const args = Array.isArray(opts.args) ? opts.args : [];
+      if (args.length === 0) {
+        process.stderr.write("Missing required option: --args\n");
+        process.exitCode = 1;
+        return;
+      }
+      const command = `ffmpeg ${args.join(" ")}`;
+      const resources = Array.isArray(opts.resources) ? opts.resources : [];
+      const res = await runFFMpegCommand(session, command, resources);
+      console.log(res);
+    });
+}

package/src/commands/help.ts

@@ -0,0 +1,13 @@
+import type { Command } from "commander";
+
+export const name = "help";
+export const description = "Show help";
+
+export function register(program: Command): void {
+  program
+    .command("help")
+    .description("Show help")
+    .action(() => {
+      program.outputHelp();
+    });
+}

package/src/commands/image.ts

@@ -0,0 +1,194 @@
+import type { Command } from "commander";
+import fs from "node:fs";
+import path from "node:path";
+import { getMaterialUri, getSessionFromCommand, syncToTOS } from "../services/cerevox";
+import type { Session } from "cerevox";
+import { createProgressSpinner } from "../utils/progress";
+
+export const name = "image";
+export const description = "Image command: create image";
+
+export function register(program: Command): void {
+  const parent = program.command("image").description("Create a new image; requires --prompt");
+
+  const allowedModels = [
+    "seedream",
+    "seedream-pro",
+    "seedream-5l",
+    "banana",
+    "banana2",
+    "banana-pro",
+    "wan",
+  ] as const;
+  type AllowedModel = (typeof allowedModels)[number];
+  const allowedAspectRatios = [
+    "1:1",
+    "3:4",
+    "4:3",
+    "16:9",
+    "9:16",
+    "2:3",
+    "3:2",
+    "21:9",
+    "1:4",
+    "4:1",
+    "1:8",
+    "8:1",
+  ] as const;
+  type AllowedAspectRatio = (typeof allowedAspectRatios)[number];
+  const allowedResolutions = ["1K", "2K", "4K"] as const;
+  type AllowedResolution = (typeof allowedResolutions)[number];
+
+  async function performImageGeneration(
+    session: Session,
+    {
+      prompt,
+      model,
+      aspectRatio,
+      resolution,
+      refsList,
+      output,
+    }: {
+      prompt: string;
+      model?: AllowedModel;
+      aspectRatio?: AllowedAspectRatio;
+      resolution?: AllowedResolution;
+      refsList: string[];
+      output?: string;
+    }
+  ): Promise<void> {
+    const referenceImages = await Promise.all(
+      refsList.map(async (ref) => ({ url: await getMaterialUri(session, ref) }))
+    );
+    const onProgress = createProgressSpinner("inferencing");
+    const payload: Record<string, unknown> = {
+      model: model || "seedream-5l",
+      prompt,
+      aspect_ratio: aspectRatio,
+      resolution,
+      reference_images: referenceImages,
+      onProgress,
+    };
+    const res = await (session.ai.generateImage as (arg: Record<string, unknown>) => Promise<any>)(
+      payload
+    );
+    if (res?.urls && Array.isArray(res.urls) && res.urls.length > 0) {
+      try {
+        const tosUrl = await syncToTOS(res.urls[0]);
+        if (tosUrl) {
+          res.url = tosUrl;
+          res.urls[0] = tosUrl;
+        }
+      } catch {}
+    }
+    process.stdout.write("\n");
+    if (output) {
+      const dir = process.cwd();
+      const url = (res.url as string) ?? res.urls[0];
+      const response = await fetch(url);
+      const buffer = Buffer.from(await response.arrayBuffer());
+      const filePath = path.resolve(dir, output);
+      if (!fs.existsSync(path.dirname(filePath))) {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+      }
+      fs.writeFileSync(filePath, buffer);
+      res.output = filePath;
+    }
+    console.log(res);
+  }
+
+  async function imageCreateAction(
+    this: Command,
+    opts: {
+      prompt?: string;
+      model?: string;
+      aspectRatio?: string;
+      resolution?: string;
+      refs?: string;
+      output?: string;
+    }
+  ) {
+    const session = getSessionFromCommand(this as unknown as Record<symbol, unknown>);
+    if (!session) {
+      process.stderr.write("No active session\n");
+      return;
+    }
+    const prompt = typeof opts.prompt === "string" ? opts.prompt : undefined;
+    if (!prompt || prompt.trim().length === 0) {
+      process.stderr.write("Missing required option: --prompt\n");
+      process.exitCode = 1;
+      return;
+    }
+    const model = typeof opts.model === "string" ? opts.model.trim() : undefined;
+    if (model && !(allowedModels as readonly string[]).includes(model)) {
+      process.stderr.write(
+        `Invalid value for --model: ${model}. Allowed: ${allowedModels.join("|")}\n`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const modelArg: AllowedModel | undefined = (model ?? undefined) as AllowedModel | undefined;
+    const aspectRatio =
+      typeof opts.aspectRatio === "string"
+        ? (opts.aspectRatio.trim() as AllowedAspectRatio)
+        : undefined;
+    if (aspectRatio && !(allowedAspectRatios as readonly string[]).includes(aspectRatio)) {
+      process.stderr.write(
+        `Invalid value for --aspectRatio: ${aspectRatio}. Allowed: ${allowedAspectRatios.join("|")}\n`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const resolution =
+      typeof opts.resolution === "string"
+        ? (opts.resolution.trim() as AllowedResolution)
+        : undefined;
+    if (resolution && !(allowedResolutions as readonly string[]).includes(resolution)) {
+      process.stderr.write(
+        `Invalid value for --resolution: ${resolution}. Allowed: ${allowedResolutions.join("|")}\n`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const refsList =
+      typeof opts.refs === "string" && opts.refs.length > 0
+        ? opts.refs
+            .split(",")
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+        : [];
+    const output = typeof opts.output === "string" ? opts.output : undefined;
+    await performImageGeneration(session, {
+      prompt,
+      model: modelArg,
+      aspectRatio,
+      resolution,
+      refsList,
+      output,
+    });
+  }
+
+  // default action on `zerocut image`
+  parent
+    .option("--prompt <prompt>", "Text prompt for image generation (required)")
+    .option("--model <model>", `Generator model: ${allowedModels.join("|")}`)
+    .option("--aspectRatio <ratio>", `Aspect ratio: ${allowedAspectRatios.join("|")}`)
+    .option("--resolution <resolution>", `Resolution: ${allowedResolutions.join("|")}`)
+    .option("--refs <refs>", "Comma-separated reference image paths/urls")
+    .option("--output <file>", "Output file path")
+    .action(imageCreateAction);
+
+  // keep `image create` for compatibility
+  parent
+    .command("create")
+    .description("Create a new image; requires --prompt")
+    .option("--prompt <prompt>", "Text prompt for image generation (required)")
+    .option("--model <model>", `Generator model: ${allowedModels.join("|")}`)
+    .option("--aspectRatio <ratio>", `Aspect ratio: ${allowedAspectRatios.join("|")}`)
+    .option("--resolution <resolution>", `Resolution: ${allowedResolutions.join("|")}`)
+    .option("--refs <refs>", "Comma-separated reference image paths/urls")
+    .option("--output <file>", "Output file path")
+    .action(imageCreateAction);
+
+  // removed `image edit`
+}