zerocut-cli 0.1.0

package/.eslintrc.js

@@ -0,0 +1,11 @@
+module.exports = {
+  root: true,
+  parser: "@typescript-eslint/parser",
+  plugins: ["@typescript-eslint", "prettier"],
+  extends: ["eslint:recommended", "plugin:@typescript-eslint/recommended", "prettier"],
+  rules: {
+    "prettier/prettier": "error",
+    "@typescript-eslint/no-unused-vars": "warn",
+    "@typescript-eslint/no-explicit-any": "warn",
+  },
+};

package/.prettierignore

@@ -0,0 +1,3 @@
+dist
+node_modules
+

package/.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "printWidth": 100,
+  "trailingComma": "es5"
+}

package/README.md

@@ -0,0 +1,205 @@
+![status: WIP](https://img.shields.io/badge/status-WIP-orange)
+
+# ZeroCut CLI
+
+ZeroCut CLI is a modular, extensible command-line toolkit for media generation and sandbox tool execution. It is built with Node.js (TypeScript), uses CommonJS output, and follows a one-command-per-file architecture.
+
+## Features
+
+- Media generation for image/video/music/tts
+- Sandbox tool execution for ffmpeg and pandoc
+- Modular commands (one file per command under `src/commands/*`)
+- Dynamic external command loading via `ZEROCUT_COMMANDS_DIR` (.js/.cjs files)
+- Configuration interceptor that validates required keys (`apiKey`)
+- Session lifecycle management using Cerevox (open on preAction, close on postAction)
+- Built-in `skill` command to print tool usage spec
+- Strict TypeScript, ESLint + Prettier, pnpm-based project
+
+## Requirements
+
+- Node.js >= 18
+- pnpm (package manager)
+
+## Installation
+
+### From Registry (recommended)
+
+```bash
+# pnpm global install (preferred)
+pnpm add -g zerocut-cli
+
+# Run directly without installing
+pnpm dlx zerocut-cli help
+
+# Run directly with npx
+npx zerocut-cli help
+```
+
+### Local Development
+
+```bash
+# install deps and build
+pnpm install
+pnpm run build
+
+# link globally for local testing
+pnpm link --global
+
+# verify
+zerocut help
+```
+
+## Quick Start
+
+- Show help:
+
+```bash
+npx zerocut-cli help
+```
+
+- Configure required settings:
+
+```bash
+npx zerocut-cli config key <key>            # Or use OTT exchange below
+# quick OTT exchange:
+npx zerocut-cli config --ott <token> --region <cn|us>
+```
+
+If configuration is missing, Zerocut prints:
+
+```
+Missing required configuration: apiKey
+Configure using:
+  zerocut config key <key>
+or:
+  zerocut config --ott <token> --region <cn|us>
+```
+
+## Configuration
+
+- Config file primary path: `~/.zerocut/config.json`
+- Keys:
+  - `apiKey`: string
+  - `region`: environment region, one of `us` or `cn` (default: `us`)
+- Key-path API (internal): `getConfigValueSync('a.b')`, `setConfigValueSync('a.b.c','value')`
+
+### Interactive configuration
+
+Key setup supports direct input or OTT exchange:
+
+```bash
+zerocut config key                   # prompts: choose region (cn/us), then enter OTT
+zerocut config --ott <token> --region <cn|us>   # non-interactive
+```
+
+## Commands
+
+- `help` — show available commands
+- `skill` — print built-in `SKILL.md` content
+- `config` — configuration management
+  - `key [key]` — set API key (prompts if omitted; supports OTT exchange)
+- `image` — create a new image (default action; requires `--prompt`)
+  - Options:
+    - `--prompt <prompt>` (required)
+    - `--model <model>` (seedream|seedream-pro|seedream-5l|banana|banana2|banana-pro|wan)
+    - `--aspectRatio <ratio>` (1:1|3:4|4:3|16:9|9:16|2:3|3:2|21:9|1:4|4:1|1:8|8:1)
+    - `--resolution <resolution>` (1K|2K|4K)
+    - `--refs <img1,img2,...>` (comma-separated paths/URLs)
+    - `--output <file>` (output file path)
+- `video` — create a new video (default action; requires `--prompt`)
+  - Options:
+    - `--prompt <prompt>` (required)
+    - `--duration <seconds>` (integer 1–16; when `--sourceVideo` is set, must be 3–10)
+    - `--model <model>` (enum: `zerocut3.0|seedance-1.5-pro|vidu|vidu-pro|viduq3|viduq3-turbo|kling|kling-v3|wan|wan-flash|sora2|sora2-pro|veo3.1|veo3.1-pro`; default `vidu`)
+    - `--sourceVideo <video>` (base video path/url for edit mode)
+    - `--seed <seed>`
+    - `--firstFrame <image>`
+    - `--lastFrame <image>`
+    - `--refs <assets>`
+    - `--resolution <resolution>`
+    - `--aspectRatio <ratio>` (9:16|16:9|1:1)
+    - `--withAudio`
+    - `--optimizeCameraMotion`
+    - `--output <file>`
+  - Notes:
+    - long videos over 16 seconds should be split into multiple clips (each 1–16s)
+    - merge split clips using `ffmpeg` command
+- `music` — create music (default action; requires `--prompt`)
+  - Options:
+    - `--prompt <prompt>` (required)
+    - `--output <file>`
+- `tts` — text to speech (default action; requires `--text`)
+  - Options:
+    - `--prompt <prompt>`
+    - `--text <text>` (required)
+    - `--voiceId <voiceId>`
+    - `--output <file>`
+- `ffmpeg` — run ffmpeg in sandbox
+  - Options:
+    - `--args <args...>` (required)
+    - `--resources <resources...>` (optional)
+  - Notes:
+    - only `ffmpeg`/`ffprobe` commands are allowed
+    - `ffmpeg` auto-injects `-y` when missing
+    - output file is auto-downloaded to current directory
+- `pandoc` — run pandoc in sandbox
+  - Options:
+    - `--args <args...>` (required)
+    - `--resources <resources...>` (optional)
+  - Notes:
+    - only `pandoc` command is allowed
+    - output file must be specified with `-o` / `--output` / `--output=...`
+    - output file is auto-downloaded to current directory
+
+### Examples
+
+```bash
+# Create an image (default action)
+npx zerocut-cli image --prompt "a cat" --model seedream --aspectRatio 1:1 --resolution 1K --refs ref1.png,ref2.jpg --output out.png
+
+# Create video (default action)
+npx zerocut-cli video --prompt "city night drive" --duration 12 --model vidu --refs frame1.png,frame2.png --resolution 720p --output movie.mp4
+
+# Edit from source video (duration must be 3-10 when sourceVideo is set)
+npx zerocut-cli video --prompt "remix this clip" --model vidu --sourceVideo input.mp4 --duration 6 --output edited.mp4
+
+# Split long video需求并拼接
+printf "file 'part1.mp4'\nfile 'part2.mp4'\nfile 'part3.mp4'\n" > concat.txt
+npx zerocut-cli ffmpeg --args -f concat -safe 0 -i concat.txt -c copy final.mp4 --resources concat.txt part1.mp4 part2.mp4 part3.mp4
+
+# Create speech audio (default action)
+npx zerocut-cli tts --text "你好，欢迎使用 ZeroCut" --voiceId voice_xxx --output speech.mp3
+
+# Create music (default action)
+npx zerocut-cli music --prompt "lofi beat" --output music.mp3
+
+# Run ffmpeg in sandbox
+npx zerocut-cli ffmpeg --args -i input.mp4 -vn output.mp3 --resources input.mp4
+
+# Run pandoc in sandbox
+npx zerocut-cli pandoc --args input.md -o output.pdf --resources input.md
+
+# Print built-in skill spec
+npx zerocut-cli skill
+```
+
+## Dynamic External Commands
+
+Set `ZEROCUT_COMMANDS_DIR` to a directory containing `.js` or `.cjs` files that export a `register(program: Command)` function. Zerocut auto-loads them at runtime.
+
+```bash
+export ZEROCUT_COMMANDS_DIR=/path/to/commands
+zerocut help
+```
+
+## Development
+
+- Build: `pnpm run build`
+- Typecheck: `pnpm run typecheck`
+- Lint: `pnpm run lint`
+- Format: `pnpm run format`
+- Dev (CLI entry): `pnpm run dev`
+
+## License
+
+MIT

package/dist/bin/zerocut.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/zerocut.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cli_1 = require("../cli");
+(0, cli_1.run)(process.argv);

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createProgram(): Command;
+export declare function run(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProgram = createProgram;
+exports.run = run;
+const commander_1 = require("commander");
+const commandLoader_1 = require("./services/commandLoader");
+const config_1 = require("./services/config");
+function createProgram() {
+    const program = new commander_1.Command();
+    program.name("zerocut").description("Zerocut CLI");
+    (0, commandLoader_1.loadBuiltInCommands)(program);
+    (0, config_1.applyConfigInterceptor)(program);
+    return program;
+}
+async function run(argv) {
+    const args = argv.slice(2);
+    const program = createProgram();
+    await (0, commandLoader_1.loadExternalCommandsAsync)(program);
+    if (args.length === 0) {
+        await program.parseAsync([argv[0] ?? "node", argv[1] ?? "zerocut", "help"]);
+        return;
+    }
+    await program.parseAsync(argv);
+}

package/dist/commands/config.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const name = "config";
+export declare const description = "Configuration management";
+export declare function register(program: Command): void;

package/dist/commands/config.js

@@ -0,0 +1,129 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = exports.name = void 0;
+exports.register = register;
+const node_readline_1 = __importDefault(require("node:readline"));
+const config_1 = require("../services/config");
+exports.name = "config";
+exports.description = "Configuration management";
+async function ask(question, defaults) {
+    const rl = node_readline_1.default.createInterface({ input: process.stdin, output: process.stdout });
+    const q = defaults ? `${question} [${defaults}]: ` : `${question}: `;
+    const answer = await new Promise((resolve) => rl.question(q, (ans) => resolve(ans)));
+    rl.close();
+    const trimmed = answer.trim();
+    return trimmed.length > 0 ? trimmed : (defaults ?? "");
+}
+function register(program) {
+    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 (opts) {
+        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());
+            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;
+            }
+            (0, config_1.setConfigValueSync)("apiKey", apiKey);
+            (0, config_1.setConfigValueSync)("region", region);
+            process.stdout.write("apiKey set via OTT\n");
+        }
+        catch (err) {
+            process.stderr.write(`OTT exchange failed: ${err.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) => {
+        const direct = typeof key === "string" ? key.trim() : "";
+        if (direct.length > 0) {
+            (0, config_1.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());
+            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;
+            }
+            (0, config_1.setConfigValueSync)("apiKey", apiKey);
+            (0, config_1.setConfigValueSync)("region", region);
+            process.stdout.write("apiKey set via OTT\n");
+        }
+        catch (err) {
+            process.stderr.write(`OTT exchange failed: ${err.message}\n`);
+            process.exitCode = 1;
+        }
+    });
+    parent
+        .command("list")
+        .description("List current configuration values")
+        .action(() => {
+        const cfg = (0, config_1.readConfigSync)();
+        const masked = { ...cfg };
+        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/dist/commands/ffmpeg.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const name = "ffmpeg";
+export declare const description = "Run ffmpeg in sandbox";
+export declare function register(program: Command): void;

package/dist/commands/ffmpeg.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = exports.name = void 0;
+exports.register = register;
+const cerevox_1 = require("../services/cerevox");
+exports.name = "ffmpeg";
+exports.description = "Run ffmpeg in sandbox";
+function register(program) {
+    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 (opts) {
+        const session = (0, cerevox_1.getSessionFromCommand)(this);
+        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 (0, cerevox_1.runFFMpegCommand)(session, command, resources);
+        console.log(res);
+    });
+}

package/dist/commands/foo.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const name = "foo";
+export declare const description = "Print bar";
+export declare function register(program: Command): void;

package/dist/commands/foo.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = exports.name = void 0;
+exports.register = register;
+exports.name = "foo";
+exports.description = "Print bar";
+function register(program) {
+    program
+        .command("foo")
+        .description("Print bar")
+        .action(() => {
+        process.stdout.write("bar\n");
+    });
+}

package/dist/commands/help.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const name = "help";
+export declare const description = "Show help";
+export declare function register(program: Command): void;

package/dist/commands/help.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = exports.name = void 0;
+exports.register = register;
+exports.name = "help";
+exports.description = "Show help";
+function register(program) {
+    program
+        .command("help")
+        .description("Show help")
+        .action(() => {
+        program.outputHelp();
+    });
+}

package/dist/commands/image.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const name = "image";
+export declare const description = "Image command: create image";
+export declare function register(program: Command): void;

package/dist/commands/image.js

@@ -0,0 +1,149 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.description = exports.name = void 0;
+exports.register = register;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const cerevox_1 = require("../services/cerevox");
+const progress_1 = require("../utils/progress");
+exports.name = "image";
+exports.description = "Image command: create image";
+function register(program) {
+    const parent = program.command("image").description("Create a new image; requires --prompt");
+    const allowedModels = [
+        "seedream",
+        "seedream-pro",
+        "seedream-5l",
+        "banana",
+        "banana2",
+        "banana-pro",
+        "wan",
+    ];
+    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",
+    ];
+    const allowedResolutions = ["1K", "2K", "4K"];
+    async function performImageGeneration(session, { prompt, model, aspectRatio, resolution, refsList, output, }) {
+        const referenceImages = await Promise.all(refsList.map(async (ref) => ({ url: await (0, cerevox_1.getMaterialUri)(session, ref) })));
+        const onProgress = (0, progress_1.createProgressSpinner)("inferencing");
+        const payload = {
+            model: model || "seedream-5l",
+            prompt,
+            aspect_ratio: aspectRatio,
+            resolution,
+            reference_images: referenceImages,
+            onProgress,
+        };
+        const res = await session.ai.generateImage(payload);
+        if (res?.urls && Array.isArray(res.urls) && res.urls.length > 0) {
+            try {
+                const tosUrl = await (0, cerevox_1.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 ?? res.urls[0];
+            const response = await fetch(url);
+            const buffer = Buffer.from(await response.arrayBuffer());
+            const filePath = node_path_1.default.resolve(dir, output);
+            if (!node_fs_1.default.existsSync(node_path_1.default.dirname(filePath))) {
+                node_fs_1.default.mkdirSync(node_path_1.default.dirname(filePath), { recursive: true });
+            }
+            node_fs_1.default.writeFileSync(filePath, buffer);
+            res.output = filePath;
+        }
+        console.log(res);
+    }
+    async function imageCreateAction(opts) {
+        const session = (0, cerevox_1.getSessionFromCommand)(this);
+        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.includes(model)) {
+            process.stderr.write(`Invalid value for --model: ${model}. Allowed: ${allowedModels.join("|")}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        const modelArg = (model ?? undefined);
+        const aspectRatio = typeof opts.aspectRatio === "string"
+            ? opts.aspectRatio.trim()
+            : undefined;
+        if (aspectRatio && !allowedAspectRatios.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()
+            : undefined;
+        if (resolution && !allowedResolutions.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`
+}

package/dist/commands/music.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+export declare const name = "music";
+export declare const description = "Music command: create music";
+export declare function register(program: Command): void;