videodraft 0.0.0 → 0.1.0

package/README.md

@@ -1,5 +1,121 @@
 # videodraft
 
-The official **VideoDraft** CLI — create AI videos, images, voiceovers and music from your terminal, for humans and coding agents.
+The official [VideoDraft](https://videodraft.ai) CLI — create AI videos, images, voiceovers and music from your terminal. Built for humans **and** coding agents: every command supports `--json`, exit codes are stable, async jobs are first-class.
 
-🚧 Launching soon — https://videodraft.ai/cli
+```bash
+npx videodraft login
+npx videodraft generate image "a red fox in snow, cinematic" --download ./out/
+npx videodraft create "30s launch video for our espresso machine" --ar 9:16
+```
+
+## Install
+
+```bash
+npm install -g videodraft     # or: npx videodraft <command>
+```
+
+Requires Node ≥ 20.
+
+## Authenticate
+
+```bash
+videodraft login                    # opens your browser (OAuth)
+videodraft login --token vd_mcp_…   # personal access token from https://app.videodraft.ai/mcp-keys
+export VIDEODRAFT_API_KEY=vd_mcp_…  # headless / CI — no login command needed
+```
+
+Credentials are stored in `~/.config/videodraft/config.json` (0600). `videodraft logout` revokes and clears them.
+
+## The pipeline
+
+```bash
+videodraft credits                              # know your budget
+videodraft create "<idea>" --ar 9:16            # idea → script → visual assets → storyboard
+videodraft shots <project> --grid --estimate    # preview the cost…
+videodraft shots <project> --grid               # …then batch-generate every shot image
+videodraft produce <project>                    # voiceovers + captions + production timeline
+videodraft export <project> --download final.mp4
+```
+
+Single assets don't need a project:
+
+```bash
+videodraft generate image "isometric workspace, warm light" --num 4 --download "./out/{job_id}_{index}.{ext}"
+videodraft generate video "slow dolly over a misty lake" --model google-veo3.1 --duration 6 --estimate
+videodraft generate voiceover "Welcome to VideoDraft" --download welcome.mp3
+videodraft generate music "minimal ambient, 60 BPM" --download bgm.mp3
+videodraft upscale image ./photo.png --scale 4x --download ./photo-4x.png
+videodraft avatar create ./founder.jpg --script "$(videodraft avatar script 'our launch' --json | jq -r .script)"
+```
+
+## Commands
+
+| Group | Commands |
+|---|---|
+| Auth | `login` `logout` `whoami` |
+| Account | `credits` `costs [model]` `models [image\|video\|voices\|styles]` `workspaces` `sessions list/create` |
+| Projects | `projects list/get/delete/favorite/open` `checkpoint create/list/restore` |
+| Pipeline | `create` `shots` `produce` (`--mode full_video`) `attach` `finalize` `export` `export-status` `video-prompts` |
+| Generate | `generate image/video/voiceover/music` `upscale image/video` `avatar script/create/render/get/list` |
+| Jobs | `status <job>` `wait <job>` `generations` |
+| Media | `upload <file>` `media list` `describe <url\|file>` `download <url>` |
+| Everything else | `tools list` `tools schema <name>` `call <tool> --args '<json>'` |
+| Agents | `skills install [--agent claude\|codex\|cursor]` `skills path` |
+| Utility | `config get/set/path` `completion bash\|zsh` `docs` `--version` |
+
+`call` reaches **every** VideoDraft API tool (the full MCP catalog), including ones without a curated command — new platform features work in the CLI the day they ship.
+
+## For agents and scripts
+
+- `--json` on any command prints a single JSON document on stdout.
+- Exit codes: `0` ok · `1` error · `2` usage · `3` auth required · `4` insufficient credits.
+- Async generations wait by default; `--no-wait` returns `{job_id}` immediately, `videodraft wait <job...>` resumes, `--wait-timeout 30m --wait-interval 5s` tune polling.
+- **Many jobs at once?** Submit them all with `--no-wait`, then `videodraft wait <id1> <id2> ...` — one process polls every job with ONE batched request per tick (don't spawn N parallel `wait` processes). Polling backs off adaptively (3s → 15s with jitter) on long jobs unless you pin `--wait-interval`.
+- `--download` templates: `{job_id}`, `{index}`, `{ext}`, `{name}`. Downloads are echoed as `downloaded_files[]` in `--json` output.
+- Local file → public URL anywhere a URL is expected (`--ref photo.jpg`), or explicitly via `videodraft upload`.
+- `NO_COLOR` and `--no-color` are respected; output is uncolored when piped.
+
+Install the VideoDraft skill so your agent knows the workflow:
+
+```bash
+npx videodraft skills install                  # zero-install: npx fetches the CLI and installs the skill
+videodraft skills install                      # if the CLI is on PATH — auto-detects your installed agents
+videodraft skills install --agent claude,codex # target specific agents (repeatable/comma; --all for every agent)
+npx skills add videodraft-ai/cli               # via the vercel-labs skills tool (discovery / 69-agent multiselect)
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|---|---|
+| `VIDEODRAFT_API_KEY` | Bearer token (`vd_mcp_…`) — skips the login flow |
+| `VIDEODRAFT_BASE_URL` | Target server (default `https://app.videodraft.ai`) |
+| `VIDEODRAFT_CONFIG_DIR` | Config location (default `~/.config/videodraft`) |
+| `VIDEODRAFT_TELEMETRY=0` | Disable telemetry |
+| `DO_NOT_TRACK=1` | Disable telemetry (and the update check) |
+| `VIDEODRAFT_NO_UPDATE_CHECK=1` | Disable the update notice |
+| `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` | Proxy support |
+
+## Telemetry
+
+The CLI sends anonymous usage events (command name, CLI version, OS, duration, success/error class — **never prompts, file contents, or arguments**) to help us improve it. Opt out any time:
+
+```bash
+videodraft config set telemetry false   # or VIDEODRAFT_TELEMETRY=0 / DO_NOT_TRACK=1
+```
+
+## Embedding (`videodraft/client`)
+
+The CLI's core is exported for programmatic use (Node ≥ 20 and Bun):
+
+```ts
+import { VideoDraftClient, resolveAuth } from "videodraft/client";
+
+const { tokenProvider, baseUrl } = resolveAuth({}); // flag/env/config-store resolution
+const client = new VideoDraftClient({ tokenProvider, baseUrl });
+const me = await client.callTool("whoami");
+```
+
+## License
+
+MIT © VideoDraft

package/dist/client.d.ts

@@ -0,0 +1,363 @@
+/**
+ * JSON-RPC 2.0 client for the VideoDraft MCP endpoint (POST {base}/api/mcp).
+ *
+ * Runtime-agnostic by design: no commander, no prompts, no process.exit, no
+ * console — this file is part of the `videodraft/client` subpath export the
+ * macOS app's sidecar consumes. Errors are thrown, never printed.
+ */
+interface TokenProvider {
+    /** Return a bearer token (vd_mcp_...). Throw AuthError when none is available. */
+    getAccessToken(): Promise<string>;
+    /**
+     * Called once after a 401. Return a fresh token to retry with, or null to
+     * give up (the 401 then surfaces as AuthError).
+     */
+    onUnauthorized?(): Promise<string | null>;
+}
+interface VideoDraftClientOptions {
+    tokenProvider: TokenProvider;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    userAgent?: string;
+    /** Per-request timeout in ms. Generation submits can be slow; default 300s (server maxDuration). */
+    requestTimeoutMs?: number;
+}
+interface McpToolInfo {
+    name: string;
+    description: string;
+    inputSchema: unknown;
+}
+declare class VideoDraftClient {
+    readonly baseUrl: string;
+    private readonly tokenProvider;
+    private readonly fetchImpl;
+    private readonly userAgent;
+    private readonly requestTimeoutMs;
+    private nextId;
+    constructor(options: VideoDraftClientOptions);
+    get endpoint(): string;
+    rpc<T = any>(method: string, params?: unknown): Promise<T>;
+    private post;
+    /**
+     * Batch several JSON-RPC requests into ONE HTTP round trip (the server
+     * implements JSON-RPC 2.0 batching). With N concurrent jobs this turns N
+     * polling requests per tick into 1 — the difference between 50 waiting CLIs
+     * generating ~17 req/s and ~0.3 req/s against /api/mcp.
+     * Results are matched by id (order-independent per spec).
+     */
+    rpcBatch(calls: Array<{
+        method: string;
+        params?: unknown;
+    }>): Promise<any[]>;
+    /**
+     * Call several tools in one batched HTTP request. Per-item failures come
+     * back as { ok:false, error } instead of throwing, so one failed job can't
+     * abort polling of its siblings.
+     */
+    callToolBatch(calls: Array<{
+        name: string;
+        args?: Record<string, unknown>;
+    }>): Promise<Array<{
+        ok: boolean;
+        result?: any;
+        error?: string;
+    }>>;
+    /**
+     * Call an MCP tool and return its parsed result.
+     * The server wraps results as { content: [{type:"text", text}], isError } —
+     * text is JSON for successes and "Error: ..." for tool failures.
+     */
+    callTool<T = any>(name: string, args?: Record<string, unknown>): Promise<T>;
+    listTools(): Promise<McpToolInfo[]>;
+    ping(): Promise<void>;
+}
+/** Static token provider — for PATs and pre-resolved tokens. */
+declare function staticTokenProvider(token: string): TokenProvider;
+
+/**
+ * Token resolution + the multi-process-safe OAuth refresh provider.
+ *
+ * Resolution order (first hit wins):
+ *   1. explicit token (--token flag)
+ *   2. VIDEODRAFT_API_KEY env
+ *   3. the profile in the config store (PAT, or OAuth with auto-refresh)
+ *
+ * OAuth refresh tokens are SINGLE-USE (the server rotates them), and the CLI
+ * shares its config store with other consumers (the macOS app's sidecar). So
+ * refresh runs under a cross-process file lock and re-reads the store after
+ * acquiring it — if another process already rotated, we use its fresh token
+ * instead of redeeming a now-dead refresh token.
+ */
+
+interface ResolvedAuth {
+    tokenProvider: TokenProvider;
+    baseUrl: string;
+    source: "flag" | "env" | "profile";
+    profileName?: string;
+}
+declare function profileTokenProvider(profileName: string, env?: NodeJS.ProcessEnv): TokenProvider;
+declare function resolveAuth(options: {
+    token?: string;
+    baseUrl?: string;
+    profile?: string;
+    env?: NodeJS.ProcessEnv;
+}): ResolvedAuth;
+
+/**
+ * Config store: $VIDEODRAFT_CONFIG_DIR || $XDG_CONFIG_HOME/videodraft || ~/.config/videodraft
+ *
+ * Deliberately NOT ~/.videodraft — the VideoDraft macOS app owns ~/videodraft/
+ * (user workspaces) and dot/no-dot adjacency invites confusion.
+ *
+ * The schema below is a documented contract: the macOS app's sidecar reads the
+ * same store to inherit `videodraft login` credentials (the same way it
+ * inherits `claude login` / `codex login`). Bump `version` on breaking changes.
+ */
+interface Profile {
+    base_url: string;
+    auth_kind: "pat" | "oauth";
+    access_token: string;
+    /** OAuth only. */
+    refresh_token?: string;
+    /** OAuth only — ISO timestamp the access token expires at. */
+    expires_at?: string;
+    /** OAuth only — the client_id the grant belongs to. */
+    client_id?: string;
+}
+interface CliConfig {
+    version: 1;
+    active_profile: string;
+    profiles: Record<string, Profile>;
+    /** Anonymous machine id for opt-out telemetry. */
+    anonymous_id?: string;
+    /** Explicit telemetry opt-out persisted via `videodraft config set telemetry false`. */
+    telemetry?: boolean;
+    /** Epoch ms of the last npm update check. */
+    last_update_check?: number;
+}
+declare const DEFAULT_BASE_URL = "https://app.videodraft.ai";
+declare function configDir(env?: NodeJS.ProcessEnv): string;
+declare function configPath(env?: NodeJS.ProcessEnv): string;
+declare function readConfig(env?: NodeJS.ProcessEnv): CliConfig;
+/** Atomic write (tmp + rename), 0700 dir / 0600 file. */
+declare function writeConfig(config: CliConfig, env?: NodeJS.ProcessEnv): void;
+declare function updateConfig(mutate: (config: CliConfig) => void, env?: NodeJS.ProcessEnv): CliConfig;
+declare function getProfile(name?: string, env?: NodeJS.ProcessEnv): {
+    name: string;
+    profile: Profile | undefined;
+    config: CliConfig;
+};
+
+/**
+ * Polling for async work: generation jobs (check_generation_status) and
+ * video exports (check_export_status).
+ */
+
+interface PollOptions {
+    intervalMs?: number;
+    timeoutMs?: number;
+    /**
+     * Adaptive backoff (default true): the effective interval grows as a job
+     * runs long (base → ×2 after 60s → ×3 after 3min, capped at 15s) with ±10%
+     * jitter so many concurrent CLIs don't poll in lockstep. Set false (the CLI
+     * does this when --wait-interval is passed explicitly) for a fixed cadence.
+     */
+    adaptive?: boolean;
+    /** Called every poll with the latest payload (drives spinners). */
+    onTick?: (status: string, payload: any) => void;
+}
+/** Effective poll delay for a job that's been running `elapsedMs`. */
+declare function nextPollDelay(baseMs: number, elapsedMs: number, adaptive?: boolean): number;
+interface GenerationResult {
+    status: string;
+    outputUrls: string[];
+    payload: any;
+}
+/** Extract output media URLs across the server's result shapes. */
+declare function extractOutputUrls(payload: any): string[];
+declare function pollGeneration(client: VideoDraftClient, jobId: string, options?: PollOptions): Promise<GenerationResult>;
+/**
+ * Poll MANY jobs from ONE process with ONE batched JSON-RPC request per tick.
+ * This is the multi-CLI answer: N parallel generations should not mean N idle
+ * Node processes and N req/tick — submit with --no-wait, then
+ * `videodraft wait <id1> <id2> ...` (or the macOS app's sidecar calling this).
+ * Per-job tool failures resolve that job as status "failed" without aborting
+ * the rest.
+ */
+declare function pollGenerationsBatch(client: VideoDraftClient, jobIds: string[], options?: PollOptions & {
+    onJobDone?: (jobId: string, result: GenerationResult) => void;
+}): Promise<Map<string, GenerationResult>>;
+declare function pollExport(client: VideoDraftClient, ref: {
+    exportId?: string;
+    projectId?: string;
+}, options?: PollOptions): Promise<{
+    status: string;
+    videoUrl?: string;
+    payload: any;
+}>;
+/** Poll many jobs concurrently (used by `shots --wait` batches). */
+declare function pollGenerations(client: VideoDraftClient, jobIds: string[], options?: PollOptions): Promise<GenerationResult[]>;
+
+/**
+ * Download generated media to local files.
+ *
+ * Path templates (genmedia-style): {job_id} {index} {ext} {name}
+ *   videodraft generate image "..." --download "./out/{job_id}_{index}.{ext}"
+ * A template without placeholders and without an extension is treated as a
+ * directory: <dir>/<job_id>_<index>.<ext>.
+ */
+interface DownloadedFile {
+    url: string;
+    path: string;
+    bytes: number;
+}
+declare function extFromUrl(url: string, fallback?: string): string;
+declare function renderTemplate(template: string, vars: {
+    job_id?: string;
+    index: number;
+    ext: string;
+    name?: string;
+}): string;
+declare function downloadUrl(url: string, destPath: string, fetchImpl?: typeof fetch): Promise<DownloadedFile>;
+declare function downloadOutputs(urls: string[], template: string, vars: {
+    job_id?: string;
+    name?: string;
+}, fetchImpl?: typeof fetch): Promise<DownloadedFile[]>;
+
+/**
+ * Local-file upload via the MCP two-step flow:
+ *   create_media_upload → PUT bytes to the presigned upload_url → finalize_media_upload
+ * The bytes go directly to GCS; they never pass through the MCP server.
+ */
+
+declare function guessContentType(filename: string): string | undefined;
+interface UploadResult {
+    url: string;
+    file_path?: string;
+    [key: string]: unknown;
+}
+declare function uploadFile(client: VideoDraftClient, localPath: string, options?: {
+    contentType?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<UploadResult>;
+
+/**
+ * Error taxonomy + stable exit codes.
+ *
+ *   0  success
+ *   1  generic / server / network error
+ *   2  usage error (bad flags/args — commander's default)
+ *   3  authentication required or invalid
+ *   4  insufficient credits
+ *
+ * Agents and scripts can branch on these; they are part of the CLI contract
+ * and documented in the README.
+ */
+declare const EXIT: {
+    readonly OK: 0;
+    readonly ERROR: 1;
+    readonly USAGE: 2;
+    readonly AUTH: 3;
+    readonly CREDITS: 4;
+};
+declare class CliError extends Error {
+    exitCode: number;
+    /** One-line remediation shown under the error (human mode only). */
+    hint?: string;
+    constructor(message: string, exitCode?: number, hint?: string);
+}
+declare class AuthError extends CliError {
+    constructor(message?: string);
+}
+/** JSON-RPC layer error (the envelope, not the tool). */
+declare class RpcError extends CliError {
+    code: number;
+    data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+/** A tools/call result that came back isError:true. */
+declare class ToolError extends CliError {
+    toolName: string;
+    constructor(toolName: string, message: string);
+}
+declare class TimeoutError extends CliError {
+    constructor(message: string);
+}
+
+/**
+ * OAuth 2.1 authorization-code + PKCE flow against the VideoDraft AS,
+ * using an RFC 8252 loopback redirect (http://127.0.0.1:<ephemeral-port>/callback).
+ *
+ * Server contract (app/api/oauth/* in the VideoDraft app):
+ *   GET  /api/oauth/authorize  ?response_type=code&client_id&redirect_uri&scope
+ *                              &state&code_challenge&code_challenge_method=S256&resource
+ *   POST /api/oauth/token      form or JSON; authorization_code | refresh_token grants
+ *   POST /api/oauth/register   RFC 7591 DCR (https or http-loopback redirect URIs only)
+ *   POST /api/oauth/revoke     RFC 7009
+ *
+ * Client identity: the static public client `vd_client_cli` (pre-registered in
+ * oauth_clients — see sql/ in this repo). When that id is missing on the target
+ * server (e.g. a fresh local stack), we fall back to Dynamic Client Registration
+ * and persist the issued client_id in the profile.
+ */
+declare const STATIC_CLI_CLIENT_ID = "vd_client_cli";
+interface OAuthTokens {
+    access_token: string;
+    refresh_token: string;
+    expires_in: number;
+    scope?: string;
+}
+declare function createPkcePair(): {
+    verifier: string;
+    challenge: string;
+};
+declare function buildAuthorizeUrl(params: {
+    baseUrl: string;
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    codeChallenge: string;
+}): string;
+/**
+ * Is this client_id known to the server? The authorize endpoint renders a
+ * non-redirect 400 HTML page for an unknown client, and 3xx-redirects to the
+ * consent page for a valid request — probe with redirect:"manual" so we can
+ * fall back to DCR before ever opening a browser tab on an error page.
+ */
+declare function probeClientId(baseUrl: string, clientId: string, redirectUri: string, fetchImpl?: typeof fetch): Promise<boolean>;
+/** RFC 7591 dynamic registration fallback. Returns the issued client_id. */
+declare function registerCliClient(baseUrl: string, fetchImpl?: typeof fetch): Promise<string>;
+/**
+ * Run the loopback listener + browser round trip and return the authorization
+ * code. `onAuthorizeUrl` receives the URL to open (the command layer opens the
+ * browser and prints it — this module stays headless/testable).
+ */
+declare function authorizeViaLoopback(params: {
+    baseUrl: string;
+    clientId: string;
+    onAuthorizeUrl: (url: string) => void | Promise<void>;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    code: string;
+    redirectUri: string;
+    verifier: string;
+}>;
+declare function exchangeCode(params: {
+    baseUrl: string;
+    clientId: string;
+    code: string;
+    redirectUri: string;
+    verifier: string;
+    fetchImpl?: typeof fetch;
+}): Promise<OAuthTokens>;
+declare function refreshAccessToken(params: {
+    baseUrl: string;
+    clientId: string;
+    refreshToken: string;
+    fetchImpl?: typeof fetch;
+}): Promise<OAuthTokens | null>;
+/** RFC 7009 revocation — best-effort, used by `videodraft logout`. */
+declare function revokeToken(baseUrl: string, token: string, fetchImpl?: typeof fetch): Promise<void>;
+
+export { AuthError, type CliConfig, CliError, DEFAULT_BASE_URL, type DownloadedFile, EXIT, type GenerationResult, type McpToolInfo, type PollOptions, type Profile, type ResolvedAuth, RpcError, STATIC_CLI_CLIENT_ID, TimeoutError, type TokenProvider, ToolError, type UploadResult, VideoDraftClient, type VideoDraftClientOptions, authorizeViaLoopback, buildAuthorizeUrl, configDir, configPath, createPkcePair, downloadOutputs, downloadUrl, exchangeCode, extFromUrl, extractOutputUrls, getProfile, guessContentType, nextPollDelay, pollExport, pollGeneration, pollGenerations, pollGenerationsBatch, probeClientId, profileTokenProvider, readConfig, refreshAccessToken, registerCliClient, renderTemplate, resolveAuth, revokeToken, staticTokenProvider, updateConfig, uploadFile, writeConfig };