videodraft 0.0.0 → 0.1.0

package/package.json

@@ -1,9 +1,68 @@
 {
   "name": "videodraft",
-  "version": "0.0.0",
-  "description": "Official VideoDraft CLI — create AI videos, images, voiceovers and music from your terminal. Launching soon.",
+  "version": "0.1.0",
+  "description": "Official VideoDraft CLI — create AI videos, images, voiceovers and music from your terminal. Agent-friendly: --json everywhere, stable exit codes, async job polling.",
   "license": "MIT",
+  "type": "module",
   "homepage": "https://videodraft.ai/cli",
-  "repository": "github:videodraft-ai/cli",
-  "keywords": ["videodraft", "ai", "video", "cli", "agent", "mcp"]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/videodraft-ai/cli.git"
+  },
+  "bugs": "https://github.com/videodraft-ai/cli/issues",
+  "keywords": [
+    "videodraft",
+    "ai",
+    "video",
+    "video-generation",
+    "image-generation",
+    "cli",
+    "agent",
+    "mcp"
+  ],
+  "bin": {
+    "videodraft": "./dist/index.js"
+  },
+  "main": "./dist/client.js",
+  "types": "./dist/client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "tsup --watch",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "npm run build && node test/e2e-mock.mjs",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "picocolors": "^1.1.1",
+    "undici": "^7.10.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.2",
+    "tsup": "^8.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.2",
+    "vitest": "^3.2.0"
+  }
 }

