reelforge 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# reelforge
+
+> CLI for [ReelForge Studio](https://github.com/puke3615/ReelForge) — every REST API exposed as a command, with `--help` available at every level.
+
+## Install
+
+```bash
+npm install -g reelforge
+```
+
+Or use directly without install:
+
+```bash
+npx reelforge <command>
+```
+
+## Quick start
+
+`reelforge` ships pointing at the hosted instance (`https://reelforge.timor419.com`). Get an activation code from the admin, log in once, and call:
+
+```bash
+npm install -g reelforge
+reelforge login JKxxxxxxxxxxxxxx               # bind your API key
+reelforge whoami                               # balance + api_keys
+reelforge create "为什么我们还没找到外星文明？" -o space.mp4
+```
+
+That's the whole story — no server to run.
+
+### Self-hosting
+
+If you want to run your own ReelForge Studio (own LLM / RunningHub keys, your own pricing) clone the upstream repo, `pnpm dev`, then point the CLI at it:
+
+```bash
+reelforge --server http://localhost:8501 health
+# or persist:
+export REELFORGE_SERVER=http://localhost:8501
+# or via `reelforge login <key> --server http://localhost:8501`
+```
+
+## Global options
+
+| flag | description |
+|---|---|
+| `-s, --server <url>` | ReelForge server URL (overrides `$REELFORGE_SERVER`; default `https://reelforge.timor419.com`) |
+| `-k, --api-key <key>` | API key (overrides `$REELFORGE_API_KEY` and `reelforge login` saved key) |
+| `--json` | Output raw JSON instead of pretty text — pipe-friendly |
+| `--quiet` | Suppress informational messages on stderr |
+| `-v, --version` | Show CLI version |
+| `-h, --help` | Show help (works on every sub-command) |
+
+## Command map
+
+Run `reelforge <command> --help` for full details on any of these.
+
+### Core capabilities
+
+| command | what it does |
+|---|---|
+| `llm chat -p <text>` | Send one prompt to the configured LLM |
+| `llm presets` | List built-in provider presets |
+| `tts edge -t <text> -o out.mp3` | Local Edge TTS synthesis |
+| `tts workflow -t <text> -w <workflow>` | ComfyUI TTS workflow (clone-style, IndexTTS etc.) |
+| `tts voices [--locale zh]` | List supported Edge TTS voices |
+| `images generate -p <prompt> -w <workflow>` | Image generation via ComfyUI / RunningHub |
+| `images analyze -i <image>` | Reverse-describe an image |
+| `videos generate -p <prompt> -w <workflow>` | Atomic video generation |
+| `videos analyze -i <video>` | Reverse-describe a video |
+
+### Content generation
+
+| command | what it does |
+|---|---|
+| `content narration -t <topic>` | Generate N narration sentences from a topic |
+| `content split -s <script>` | Split a fixed script into narrations |
+| `content image-prompts -i <file>` | English image prompts from narration list |
+| `content title -c <content>` | Generate a short video title |
+| `content asset-script --intent ... --assets <file>` | Asset-based scene script |
+
+### Composition
+
+| command | what it does |
+|---|---|
+| `templates list [--size 1080x1920] [--type image]` | List HTML frame templates |
+| `templates preview <key> [-o out.png]` | Render a template preview |
+| `frames render -t <key> --title ... --text ...` | Render a single composed frame to PNG |
+| `compositions concat <v1> <v2> -o out.mp4` | FFmpeg concat (+ optional BGM) |
+| `compositions bgm -i video.mp4 --bgm bgm.mp3 -o out.mp4` | Add background music |
+| `compositions image-to-video -i img.png -a aud.mp3 -o out.mp4` | Build video from image + audio |
+| `compositions overlay -v video.mp4 --overlay overlay.png -o out.mp4` | Overlay PNG on video |
+
+### End-to-end pipelines
+
+All `pipelines *` commands submit an **async task** and (by default) poll until it finishes with a live progress indicator on stderr. Use `--no-wait` to return immediately with a `task_id`, then `reelforge tasks wait <id>` later.
+
+| command | what it does |
+|---|---|
+| `pipelines standard -t <topic\|script>` | Topic / script → narration → frames → final MP4 |
+| `pipelines asset-based --intent ... --assets <file>` | User assets → AI-arranged scene video |
+| `pipelines digital-human -w <wf> -i <portrait> -t <text>` | Digital human speaker |
+| `pipelines i2v -w <wf> -i <image>` | Image-to-video |
+| `pipelines action-transfer -w <wf> --reference-video <v> --character-image <img>` | Action transfer |
+
+### Resources
+
+| command | what it does |
+|---|---|
+| `workflows list [--source runninghub] [--kind image]` | Browse ComfyUI workflows |
+| `bgm list / upload <file> / delete <name>` | Manage background music |
+| `files list / upload <file> / download <path> / delete <path>` | Manage user assets |
+
+### System
+
+| command | what it does |
+|---|---|
+| `config get` | Read server config (keys masked) |
+| `config set <key> <value>` | Update a dotted-path setting (e.g. `llm.api_key sk-xxx`) |
+| `config patch <file>` | Apply a JSON-merge patch |
+| `tasks list [--status running]` | List recent tasks |
+| `tasks get <id>` / `tasks wait <id>` / `tasks cancel <id>` | Task lifecycle |
+| `history list / get <id> / delete <id>` | Browse / delete completed runs |
+| `health` | Server health + capability check |
+
+## Examples
+
+```bash
+# 1. End-to-end "text → video" with zero external APIs (Edge TTS + static template)
+reelforge pipelines standard \
+  -t "Hello world. This is scene one.\n\nThis is scene two." \
+  --mode fixed --title "Smoke Test" \
+  --frame-template 1080x1920/static_default.html \
+  --tts-voice en-US-AriaNeural -o smoke.mp4
+
+# 2. Inspect existing tasks & redownload a finished video
+reelforge tasks list --limit 5
+reelforge history get <task-id> --download recovered.mp4
+
+# 3. JSON pipe for automation
+reelforge workflows list --kind image --json | jq '.workflows[].key'
+
+# 4. Configure & test LLM
+reelforge config set llm.api_key sk-xxxxx
+reelforge config set llm.base_url https://dashscope.aliyuncs.com/compatible-mode/v1
+reelforge config set llm.model qwen-plus
+reelforge llm chat -p 'one-sentence summary of antifragile'
+```
+
+## Tip — getting unstuck
+
+Every level has `--help`:
+
+```bash
+reelforge --help                     # top-level overview
+reelforge pipelines --help           # list of pipelines
+reelforge pipelines standard --help  # full option reference
+reelforge tts edge --help            # one specific command
+```
+
+## Development & publishing
+
+```bash
+cd cli
+npm install
+npm run build
+npm link                           # makes `reelforge` available globally for testing
+reelforge health                     # try it out
+
+# Publish to npm
+npm publish --access public
+```
+
+## License
+
+Apache-2.0

package/bin/reelforge.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// Thin shim so `reelforge` is invokable globally. The actual implementation
+// is bundled to dist/ by `npm run build`.
+import("../dist/index.js").catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err?.stack || err);
+  process.exit(1);
+});