package/skills/videodraft/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: videodraft
+description: Create AI videos, images, voiceovers, music, storyboards, avatar videos and product/ad videos with VideoDraft. Use when the user mentions VideoDraft, or asks to generate/make a video, video ad, explainer, storyboard, talking-head/avatar video, AI image, voiceover/TTS, or background music — including batch/programmatic video generation in scripts or CI. Works via the `videodraft` CLI (preferred in terminals) or the VideoDraft MCP connector.
+license: MIT
+metadata:
+  author: VideoDraft (videodraft.ai)
+  homepage: https://videodraft.ai/cli
+---
+
+# VideoDraft
+
+VideoDraft is an AI video creation platform: idea → script → storyboard (scenes + shot images) → production (voiceover, captions, motion clips, music) → exported MP4. You can drive all of it from this environment.
+
+## How to connect
+
+Two equivalent surfaces (same backend, same credits, same projects):
+
+1. **CLI** (preferred when you have a shell): run `videodraft` if it's on PATH; otherwise `npx videodraft` runs it with no install (needs Node ≥20; the package is fetched on first use and cached). For heavy use, `npm install -g videodraft`. If there's no Node/shell here but the MCP connector below is available, use that instead; if neither works, tell the user how to install (https://videodraft.ai/cli).
+   - Auth — pick by context, don't guess:
+     • INTERACTIVE (a human is in the session, e.g. Claude Code / Codex): on exit code 3 ("not authenticated"), tell the user to run `videodraft login` in their terminal — it opens their browser for a one-click VideoDraft sign-in (OAuth), no key to copy. Wait for them to confirm it succeeded, then retry the command. This is the preferred path when the user is present.
+     • HEADLESS / CI (no browser): set `VIDEODRAFT_API_KEY=vd_mcp_...` (a token the user mints at https://app.videodraft.ai/mcp-keys).
+     • SECURITY: never ask the user to paste a `vd_mcp_...` token into the chat — use browser `login` or the env var so the token never lands in the transcript.
+   - Every command accepts `--json` (parse this, don't scrape text). Exit codes: 0 ok, 1 error, 2 usage, 3 auth (see Auth above), 4 insufficient credits (→ tell the user, don't retry).
+   - Full API access: `videodraft tools list`, `videodraft tools schema <name>`, `videodraft call <tool> --args '<json>'`.
+2. **MCP connector**: if VideoDraft MCP tools (e.g. `generate_storyboard_from_idea`) are available, call them directly — the CLI's curated commands map 1:1 onto these tools.
+
+## First decision: asset or video?
+
+- **One standalone asset** (a single image, clip, voiceover, or music track, no story): generate it directly. Do NOT create a project.
+  - `videodraft generate image "a red fox in snow, cinematic" --ar 16:9 --download ./out/`
+  - `videodraft generate video "slow dolly over a misty lake" --model google-veo3.1 --duration 6 --download ./out/`
+- **A video / ad / explainer / anything multi-scene**: create a project so the work stays organized, editable in the web app, and exportable.
+  - `videodraft create "30s launch video for our espresso machine" --ar 9:16`
+- **Just a script** (no video asked for): `videodraft create "..." --script-only`. Stop at the script — do not build a storyboard the user didn't ask for.
+- **Iterating on existing work**: find it first (`videodraft projects list`) and reuse that project. Never create a new project to change an existing one.
+
+## Credits: confirm before spending
+
+Generation costs credits (video is per-second; shot-image batches are the largest single spend). Before anything expensive:
+
+1. `videodraft credits` — check the balance.
+2. `videodraft generate video "..." --estimate` or `videodraft costs <model> --duration 8 --resolution 1080p` — get the quote.
+3. Tell the user the model + settings + rough cost and get a go-ahead. Ask rather than assume aspect ratio, duration, and model when they matter.
+
+`videodraft models image|video` lists every model with its supported inputs (aspect ratios, resolutions, reference limits) — consult it instead of guessing capabilities.
+
+## Async jobs
+
+Image/video generation is asynchronous: commands submit a job and **wait by default**, printing output URLs (and saving files with `--download`). In scripts/CI prefer explicit control:
+
+```bash
+JOB=$(videodraft generate image "..." --no-wait --json | jq -r .job_id)
+videodraft wait "$JOB" --download "./outputs/{job_id}_{index}.{ext}" --json
+```
+
+For MANY jobs: submit each with `--no-wait`, collect ALL with one command — `videodraft wait <id1> <id2> ...` polls every job from one process with one batched request per tick. Do NOT spawn parallel `wait`/`generate --wait` processes for a batch.
+
+If a wait times out, the job is still running server-side — `videodraft status <job_id>` later. Never re-submit just because a wait timed out (that double-spends credits).
+
+## Local files and reference images
+
+Reference inputs must be public URLs. The CLI uploads local files automatically wherever a URL is expected (`--ref photo.jpg`, `--start-image frame.png`), or explicitly:
+
+```bash
+URL=$(videodraft upload ./product.png --json | jq -r .url)
+```
+
+Never silently drop a reference you couldn't upload — stop and tell the user. Never upload a user's file to a third-party host.
+
+When the user attaches media, classify each item before acting: a recurring **visual asset** (character/product/location/style), actual **footage to place as shots**, or **inspiration only**. See [references/pipeline.md](references/pipeline.md) for how each role flows into a project.
+
+## The full pipeline (idea → MP4)
+
+```bash
+videodraft credits
+videodraft create "<idea>" --ar 9:16            # project: script → visual assets → storyboard
+videodraft shots <project_id> --grid --estimate # cost preview, confirm with user
+videodraft shots <project_id> --grid            # batch shot images (waits, writes onto shot cards)
+videodraft produce <project_id>                 # voiceovers + captions + production timeline
+videodraft export <project_id> --download final.mp4
+```
+
+Optional between produce and export: per-shot motion clips (`videodraft generate video ... --project <id>` then place it with `videodraft attach <project> --scene N --shot M --media <url|file> --type video --duration <s>`), and music (`videodraft generate music "..." --attach <project_id>`). Details, per-step tools and editing rules: [references/pipeline.md](references/pipeline.md).
+
+Avatar/talking-head videos are their own short flow: `videodraft avatar script` → `avatar create` → `avatar render` (paid step).
+
+## Working with project data
+
+A project is one JSON blob (script, storyboard scenes, shot cards, visual assets, production timeline). To inspect: `videodraft projects get <id>`. To edit: fetch `--raw`, modify, then `videodraft call update_project` — objects deep-merge, **arrays replace wholesale** (send the complete `storyboard.scenes` array to change one scene). Snapshot first with `videodraft checkpoint create <id>` before risky edits. Schema reference: `videodraft call get_project_schema`.
+
+## More
+
+- [references/pipeline.md](references/pipeline.md) — project data model, step-by-step tools, attaching media, editing safely
+- [references/models.md](references/models.md) — choosing image/video models, pricing patterns, voices and styles
+- [references/examples.md](references/examples.md) — recipes: batch product videos from a CSV, talking-head from a script, changelog video in CI

package/skills/videodraft/references/examples.md

@@ -0,0 +1,84 @@
+# Recipes
+
+Working patterns for common asks. All assume auth (`videodraft login` once, or `VIDEODRAFT_API_KEY` in the environment) and use `--json` for parsing.
+
+## 1. Batch product videos from a CSV
+
+One 9:16 product clip per row of `products.csv` (`name,image_url,tagline`):
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+mkdir -p outputs
+
+while IFS=, read -r name image tagline; do
+  job=$(videodraft generate video \
+    "Premium product shot of ${name}: ${tagline}. Slow orbit, studio lighting." \
+    --model google-veo3.1 --ar 9:16 --duration 6 \
+    --start-image "$image" \
+    --no-wait --json | jq -r .job_id)
+  echo "$name,$job" >> outputs/jobs.csv
+done < <(tail -n +2 products.csv)
+
+# Collect ALL results with ONE process (batched polling — one request per tick)
+videodraft wait $(cut -d, -f2 outputs/jobs.csv) \
+  --download "outputs/{job_id}_{index}.{ext}" --json > outputs/results.json
+# map job ids back to product names via outputs/jobs.csv
+```
+
+Submit-then-collect parallelizes server-side generation; the single multi-id `wait` keeps it to one local process and one batched poll request per tick no matter how many jobs. Estimate first: `videodraft costs google-veo3.1 --type video --duration 6` × rows, and confirm with the user.
+
+## 2. Full marketing video from one idea
+
+```bash
+videodraft credits --json
+videodraft create "30-second launch video for Solace, a sleep-tracking ring. Calm, premium, dark palette." \
+  --ar 9:16 --style cinematic --json > project.json
+PROJECT=$(jq -r .project_id project.json)
+
+videodraft shots "$PROJECT" --grid --estimate          # show the user the cost; get a go-ahead
+videodraft shots "$PROJECT" --grid
+videodraft produce "$PROJECT"
+videodraft generate music "minimal ambient, warm pads, 60 BPM" --attach "$PROJECT"
+videodraft export "$PROJECT" --download solace-launch.mp4
+```
+
+The project stays editable at the URL in `project.json` (`.urls`) — hand it to the user for tweaks.
+
+## 3. Talking-head (avatar) video
+
+```bash
+SCRIPT=$(videodraft avatar script "why our espresso subscription saves you money" --style ad-style --json | jq -r .script)
+AVATAR=$(videodraft avatar create ./founder.jpg --script "$SCRIPT" --ar 9:16 --json | jq -r .avatar_video_id)
+videodraft avatar render "$AVATAR" --resolution 720p   # paid step — confirm cost first (~20 credits/sec)
+```
+
+## 4. Changelog video in CI
+
+In a GitHub Action with `VIDEODRAFT_API_KEY` set as a secret:
+
+```bash
+NOTES=$(git log --oneline v1.2.0..HEAD | head -20)
+videodraft create "Weekly product update video. Energetic, 20 seconds. Changes: ${NOTES}" --ar 16:9 --json > p.json
+PROJECT=$(jq -r .project_id p.json)
+videodraft shots "$PROJECT" && videodraft produce "$PROJECT"
+videodraft export "$PROJECT" --download changelog.mp4 --wait-timeout 30m
+```
+
+## 5. Variations and picking a winner
+
+```bash
+videodraft generate image "logo concept: minimalist fox, geometric" --num 4 --download "./concepts/{job_id}_{index}.{ext}" --json
+# Show all 4 to the user; regenerate the chosen one at higher res:
+videodraft generate image "<same prompt>" --model nano-banana-pro --resolution 4K
+```
+
+## 6. Reaching tools without a curated command
+
+```bash
+videodraft tools list --json | jq -r '.[].name'
+videodraft tools schema attach_media_to_shot --json
+videodraft call attach_media_to_shot --args '{"project_id":"...","scene_index":0,"shot_index":1,"media_url":"https://...","media_type":"video","duration_seconds":6}'
+```
+
+Anything the VideoDraft MCP exposes — character studio, product studio, timeline editing — is reachable this way even before it gets a curated command.

package/skills/videodraft/references/models.md

@@ -0,0 +1,43 @@
+# Choosing models (and predicting cost)
+
+Always consult the live catalog instead of memorizing this page — models change weekly:
+
+```bash
+videodraft models image --json     # every image model + inputs (aspect ratios, resolutions, max refs)
+videodraft models video --json     # every video model + inputs + per-second pricing metadata
+videodraft models voices --json    # TTS voices
+videodraft models styles --json    # visual style presets
+```
+
+## Defaults (safe starting points)
+
+- **Image**: `nano-banana-2` (the platform default, 1K). Use `--num 1..4` for variations of one prompt in a single call — never loop for variations.
+- **Video**: `google-veo3.1` at fast quality (6s / 720p) — the platform default.
+- **Voiceover**: ElevenLabs Brittney (default voice).
+- **Music**: `lyria-3-clip-preview` (30s, cheap); `lyria-3-pro-preview` for 180s/quality.
+
+## Capability gotchas
+
+- Each model's `inputs` block is authoritative: supported `aspect_ratios`, `resolutions`, `quality_options`, `start_frame`/`end_frame`, `max_reference_images/videos/audio`, `multi_prompt`, `audio_toggle`. Passing an unsupported input fails with a clear error — check first, don't trial-and-error paid calls.
+- Most video models support only 16:9 / 9:16 / 1:1. A 3:4 request hard-fails on most.
+- `--seed` reproduces a specific output on models that support it (e.g. Flux, Ideogram V4); everything else ignores it. You do not need a seed for variation — `--num` already varies.
+- `--rendering-speed` applies to Ideogram (V3: `Default`/`Turbo`/`Quality`; V4: `Turbo`/`Balanced`/`Quality`) and affects image cost — pass it to `videodraft costs ... --rendering-speed <tier>` for an accurate estimate. Always trust `videodraft models image --json` over this list; new models and tiers appear there the moment the platform ships them, with no CLI update.
+- Reference inputs: `--ref <img>` (images), `--ref-video <v>` (Seedance 2, Wan 2.7), `--ref-audio <a>` (Seedance 2). The CLI uploads local files for all of these, so you can pass a path or a URL. `--segment "<prompt>:<seconds>"` (repeatable) drives multi-prompt models (Kling 3.0 / 3.0 Turbo / O3); total 3-15s. `generate image --video-ref` is the nano-banana-2 video reference.
+- The top-level prompt is OPTIONAL for `generate video` with multi-prompt models and for Kling 3.0 Turbo (`--model kling-v3-turbo`) image-to-video — a `--segment`-only or `--start-image`-only call is valid. Every other model still needs a prompt; the server enforces per-model rules.
+- AI Production: `videodraft produce <project> --mode full_video` generates one Seedance 2 video per scene; poll with `videodraft generations`, then `videodraft finalize <project>` swaps them into the timeline before `export`.
+
+## Cost model
+
+- Images: per image (× `--num`). Matrix-priced models (GPT-Image, Nano Banana Pro) vary by resolution/quality.
+- Video: usually credits/second × duration; rate depends on model + resolution + quality + native audio on/off.
+- Shot-image batches: one image per shot (+1 grid image per scene in `--grid` mode) — the largest single spend in the pipeline.
+- Avatar renders: ~10 credits/sec at 480p, ~20/sec at 720p.
+- Upscales: priced by scale and source size.
+
+Quote before spending:
+
+```bash
+videodraft costs google-veo3.1 --type video --duration 8 --resolution 1080p --audio
+videodraft generate video "..." --estimate        # same quote, inline
+videodraft credits                                 # current balance
+```

package/skills/videodraft/references/pipeline.md

@@ -0,0 +1,59 @@
+# VideoDraft pipeline reference
+
+Everything here works through the CLI (`videodraft <command>` / `videodraft call <tool>`) or the MCP connector (tool names in backticks). One backend; pick the surface you have.
+
+## Stages and their tools
+
+| Stage | CLI | Underlying tool |
+|---|---|---|
+| Idea → full storyboard project | `videodraft create "<idea>"` | `generate_storyboard_from_idea` |
+| Idea → script only (stop there) | `videodraft create "<idea>" --script-only` | `generate_script_from_idea` |
+| Footage IS the video | `videodraft call generate_storyboard_from_media` | `generate_storyboard_from_media` |
+| Batch shot images | `videodraft shots <project>` | `generate_shot_images` |
+| One shot image | `videodraft generate image --project <id> --scene N --shot M` | `generate_image` |
+| Produce (voiceover, captions, timeline) | `videodraft produce <project>` | `produce_project` |
+| Per-shot motion prompts | `videodraft video-prompts <project>` | `generate_video_prompts` |
+| Motion clip for a shot | `videodraft generate video --project <id>` | `generate_video` |
+| Attach a finished clip to the timeline | `videodraft attach <project> --scene N --shot M --media <url> --type video` | `attach_media_to_shot` |
+| Background music | `videodraft generate music --attach <project>` | `generate_music` / `set_background_music` |
+| Scene voiceover | `videodraft generate voiceover --project <id> --scene N` | `generate_voiceover` |
+| Final MP4 | `videodraft export <project>` | `export_video` + `check_export_status` |
+
+## Rules that prevent broken results
+
+- **The storyboard is generated FROM the script**, never from the raw idea. `videodraft create` runs the whole chain correctly. Don't call `generate_storyboard_scenes` with a raw idea as the "script".
+- **Visual consistency**: never generate a storyboard shot in isolation. Shot prompts carry `[[asset:Name]]` / `[[shot:X-Y]]` tags that `generate_shot_images` resolves against the project's visual assets and prior shots. When generating a single shot whose prompt has no tags, pass `--ref` images yourself (the project's visual assets and/or the previous shot's image — `projects get` exposes both). Grid mode (`--grid`) gives the strongest cross-shot consistency.
+- **Hold off generating shot images while the user is still iterating** on storyboard structure.
+- **produce → export ordering**: `export` requires a produced project where every production scene has timeline media. If `produce` returns `generating_shot_images`, poll the job ids it returns, then re-run produce.
+- **Generated motion clips do not auto-attach**: after `generate video` completes, attach the clip with `attach_media_to_shot` (`media_type:"video"`, include `duration_seconds`) — it replaces the production timeline clip while keeping the storyboard still.
+- **Timeouts on the one-shot create**: if `create` times out at the transport layer, the project was still created server-side — `videodraft projects list`, take the most recent, and resume with its id. Don't start a duplicate.
+
+## User-attached media: classify roles first
+
+For EACH attached file decide:
+
+- **visual_asset** — recurring reference (character / product / location / style). Upload, then pass in `visual_assets` of `generate_storyboard_from_idea` (via `videodraft call`), or add to an existing project with `add_visual_assets`. Type must be one of `character | object | location | style | custom` with a short name + concrete description.
+- **shot** — the media IS footage for the video. Whole video = footage → `generate_storyboard_from_media`. Idea + footage → `generate_storyboard_from_idea` with `shot_media`. Existing storyboard → `attach_media_to_shots`.
+- **reference** — inspiration only → fold a description into the idea/instructions; don't place it as a shot or asset.
+
+Ambiguous (e.g. a person holding a product)? Ask the user.
+
+Uploads persist in the media library — recall later with `videodraft media list`.
+
+## Editing project data safely
+
+1. `videodraft call get_project_schema` — read the structure once per session.
+2. `videodraft projects get <id> --raw` — the exact editable blob.
+3. Modify; then `videodraft call update_project --stdin` with `{"project_id": "...", "data": {...}}`.
+   - Objects deep-merge key-by-key; **arrays replace wholesale** — send the complete array you're changing (e.g. all of `storyboard.scenes`).
+   - Scene shot arrays (`image_prompt` / `shot_types` / `shot_actions` / `search_prompt` / `preview_media`) are auto-aligned; fix-ups come back as warnings.
+4. Snapshot before risky edits: `videodraft checkpoint create <id> --name "before re-script"`. Restore with `videodraft checkpoint restore <id> <version>`.
+
+## AI Studio sessions (standalone generations)
+
+Project generations group automatically. For standalone work in a long conversation, create one session up front and reuse it:
+
+```bash
+SESSION=$(videodraft call create_ai_studio_session --arg name="Fox brand explorations" --json | jq -r .session_id)
+videodraft generate image "..." --session "$SESSION"
+```