package/dist/client.js

@@ -0,0 +1,130 @@
+/**
+ * HTTP client for the ReelForge Studio REST API.
+ *
+ * Resolution:
+ *   server  = --server flag > $REELFORGE_SERVER > ~/.reelforge/config.json > https://reelforge.timor419.com
+ *   api_key = setApiKey() (from --api-key flag) > $REELFORGE_API_KEY > ~/.reelforge/config.json > none
+ *
+ * Auth: if an api_key is resolved, requests automatically get
+ * `Authorization: Bearer <api_key>` (unless the caller pre-sets one).
+ */
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+const DEFAULT_SERVER = "https://reelforge.timor419.com";
+function loadConfigSync() {
+    try {
+        const p = path.join(os.homedir(), ".reelforge", "config.json");
+        const raw = readFileSync(p, "utf-8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed === "object" && parsed ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+const fileConfig = loadConfigSync();
+let overrideServer = null;
+let overrideApiKey = null;
+export function setServer(url) {
+    overrideServer = url.replace(/\/$/, "");
+}
+export function getServer() {
+    if (overrideServer)
+        return overrideServer;
+    const env = process.env.REELFORGE_SERVER;
+    if (env)
+        return env.replace(/\/$/, "");
+    if (fileConfig.server)
+        return fileConfig.server.replace(/\/$/, "");
+    return DEFAULT_SERVER;
+}
+export function setApiKey(key) {
+    overrideApiKey = key;
+}
+export function getApiKey() {
+    if (overrideApiKey)
+        return overrideApiKey;
+    if (process.env.REELFORGE_API_KEY)
+        return process.env.REELFORGE_API_KEY;
+    if (fileConfig.api_key)
+        return fileConfig.api_key;
+    return null;
+}
+export class ApiCallError extends Error {
+    status;
+    code;
+    details;
+    constructor(err) {
+        super(err.message);
+        this.status = err.status;
+        this.code = err.code;
+        this.details = err.details;
+    }
+}
+async function request(path, init = {}) {
+    const url = `${getServer()}${path.startsWith("/") ? path : `/${path}`}`;
+    const headers = new Headers(init.headers);
+    const key = getApiKey();
+    if (key && !headers.has("Authorization") && !headers.has("authorization")) {
+        headers.set("Authorization", `Bearer ${key}`);
+    }
+    let res;
+    try {
+        res = await fetch(url, { ...init, headers });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new ApiCallError({
+            status: 0,
+            message: `Network error contacting ${url}: ${msg}`,
+        });
+    }
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        if (!res.ok) {
+            throw new ApiCallError({ status: res.status, message: text.slice(0, 500) });
+        }
+        return text;
+    }
+    if (!res.ok) {
+        const err = json?.error;
+        throw new ApiCallError({
+            status: res.status,
+            code: err?.code,
+            message: err?.message || `HTTP ${res.status}`,
+            details: err?.details,
+        });
+    }
+    return json;
+}
+export function get(path) {
+    return request(path);
+}
+export function post(path, body) {
+    return request(path, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}
+export function patch(path, body) {
+    return request(path, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+}
+export function del(path) {
+    return request(path, { method: "DELETE" });
+}
+export async function uploadMultipart(path, fields) {
+    const form = new FormData();
+    for (const [k, v] of Object.entries(fields))
+        form.append(k, v);
+    return request(path, { method: "POST", body: form });
+}

package/dist/commands/auth.js

@@ -0,0 +1,69 @@
+import { get, setApiKey, setServer, getServer } from "../client.js";
+import { loadConfig, saveConfig, deleteConfig, getConfigPath } from "../utils/config-file.js";
+import { info, success, print, table } from "../utils/output.js";
+export function registerAuth(program) {
+    program
+        .command("login <api_key>")
+        .description("Save your API key (and optionally server URL) to ~/.reelforge/config.json")
+        .helpOption("-h, --help", "show help")
+        .option("--server <url>", "also persist a custom server URL")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  reelforge login JK1234567890ABCDEF                            # bind key, use default server",
+        "  reelforge login JK1234567890ABCDEF --server http://nas:8501   # bind key + custom server",
+        "",
+        "The key is verified against /api/v1/me before being saved.",
+    ].join("\n"))
+        .action(async (apiKey, opts) => {
+        if (opts.server)
+            setServer(opts.server);
+        setApiKey(apiKey);
+        // verify
+        const me = await get("/api/v1/me");
+        const existing = await loadConfig();
+        const saved = await saveConfig({
+            ...existing,
+            api_key: apiKey,
+            ...(opts.server ? { server: opts.server } : {}),
+        });
+        success(`Saved → ${saved}`);
+        info(`Account: ${me.account.account_number}${me.account.label ? ` · ${me.account.label}` : ""}`);
+        info(`Balance: ${me.account.balance} ${me.account.unit_name}`);
+        info(`Server:  ${getServer()}`);
+    });
+    program
+        .command("logout")
+        .description("Delete the locally saved API key (and server)")
+        .helpOption("-h, --help", "show help")
+        .action(async () => {
+        const path = getConfigPath();
+        const deleted = await deleteConfig();
+        if (deleted) {
+            success(`Deleted ${path}`);
+        }
+        else {
+            info(`No config to delete (${path} not found)`);
+        }
+    });
+    program
+        .command("whoami")
+        .description("Show the currently logged-in account: balance, api_keys, usage stats")
+        .helpOption("-h, --help", "show help")
+        .action(async () => {
+        const me = await get("/api/v1/me");
+        print({
+            account: me.account,
+        });
+        if (me.api_keys.length) {
+            info(`API keys (${me.api_keys.length}):`);
+            table(me.api_keys.map((k) => ({
+                id: k.id,
+                api_key: k.api_key,
+                label: k.label ?? "",
+                status: k.status,
+                last_used_at: k.last_used_at ?? "—",
+            })));
+        }
+    });
+}

package/dist/commands/bgm.js

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import path from "node:path";
+import { del, get, uploadMultipart } from "../client.js";
+import { print, table, success, bytes } from "../utils/output.js";
+export function registerBgm(program) {
+    const bgm = program
+        .command("bgm")
+        .description("Manage background-music files")
+        .helpOption("-h, --help", "show help");
+    bgm
+        .command("list")
+        .description("List all BGM files (default + user-uploaded)")
+        .helpOption("-h, --help", "show help")
+        .action(async () => {
+        const r = await get("/api/v1/bgm");
+        table(r.bgm.map((b) => ({
+            name: b.name,
+            size: bytes(b.size_bytes),
+            source: b.source,
+            path: b.relative_path,
+        })));
+    });
+    bgm
+        .command("upload <file>")
+        .description("Upload a new BGM file (saved under data/bgm/)")
+        .helpOption("-h, --help", "show help")
+        .action(async (file) => {
+        const abs = path.resolve(file);
+        const buf = fs.readFileSync(abs);
+        const name = path.basename(abs);
+        const fileObj = new File([new Uint8Array(buf)], name, { type: "audio/mpeg" });
+        const r = await uploadMultipart("/api/v1/bgm", { file: fileObj });
+        success(`Uploaded ${name}`);
+        print(r);
+    });
+    bgm
+        .command("delete <name>")
+        .alias("rm")
+        .description("Delete a user-uploaded BGM (default repo BGM is protected)")
+        .helpOption("-h, --help", "show help")
+        .action(async (name) => {
+        const r = await del(`/api/v1/bgm/${encodeURIComponent(name)}`);
+        print(r);
+    });
+}

package/dist/commands/compositions.js

@@ -0,0 +1,95 @@
+import path from "node:path";
+import { post } from "../client.js";
+import { downloadTo } from "../utils/download.js";
+import { print, success } from "../utils/output.js";
+export function registerCompositions(program) {
+    const comp = program
+        .command("compositions")
+        .alias("compose")
+        .description("FFmpeg compositions: concat / add BGM / image+audio→video / overlay")
+        .helpOption("-h, --help", "show help");
+    comp
+        .command("concat <videos...>")
+        .description("Concatenate multiple MP4 files into one")
+        .helpOption("-h, --help", "show help")
+        .option("-o, --output <file>", "output path (REQUIRED)")
+        .option("--method <method>", "demuxer | filter", "demuxer")
+        .option("--bgm <path>", "optional BGM file to mix in")
+        .option("--bgm-volume <n>", "BGM volume (0..1)", parseFloat, 0.2)
+        .option("--bgm-mode <mode>", "loop | once", "loop")
+        .addHelpText("after", "\nExample:\n  reelforge compositions concat a.mp4 b.mp4 c.mp4 -o final.mp4 --bgm bgm/default.mp3")
+        .action(async (videos, opts) => {
+        if (!opts.output)
+            throw new Error("--output is required");
+        const r = await post("/api/v1/compositions/concat", {
+            videos: videos.map((v) => path.resolve(v)),
+            method: opts.method,
+            bgm_path: opts.bgm,
+            bgm_volume: opts.bgmVolume,
+            bgm_mode: opts.bgmMode,
+        });
+        await downloadTo(r.url, opts.output);
+        success(`Saved → ${opts.output}`);
+        print(r);
+    });
+    comp
+        .command("bgm")
+        .description("Add background music to an existing video")
+        .helpOption("-h, --help", "show help")
+        .requiredOption("-i, --input <file>", "input video path")
+        .requiredOption("--bgm <file>", "BGM audio file")
+        .option("-o, --output <file>", "output path (REQUIRED)")
+        .option("--volume <n>", "BGM volume (0..1)", parseFloat, 0.2)
+        .option("--mode <mode>", "loop | once", "loop")
+        .action(async (opts) => {
+        if (!opts.output)
+            throw new Error("--output is required");
+        const r = await post("/api/v1/compositions/bgm", {
+            video: path.resolve(opts.input),
+            bgm: path.resolve(opts.bgm),
+            volume: opts.volume,
+            mode: opts.mode,
+        });
+        await downloadTo(r.url, opts.output);
+        success(`Saved → ${opts.output}`);
+        print(r);
+    });
+    comp
+        .command("image-to-video")
+        .description("Build a video from a single image + an audio track")
+        .helpOption("-h, --help", "show help")
+        .requiredOption("-i, --image <file>", "input image")
+        .requiredOption("-a, --audio <file>", "input audio")
+        .option("-o, --output <file>", "output path (REQUIRED)")
+        .option("--fps <n>", "frames per second", parseInt, 30)
+        .action(async (opts) => {
+        if (!opts.output)
+            throw new Error("--output is required");
+        const r = await post("/api/v1/compositions/image-to-video", {
+            image: path.resolve(opts.image),
+            audio: path.resolve(opts.audio),
+            fps: opts.fps,
+        });
+        await downloadTo(r.url, opts.output);
+        success(`Saved → ${opts.output}`);
+        print(r);
+    });
+    comp
+        .command("overlay")
+        .description("Overlay a transparent PNG on top of a video")
+        .helpOption("-h, --help", "show help")
+        .requiredOption("-v, --video <file>", "input video")
+        .requiredOption("--overlay <file>", "overlay PNG (with transparency)")
+        .option("-o, --output <file>", "output path (REQUIRED)")
+        .action(async (opts) => {
+        if (!opts.output)
+            throw new Error("--output is required");
+        const r = await post("/api/v1/compositions/overlay", {
+            video: path.resolve(opts.video),
+            overlay_image: path.resolve(opts.overlay),
+        });
+        await downloadTo(r.url, opts.output);
+        success(`Saved → ${opts.output}`);
+        print(r);
+    });
+}

package/dist/commands/config.js

@@ -0,0 +1,65 @@
+import fs from "node:fs/promises";
+import { get, patch } from "../client.js";
+import { print } from "../utils/output.js";
+export function registerConfig(program) {
+    const cfg = program
+        .command("config")
+        .description("Read or update the server config.yaml (LLM / ComfyUI / RunningHub keys)")
+        .helpOption("-h, --help", "show help");
+    cfg
+        .command("get")
+        .description("Print the current config (API keys masked)")
+        .helpOption("-h, --help", "show help")
+        .action(async () => {
+        const r = await get("/api/v1/config");
+        print(r);
+    });
+    cfg
+        .command("set <key> <value>")
+        .description("Update a single config value using dotted path, e.g. `llm.api_key sk-xxx`")
+        .helpOption("-h, --help", "show help")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  reelforge config set llm.api_key sk-xxxxxx",
+        "  reelforge config set llm.base_url https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "  reelforge config set llm.model qwen-plus",
+        "  reelforge config set comfyui.runninghub_api_key rh-xxxxxx",
+        "  reelforge config set comfyui.runninghub_instance_type plus",
+    ].join("\n"))
+        .action(async (key, value) => {
+        const parts = key.split(".");
+        const patchBody = {};
+        let cur = patchBody;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const next = {};
+            cur[parts[i]] = next;
+            cur = next;
+        }
+        cur[parts[parts.length - 1]] = coerce(value);
+        const r = await patch("/api/v1/config", patchBody);
+        print(r);
+    });
+    cfg
+        .command("patch <file>")
+        .description("Apply a JSON-merge patch file to the config")
+        .helpOption("-h, --help", "show help")
+        .action(async (file) => {
+        const body = JSON.parse(await fs.readFile(file, "utf-8"));
+        const r = await patch("/api/v1/config", body);
+        print(r);
+    });
+}
+function coerce(s) {
+    if (s === "true")
+        return true;
+    if (s === "false")
+        return false;
+    if (s === "null")
+        return null;
+    if (/^-?\d+$/.test(s))
+        return parseInt(s, 10);
+    if (/^-?\d+\.\d+$/.test(s))
+        return parseFloat(s);
+    return s;
+}