@mevdragon/vidfarm-devcli 0.3.5 → 0.4.0

package/README.md

@@ -48,4 +48,6 @@ npx -y @mevdragon/vidfarm-devcli <template_id>
 
 Flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or `VIDFARM_API_KEY`), `--share`, `--refetch`. Use `dev-serve` as an explicit subcommand to skip the fetch step and just serve an existing directory.
 
+Beyond the local editor loop, the devcli also wraps the **entire director REST flow** as 1:1 commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render`, `approve`, `schedule`, `posts`, `upload`/`download`, plus a raw `vidfarm api <METHOD> <path>` passthrough. Each maps to exactly one REST route and prints the prod frontend URL to open. Run `vidfarm --help` for the full surface, or see `SKILL.director.md` § "`vidfarm-devcli` — full command surface".
+
 See `SKILL.platform.md` § "Local editor dev loop" for the request-rewrite / SSE reload flow.

package/SKILL.director.md

@@ -1,6 +1,6 @@
 ---
 name: vidfarm-director
-description: Use Vidfarm as a director. Fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, publish to MP4, and share. Includes login, provider keys, discovery, publishing, versioning, and billing.
+description: Use Vidfarm as a director. Browse/add inspiration videos, fork a template into a composition, edit it in the Trackpad Editor (timeline-based like Premiere/DaVinci), auto-decompose source video into scenes, render to MP4, approve into a shareable post, and schedule it. Includes login, provider keys, discovery, versioning, uploads/downloads, and billing. Every step is available as a raw REST route and as a 1:1 `vidfarm-devcli` command.
 ---
 
 # Vidfarm Director
@@ -82,6 +82,16 @@ Each template exposes a public preview:
 
 Directors don't edit templates directly. They fork.
 
+### Add your own source (inspiration)
+
+To bring a new viral video into the catalog as a **private** template you own, ingest its social URL:
+
+- `POST /discover/templates { source_url, tagline?, notes? }` — accepts TikTok / YouTube / Instagram / Twitter-X URLs only. The video download runs async; the response is the inspiration record (`202`, `status: "processing"`). The card finalizes into a private `template_...` the next time `GET /discover/feed` is polled (the feed poll doubles as the completion check).
+- `DELETE /discover/templates/:entryId` — remove a private inspiration/template you own (accepts either the `inspiration_...` or minted `template_...` id).
+- `POST /api/v1/inspirations/:inspirationId/decompose { user_prompt? }` — AI-decompose an inspiration's downloaded video into scenes (requires a saved provider key; same 120s source cap as auto-decompose).
+
+devcli: `vidfarm inspiration-add <url>`, `vidfarm inspiration-rm <id>`, `vidfarm inspiration-decompose <id>`, and `vidfarm discover` to browse.
+
 ## Fork a template
 
 ```
@@ -193,9 +203,9 @@ Use it whenever you need to know what the video says or shows: writing/translati
 - **Editor chat (frontend AI)** exposes this as the optional `video_context` tool — the copilot calls it on demand.
 - **Desktop agents (Claude Code / Codex)**: `vidfarm edit <template_id>` syncs the same payload to `video-context.json` on disk next to `composition.html` (use `--refetch` to refresh it after a new decompose), or fetch the route directly.
 
-## Publish
+## Render (publish to MP4)
 
-Publishing renders the fork's current working state to an MP4 using shared Remotion Lambda. The route is `/export`:
+Rendering publishes the fork's current working state to an MP4 using shared Remotion Lambda. In the Trackpad Editor this is the **Render** button; the REST route is still named `/export` (the route name predates the UI rename — treat "Render", "publish", and `/export` as the same operation). The devcli exposes it as `vidfarm render <forkId> [--wait]`.
 
 ```
 POST /api/v1/compositions/:forkId/export
@@ -214,6 +224,41 @@ Response includes `{ ok, renderId, status: "RUNNING" | "SUCCEEDED" | "FAILED", p
 
 Every publish creates an immutable version snapshot at `versions/<N>/composition.html` and `versions/<N>/composition.json`.
 
+## Approve a finished post
+
+A render produces a bare MP4 URL. **Approving** wraps that MP4 (plus caption, title, pinned comment, and any carousel slides) into a shareable preview page — the phone-mockup page a human opens to review and copy the post.
+
+```
+POST /api/v1/approved/posts
+Content-Type: application/json
+
+{ "caption": "required", "title": "optional", "pinned_comment": "optional", "tracer": "optional",
+  "media": [ { "url": "https://.../output.mp4", "kind": "video", "role": "primary" } ] }
+```
+
+`caption` is required. `media[]` items take `{ url, kind?: "image"|"video"|..., role?: "primary"|"slide"|... }`. Response (`201`) is the approved post including **`share_url`** — the prod frontend page for previewing/sharing. Surface that URL to the user; it is the headline output of this step.
+
+- `GET /api/v1/approved/posts` — list your approved posts
+- `GET /api/v1/approved/posts/:postId` — read one (returns `share_url`, `download_zip_url`)
+
+devcli: `vidfarm approve --video <mp4-url> --caption "..."` prints the `share_url` as a first-class openable link; `vidfarm posts` lists, `vidfarm post <id>` reads one.
+
+## Schedule a post
+
+Schedule an approved post to a connected destination channel (FlockPoster social account or email) at one ISO timestamp:
+
+```
+POST /api/v1/approved/posts/:postId/schedules
+Content-Type: application/json
+
+{ "destination_type": "flockposter" | "email", "destination_id": "<channel or email>",
+  "scheduled_at": "2026-07-10T14:00:00Z", "timezone": "America/New_York", "additional_notes": "optional" }
+```
+
+Minimum 10-minute lead time. Response (`201`) is the schedule record. Browse existing schedules with `GET /api/v1/approved/posts/:postId/schedules`.
+
+devcli: `vidfarm schedule <postId> --at <iso> --to <destinationId> [--type flockposter|email]`, and `vidfarm schedules <postId>` to browse.
+
 ## Version history
 
 ```
@@ -300,17 +345,65 @@ For agents that operate Vidfarm headlessly, the typical loop is:
 
 Send a stable `tracer` on export so retries are traceable and filterable in job history — but note that submission is **not idempotent**: every POST creates a new job (and a new charge) even with the same tracer. Do not blind-retry expensive submissions; check the render status first.
 
-## Local dev loop with `vidfarm-devcli`
+## `vidfarm-devcli` — full command surface
+
+`@mevdragon/vidfarm-devcli` wraps the **entire director REST flow** as CLI commands. It is a thin shell over the REST API, not a second implementation: **every named command maps 1:1 to exactly one REST route**, and all it adds is fork auto-resolution, the `vidfarm-api-key` header, prod frontend links in the output, render-poll waiting, and the multi-step upload/download flows. Auth via `--api-key <key>` or `VIDFARM_API_KEY`.
+
+**Raw REST vs devcli — your choice.** If you want full control, call the REST API directly (or use the raw passthrough `vidfarm api <METHOD> <path> [--data <json>] [--query k=v]`). If you want ergonomics + openable frontend URLs, use the named commands. They are interchangeable — pick per call.
+
+| Command | REST route | Flow step |
+|---|---|---|
+| `vidfarm discover` | `GET /discover/feed` | browse inspiration/templates |
+| `vidfarm inspiration-add <url>` | `POST /discover/templates` | add your own source |
+| `vidfarm inspiration-rm <id>` | `DELETE /discover/templates/:id` | remove a private one |
+| `vidfarm inspiration-decompose <id>` | `POST /api/v1/inspirations/:id/decompose` | AI-decompose an inspiration |
+| `vidfarm fork <template_id>` | `POST /api/v1/compositions` | fork a template |
+| `vidfarm decompose <forkId>` | `POST .../compositions/:forkId/auto-decompose` | split source into scenes |
+| `vidfarm ghostcut <forkId>` | `GET .../compositions/:forkId/ghostcut` | subtitle-removal status |
+| `vidfarm snapshot <forkId>` | `POST .../compositions/:forkId/versions` | save composition fork version |
+| `vidfarm versions <forkId>` | `GET .../compositions/:forkId/versions` | list versions |
+| `vidfarm render <forkId> [--wait]` | `POST .../compositions/:forkId/export` | render video to MP4 |
+| `vidfarm render-status <forkId> <renderId>` | `GET .../compositions/:forkId/renders/:renderId` | poll a render |
+| `vidfarm visibility <forkId> <private\|public>` | `PATCH .../compositions/:forkId/visibility` | set visibility |
+| `vidfarm clone <forkId>` | `POST .../compositions/:forkId/clone` | clone a fork |
+| `vidfarm share-link <forkId>` | `POST .../compositions/:forkId/share-links` | mint a share URL |
+| `vidfarm approve --video <url> --caption "…"` | `POST /api/v1/approved/posts` | approve post (prints `share_url`) |
+| `vidfarm posts` / `vidfarm post <id>` | `GET /api/v1/approved/posts[/:id]` | browse approved posts |
+| `vidfarm schedule <postId> --at <iso> --to <dest>` | `POST /api/v1/approved/posts/:postId/schedules` | schedule a post |
+| `vidfarm schedules <postId>` | `GET /api/v1/approved/posts/:postId/schedules` | browse scheduled posts |
+| `vidfarm login <email>` / `vidfarm verify <email> <code>` | `POST /api/v1/user/request-otp` · `verify-otp` | get an API key |
+| `vidfarm whoami` | `GET /api/v1/user/me` | who am I |
+| `vidfarm provider-keys` / `vidfarm add-provider-key <p> <secret>` | `GET`·`POST /api/v1/user/me/provider-keys` | manage AI keys |
+| `vidfarm upload <file>` | `POST /api/v1/user/me/temporary-files/upload` | upload → durable URL |
+| `vidfarm download <url> [dest]` | (streams any URL to disk) | download media |
+
+**Frontend URLs are first-class output.** Every command that has a human-openable page (editor, discover, approved-post preview, share link) prints that prod frontend URL as a highlighted line. `render --wait` polls to completion and prints the final MP4 URL; `approve` prints the approved-post `share_url`. Add `--json` to any command for pure JSON (agent-friendly, no banners).
+
+**Uploads/downloads live in the devcli** because they are genuine multi-step / streaming flows: `upload` posts the file as multipart to the temporary-files route and prints the durable URL to drop into a composition or approved post; `download` streams any Vidfarm/media URL to disk.
+
+## Local dev loop (edit on disk)
 
 For iterating on a composition on disk (e.g. Claude Code editing HTML directly), pair the hosted editor with a local composition directory:
 
 ```bash
 npx -y @mevdragon/vidfarm-devcli <template_id>
-# → downloads composition.html/json + manifest.json into .vidfarm/<template_id>/
+# → downloads composition.html/json + manifest.json + video-context.json into .vidfarm/<template_id>/
+# → downloads the videos + per-scene frames for local analysis (see below)
 # → starts dev-serve on http://localhost:4321
 # → prints https://vidfarm.cc/editor/<template_id>?fork=<forkId>&dev=http%3A%2F%2Flocalhost%3A4321
 ```
 
+### Local media for analysis (`sources.json`, videos, frames)
+
+So a coding agent can *see* what it is editing — not just read URLs — `vidfarm edit` also drops the actual media next to the composition:
+
+- **`original.mp4`** — the raw source video, before any processing.
+- **`source.mp4`** — the video the composition timeline actually renders from. This differs from `original.mp4` only when the fork was ghostcut/subtitle-removed; otherwise `sources.json` marks them `same_as_decomposed: true` and only `source.mp4` is written.
+- **`frames/<scene>.png`** — one still per timeline scene, sampled at the scene midpoint from `source.mp4`. Open these as images to analyze what each scene shows. Requires `ffmpeg` (bundled via `ffmpeg-static`); if unavailable the videos still download and frames are skipped.
+- **`sources.json`** — the manifest tying it together: each video's role/url/local path/byte size, the total duration, and per-scene `{ slug, start, duration, label, description, transcript_excerpt, frame }`.
+
+This is best-effort and never blocks the editor session. Re-run with `--refetch` to refresh the media after a new decompose or ghostcut. For deeper text grounding (full transcript, per-scene visual descriptions) read `video-context.json` — the media files complement it with the pixels.
+
 Open the printed URL in your browser. An orange **LOCAL DEV MODE** banner pins to the top with an Exit button. All fork API fetches now route to your local dir instead of the deployed API; disk edits push an SSE reload event and the editor re-fetches automatically.
 
 Flags: `--port`, `--dir`, `--host`, `--fork`, `--api-key` (or set `VIDFARM_API_KEY`), `--share`, `--refetch`. For a fork that already has composition files on disk (or that you've populated manually), use `vidfarm-devcli dev-serve --dir ./my-fork --port 4321` to skip the fetch step.

package/SKILL.platform.md

@@ -184,7 +184,7 @@ The editor is a single monolithic React component (~9k lines). It builds cleanly
 
 Publish flow:
 
-1. Client `POST /api/v1/compositions/:forkId/export` (the route is named `export`; the concept is "publish")
+1. Client `POST /api/v1/compositions/:forkId/export` (the route is named `export`; the editor button and devcli command are both **Render**; treat "render", "publish", and `/export` as the same operation)
 2. API stamps `data-composition-id="<forkId>@v<N>"` into the composition HTML, PUTs the stamped HTML to working, and reads composition.json
 3. API resolves the caller's provider keys (preflight check for required models)
 4. API creates a `job` record and invokes the `hyperframes_render` primitive Lambda
@@ -353,7 +353,7 @@ Legacy but still active:
 - Composition runtime script — `src/composition-runtime.ts`
 - Trackpad Editor — `demo/src/HyperframesStudioEditor.tsx`
 - Editor local-mode bootstrap — `demo/src/dev-mode.ts`
-- Devcli (`vidfarm-devcli`) — `src/cli.ts` (edit-mode fetch + banner), `src/dev-serve.ts` (raw HTTP shim)
+- Devcli (`vidfarm-devcli`) — `src/cli.ts` (edit-mode fetch + banner, the REST-wrapper commands, and the shared `apiRequest()` helper), `src/dev-serve.ts` (raw HTTP shim)
 - Auto-decompose logic — `src/hyperframes/composition.ts` (time-slice), `src/services/hyperframes.ts` (smart)
 - Publish flow — `src/app.ts` `publishCompositionToRenderer()`
 - Ghostcut — `src/services/ghostcut.ts`
@@ -361,7 +361,7 @@ Legacy but still active:
 
 ## Local editor dev loop
 
-`@mevdragon/vidfarm-devcli` (`src/cli.ts` + `src/dev-serve.ts`) pairs a local directory of composition files with the hosted Trackpad Editor so Claude Code, Codex, or a human can edit `composition.html` on disk and see instant preview reload in the browser.
+`@mevdragon/vidfarm-devcli` (`src/cli.ts` + `src/dev-serve.ts`) has two roles. First, it pairs a local directory of composition files with the hosted Trackpad Editor so Claude Code, Codex, or a human can edit `composition.html` on disk and see instant preview reload in the browser (the `edit`/`publish`/`dev-serve` commands, detailed below). Second, it wraps the **entire director REST flow** as 1:1 CLI commands — `discover`, `inspiration-add`, `fork`, `decompose`, `snapshot`, `render` (→ `/export`), `approve`, `schedule`, `posts`/`schedules`, `upload`/`download`, `login`/`whoami`/`provider-keys`, plus a raw `api <METHOD> <path>` passthrough. Every wrapper routes through a single `apiRequest()` helper (auth + host + JSON), so it never duplicates route logic; the command↔route table and the raw-REST-vs-devcli guidance live in `SKILL.director.md`. Each command prints its prod frontend URL (editor / discover / approved-post `share_url`) as a first-class output, and `--json` gives pure JSON for agents.
 
 ```bash
 # One-shot: fetch composition, start dev-serve, print editor URL.

package/dist/src/cli.js

@@ -1,41 +1,98 @@
 #!/usr/bin/env node
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
+import { spawnSync } from "node:child_process";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 // vidfarm-devcli — thin CLI that pairs a local composition directory with the
 // hosted Trackpad Editor at https://vidfarm.cc/editor/. Point it at a template
 // id, and it: resolves the user's fork, downloads the current composition,
 // starts a local dev-serve, and prints the editor URL to open in the browser.
 const DEFAULT_HOST = "https://vidfarm.cc";
 const DEFAULT_PORT = 4321;
-const HELP = `vidfarm-devcli — local editor bridge for the Vidfarm Trackpad Editor
+// Every command below is a thin wrapper over ONE Vidfarm REST call (the `→`
+// line documents the exact route). The devcli adds nothing the raw API can't
+// do — it just resolves your fork, sets the `vidfarm-api-key` header, prints
+// the prod frontend URL to open, and handles the multi-step upload/download +
+// render-polling flows that are awkward to do by hand. Prefer the raw REST API
+// (or `vidfarm api <METHOD> <path>`) whenever you want full control; reach for
+// the named commands when you want the ergonomics and the frontend links.
+const HELP = `vidfarm-devcli — command-line bridge for the Vidfarm video studio
+
+Every named command maps 1:1 to a single REST route (shown as → below). Use
+raw REST (or \`vidfarm api\`) when you want control; use named commands for the
+ergonomics + prod frontend links. Auth: --api-key <key> or VIDFARM_API_KEY.
 
 Usage:
-  vidfarm-devcli <template_id> [options]        Start local editor session
-  vidfarm-devcli publish <template_id> [opts]   Push local composition to your fork
-  vidfarm-devcli dev-serve [options]            Serve an existing local dir only
-  vidfarm-devcli --help                         Show this help
+  vidfarm <template_id> [opts]              Start local editor session (default)
+  vidfarm <command> [args] [opts]
+  vidfarm --help
 
-Options (edit mode):
-  --port <n>          Local dev-serve port (default: ${DEFAULT_PORT})
-  --dir <path>        Local composition directory (default: .vidfarm/<template_id>)
-  --host <url>        Vidfarm host to fetch from (default: ${DEFAULT_HOST})
-  --fork <id>         Fork id to fetch (default: auto-resolve for the current user)
+Local editor loop:
+  <template_id> [opts]      Fetch composition + media, dev-serve, print editor URL
+  publish [template_id]     Push local composition.html/json to your fork  → PUT/PATCH composition + POST versions
+  dev-serve                 Serve an existing local dir only (no fetch)
+
+Discover & inspiration (browse the viral-video catalog, add your own source):
+  discover                  List the template/inspiration feed          → GET  /discover/feed
+  inspiration-add <url>     Ingest a TikTok/YT/IG/X video as a template  → POST /discover/templates
+  inspiration-rm <id>       Delete a private inspiration/template you own → DELETE /discover/templates/:id
+  inspiration-decompose <id>  AI-decompose an inspiration into scenes     → POST /api/v1/inspirations/:id/decompose
+
+Composition lifecycle (fork → decompose → snapshot → render):
+  fork <template_id>        Fork a template into an editable composition → POST /api/v1/compositions
+  decompose <forkId>        Split the fork's source into scenes (smart)  → POST .../compositions/:forkId/auto-decompose
+  ghostcut <forkId>         Read subtitle-removal status (non-billing)   → GET  .../compositions/:forkId/ghostcut
+  versions <forkId>         List immutable version snapshots             → GET  .../compositions/:forkId/versions
+  snapshot <forkId>         Save the working state as a new version      → POST .../compositions/:forkId/versions
+  render <forkId>           Render the fork to MP4 (--wait to poll)      → POST .../compositions/:forkId/export
+  render-status <forkId> <renderId>   Poll one render job               → GET  .../compositions/:forkId/renders/:renderId
+  visibility <forkId> <private|public>   Set fork visibility            → PATCH .../compositions/:forkId/visibility
+  clone <forkId>            Clone a fork as a new starting point         → POST .../compositions/:forkId/clone
+  share-link <forkId>       Mint a share-token URL for a fork            → POST .../compositions/:forkId/share-links
+
+Approve & schedule (publish a finished MP4 as a shareable post):
+  approve                   Approve media into a preview/share page      → POST /api/v1/approved/posts
+  posts                     List your approved posts                     → GET  /api/v1/approved/posts
+  post <postId>             Read one approved post (prints share URL)    → GET  /api/v1/approved/posts/:postId
+  schedule <postId>         Schedule an approved post to a channel       → POST /api/v1/approved/posts/:postId/schedules
+  schedules <postId>        Browse an approved post's schedules          → GET  /api/v1/approved/posts/:postId/schedules
+
+Account:
+  login <email>             Send an OTP code to email                    → POST /api/v1/user/request-otp
+  verify <email> <code>     Verify the OTP, print a fresh API key        → POST /api/v1/user/verify-otp
+  whoami                    Show the authenticated account               → GET  /api/v1/user/me
+  provider-keys             List saved AI provider keys                  → GET  /api/v1/user/me/provider-keys
+  add-provider-key <provider> <secret>   Save an AI provider key         → POST /api/v1/user/me/provider-keys
+
+Files (multi-step flows the devcli handles for you):
+  upload <file>             Upload a local file, print its durable URL   → POST /api/v1/user/me/temporary-files/upload
+  download <url> [dest]     Stream any Vidfarm/media URL to disk
+
+Escape hatch — call ANY route directly:
+  api <METHOD> <path>       Raw REST call with auth + pretty errors
+    --data <json>           JSON request body (or --data-file <path>)
+    --query k=v             Repeatable query param
+  Examples:
+    vidfarm api GET /discover/feed
+    vidfarm api POST /api/v1/compositions --data '{"template_id":"template_..."}'
+
+Common options (any command):
+  --host <url>        Vidfarm host (default: ${DEFAULT_HOST})
   --api-key <key>     Vidfarm API key (or set VIDFARM_API_KEY)
   --share <token>     Share token for a shared fork (public read)
-  --refetch           Overwrite local composition files with the latest remote copy
+  --json              Print only the raw JSON response (agent-friendly)
 
-Options (publish mode):
+Editor-mode options:
+  --port <n>          Local dev-serve port (default: ${DEFAULT_PORT})
   --dir <path>        Local composition directory (default: .vidfarm/<template_id>)
-  --host <url>        Vidfarm host to publish to (default: ${DEFAULT_HOST})
-  --fork <id>         Fork id to publish into (default: auto-resolve for the current user)
-  --api-key <key>     Vidfarm API key (or set VIDFARM_API_KEY) — required to write
-  --message <text>    Optional message attached to the published version snapshot
-  --no-snapshot       Only update the working copy; skip the version snapshot
+  --fork <id>         Fork id (default: auto-resolve for the current user)
+  --refetch           Overwrite local composition files with the latest remote copy
 
-Options (dev-serve mode):
-  --dir <path>        Directory to serve (default: current dir)
-  --port <n>          Port to listen on (default: ${DEFAULT_PORT})
+Publish-mode options:
+  --message <text>    Message attached to the published version snapshot
+  --no-snapshot       Only update the working copy; skip the version snapshot
 `;
 void main().catch((error) => {
     console.error(error instanceof Error ? error.stack ?? error.message : String(error));
@@ -48,25 +105,218 @@ async function main() {
         return;
     }
     const command = argv[0];
-    if (command === "dev-serve") {
-        const { runDevServeCommand } = await import("./dev-serve.js");
-        await runDevServeCommand(argv.slice(1));
-        return;
+    const rest = argv.slice(1);
+    switch (command) {
+        case "dev-serve": {
+            const { runDevServeCommand } = await import("./dev-serve.js");
+            await runDevServeCommand(rest);
+            return;
+        }
+        case "edit":
+            await runEditCommand(rest);
+            return;
+        case "publish":
+            await runPublishCommand(rest);
+            return;
+        // Raw escape hatch + all the 1:1 REST wrappers.
+        case "api":
+            await runApiCommand(rest);
+            return;
+        case "discover":
+            await runDiscoverCommand(rest);
+            return;
+        case "inspiration-add":
+            await runInspirationAddCommand(rest);
+            return;
+        case "inspiration-rm":
+            await runInspirationRemoveCommand(rest);
+            return;
+        case "inspiration-decompose":
+            await runInspirationDecomposeCommand(rest);
+            return;
+        case "fork":
+            await runForkCommand(rest);
+            return;
+        case "decompose":
+            await runDecomposeCommand(rest);
+            return;
+        case "ghostcut":
+            await runGhostcutCommand(rest);
+            return;
+        case "versions":
+            await runVersionsCommand(rest);
+            return;
+        case "snapshot":
+            await runSnapshotCommand(rest);
+            return;
+        case "render":
+            await runRenderCommand(rest);
+            return;
+        case "render-status":
+            await runRenderStatusCommand(rest);
+            return;
+        case "visibility":
+            await runVisibilityCommand(rest);
+            return;
+        case "clone":
+            await runCloneCommand(rest);
+            return;
+        case "share-link":
+            await runShareLinkCommand(rest);
+            return;
+        case "approve":
+            await runApproveCommand(rest);
+            return;
+        case "posts":
+            await runPostsCommand(rest);
+            return;
+        case "post":
+            await runPostCommand(rest);
+            return;
+        case "schedule":
+            await runScheduleCommand(rest);
+            return;
+        case "schedules":
+            await runSchedulesCommand(rest);
+            return;
+        case "login":
+            await runLoginCommand(rest);
+            return;
+        case "verify":
+            await runVerifyCommand(rest);
+            return;
+        case "whoami":
+            await runWhoamiCommand(rest);
+            return;
+        case "provider-keys":
+            await runProviderKeysCommand(rest);
+            return;
+        case "add-provider-key":
+            await runAddProviderKeyCommand(rest);
+            return;
+        case "upload":
+            await runUploadCommand(rest);
+            return;
+        case "download":
+            await runDownloadCommand(rest);
+            return;
+        default:
+            if (!command.startsWith("-")) {
+                // Positional template id → default `edit` command.
+                await runEditCommand(argv);
+                return;
+            }
+            throw new Error(`Unknown option before command: ${command}\n\n${HELP}`);
     }
-    if (command === "edit") {
-        await runEditCommand(argv.slice(1));
-        return;
+}
+// ── REST plumbing shared by every wrapper command ───────────────────────────
+// One code path for auth + host + query + JSON. This is what makes the devcli a
+// thin shell over the REST API rather than a second implementation: the named
+// commands below just assemble a method/path/body and hand it here.
+const FRONTEND = "\x1b[1m\x1b[36m"; // bold cyan — reserved for openable URLs
+const BOLD = "\x1b[1m";
+const DIM = "\x1b[2m";
+const GREEN = "\x1b[32m";
+const RED = "\x1b[31m";
+const RESET = "\x1b[0m";
+async function apiRequest(input) {
+    const url = new URL(input.path, input.host);
+    for (const [key, value] of Object.entries(input.query ?? {})) {
+        if (value !== undefined && value !== null && value !== "")
+            url.searchParams.set(key, value);
     }
-    if (command === "publish") {
-        await runPublishCommand(argv.slice(1));
-        return;
+    const headers = { ...buildAuthHeaders(input.auth), accept: "application/json" };
+    let body;
+    if (input.body !== undefined) {
+        headers["content-type"] = "application/json";
+        body = JSON.stringify(input.body);
     }
-    if (!command.startsWith("-")) {
-        // Positional template id → default `edit` command.
-        await runEditCommand(argv);
+    const res = await fetch(url, { method: input.method.toUpperCase(), headers, body });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    return { status: res.status, ok: res.ok, json, text };
+}
+// Named commands should fail loudly (unlike the read-tolerant edit fetch).
+function assertApiOk(result, action) {
+    if (result.ok)
+        return;
+    const detail = result.json && typeof result.json === "object" && typeof result.json.error === "string"
+        ? ` — ${result.json.error}`
+        : result.text
+            ? ` — ${result.text.slice(0, 300)}`
+            : "";
+    const hint = result.status === 401 || result.status === 403
+        ? " Check --api-key / VIDFARM_API_KEY and that you own this resource."
+        : result.status === 402
+            ? " The account is not on a paid plan (or the wallet is empty)."
+            : result.status === 429
+                ? " Rate-limited; wait and retry."
+                : "";
+    throw new Error(`${action} failed: ${result.status}${detail}.${hint}`);
+}
+// Resolve host + auth + output mode shared by every wrapper command. Adding
+// these to a parseArgs `options` block keeps the flags consistent everywhere.
+function commonOptions() {
+    return {
+        host: { type: "string", default: DEFAULT_HOST },
+        "api-key": { type: "string" },
+        share: { type: "string" },
+        json: { type: "boolean", default: false }
+    };
+}
+function commonContext(values) {
+    return {
+        host: trimTrailingSlash(String(values.host ?? DEFAULT_HOST)),
+        auth: {
+            apiKey: values["api-key"] ?? process.env.VIDFARM_API_KEY,
+            shareToken: values.share
+        },
+        json: Boolean(values.json)
+    };
+}
+function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+// Print the JSON result and, when not in --json mode, a highlighted list of the
+// prod frontend URLs a human can open. Frontend links are a first-class output.
+function emitResult(result, json, frontend) {
+    if (json) {
+        printJson(result.json ?? result.text);
         return;
     }
-    throw new Error(`Unknown option before command: ${command}\n\n${HELP}`);
+    printJson(result.json ?? result.text);
+    const links = (frontend ?? []).filter((entry) => Boolean(entry[1]));
+    if (links.length > 0) {
+        console.log("");
+        for (const [label, url] of links) {
+            console.log(`  ${BOLD}${label}${RESET}  ${FRONTEND}${url}${RESET}`);
+        }
+    }
+}
+// Frontend URL builders — these are the pages a director opens in a browser.
+function editorFrontendUrl(host, templateId, forkId) {
+    const base = `${host}/editor/${encodeURIComponent(templateId)}`;
+    return forkId ? `${base}?fork=${encodeURIComponent(forkId)}` : base;
+}
+function discoverFrontendUrl(host) {
+    return `${host}/discover`;
+}
+// Small arg helper: split "k=v" pairs for --query.
+function collectKeyValues(entries) {
+    const out = {};
+    for (const entry of entries ?? []) {
+        const eq = entry.indexOf("=");
+        if (eq === -1)
+            throw new Error(`--query expects k=v, got: ${entry}`);
+        out[entry.slice(0, eq)] = entry.slice(eq + 1);
+    }
+    return out;
 }
 async function runEditCommand(argv) {
     const parsed = parseArgs({
@@ -107,6 +357,17 @@ async function runEditCommand(argv) {
         shareToken,
         refetch: parsed.values.refetch
     });
+    // Give local coding agents (Claude Code / Codex / opencode) the actual media
+    // to look at: the original source video, the composition's decomposed source
+    // (which may differ after ghostcut subtitle-removal), one still frame per
+    // scene, and a sources.json manifest tying it all together. Best-effort —
+    // never blocks the editor session if a download or frame extraction fails.
+    try {
+        await fetchVideoAssets({ dir: rootDir, apiKey, shareToken, refetch: parsed.values.refetch });
+    }
+    catch (error) {
+        console.warn(`[vidfarm] video assets skipped: ${error instanceof Error ? error.message : String(error)}`);
+    }
     const devSource = `http://localhost:${port}`;
     const editorUrl = `${host}/editor/${encodeURIComponent(templateId)}?fork=${encodeURIComponent(forkId)}&dev=${encodeURIComponent(devSource)}`;
     printEditorBanner({ templateId, forkId, dir: rootDir, port, editorUrl });
@@ -302,6 +563,232 @@ async function fetchCompositionFiles(input) {
         console.log(`[vidfarm] fetched ${filename} (${body.length} bytes)`);
     }
 }
+async function fetchVideoAssets(input) {
+    const refs = readSourceRefs(input.dir);
+    if (!refs.compositionSourceUrl && !refs.originalSourceUrl) {
+        console.log("[vidfarm] no source video URL found in composition — skipping video assets");
+        return;
+    }
+    // "decomposed video in composition" = the source the composition currently
+    // renders from (post-ghostcut if applicable). "original" = the raw source the
+    // decompose ran against, before any processing. They coincide when the fork
+    // was never ghostcut/subtitle-removed.
+    const compositionUrl = refs.compositionSourceUrl ?? refs.originalSourceUrl;
+    const originalUrl = refs.originalSourceUrl ?? refs.compositionSourceUrl;
+    const sameSource = compositionUrl === originalUrl;
+    const headers = buildAuthHeaders(input);
+    const decomposedName = "source.mp4";
+    const originalName = "original.mp4";
+    const decomposed = await downloadVideo({
+        url: compositionUrl,
+        target: path.join(input.dir, decomposedName),
+        headers,
+        refetch: input.refetch,
+        label: "decomposed source"
+    });
+    let original = decomposed && sameSource ? { ...decomposed, path: decomposedName } : null;
+    if (!sameSource) {
+        original = await downloadVideo({
+            url: originalUrl,
+            target: path.join(input.dir, originalName),
+            headers,
+            refetch: input.refetch,
+            label: "original source"
+        });
+    }
+    // One representative still per scene, taken from the decomposed source (what
+    // the composition actually renders). Falls back to the original if that's the
+    // only video that came down.
+    const frameBase = decomposed ? decomposedName : original ? originalName : null;
+    const frames = frameBase
+        ? await extractSceneFrames({
+            dir: input.dir,
+            videoName: frameBase,
+            scenes: refs.scenes,
+            durationSeconds: refs.durationSeconds,
+            refetch: input.refetch
+        })
+        : new Map();
+    const manifest = {
+        generated_by: "vidfarm-devcli",
+        note: "Local media references for coding agents. `original.mp4` is the raw source video; " +
+            "`source.mp4` is the video the composition timeline renders from (may differ from the " +
+            "original after ghostcut subtitle-removal). Scene entries map timeline segments to a still " +
+            "frame you can open as an image. Run `--refetch` to refresh.",
+        videos: {
+            decomposed: {
+                role: "video the composition timeline renders from (decomposed source)",
+                url: compositionUrl,
+                path: decomposed ? decomposedName : null,
+                bytes: decomposed?.bytes ?? null
+            },
+            original: {
+                role: "raw original source video (before any processing)",
+                url: originalUrl,
+                path: original ? original.path : null,
+                bytes: original?.bytes ?? null,
+                same_as_decomposed: sameSource
+            }
+        },
+        duration_seconds: refs.durationSeconds,
+        scenes: refs.scenes.map((scene, index) => ({
+            slug: scene.slug,
+            start: scene.start,
+            duration: scene.duration,
+            label: scene.label,
+            description: scene.description,
+            transcript_excerpt: scene.transcript_excerpt,
+            frame: frames.get(index) ?? null,
+            frame_source: frameBase
+        }))
+    };
+    writeFileSync(path.join(input.dir, "sources.json"), JSON.stringify(manifest, null, 2));
+    console.log(`[vidfarm] wrote sources.json (${refs.scenes.length} scenes, ${frames.size} frames)`);
+}
+// Derive the source URLs and scene list from the files already on disk
+// (composition.html + video-context.json) — no extra network round-trips.
+function readSourceRefs(dir) {
+    let compositionSourceUrl = null;
+    const htmlPath = path.join(dir, "composition.html");
+    if (existsSync(htmlPath)) {
+        const html = readFileSync(htmlPath, "utf8");
+        compositionSourceUrl =
+            matchAttr(html, "data-source-video") ??
+                matchPlaybackSourceSrc(html) ??
+                null;
+    }
+    let originalSourceUrl = null;
+    let scenes = [];
+    let durationSeconds = null;
+    const ctxPath = path.join(dir, "video-context.json");
+    if (existsSync(ctxPath)) {
+        try {
+            const ctx = JSON.parse(readFileSync(ctxPath, "utf8"));
+            if (typeof ctx.source_url === "string" && ctx.source_url)
+                originalSourceUrl = ctx.source_url;
+            if (typeof ctx.duration_seconds === "number")
+                durationSeconds = ctx.duration_seconds;
+            if (Array.isArray(ctx.scenes)) {
+                scenes = ctx.scenes
+                    .map((raw) => {
+                    if (!raw || typeof raw !== "object")
+                        return null;
+                    const s = raw;
+                    return {
+                        slug: typeof s.slug === "string" ? s.slug : null,
+                        start: Number(s.start ?? 0),
+                        duration: Number(s.duration ?? 0),
+                        label: typeof s.label === "string" ? s.label : null,
+                        description: typeof s.description === "string" ? s.description : "",
+                        transcript_excerpt: typeof s.transcript_excerpt === "string" ? s.transcript_excerpt : ""
+                    };
+                })
+                    .filter((s) => s !== null);
+            }
+        }
+        catch {
+            // video-context.json absent/status:none/malformed → fall back to composition source only
+        }
+    }
+    return { compositionSourceUrl, originalSourceUrl, scenes, durationSeconds };
+}
+function matchAttr(html, attr) {
+    const match = html.match(new RegExp(`${attr}="([^"]+)"`));
+    return match ? decodeHtmlEntities(match[1]) : null;
+}
+function matchPlaybackSourceSrc(html) {
+    const match = html.match(/data-vf-playback-source="true"[^>]*\ssrc="([^"]+)"/) ??
+        html.match(/<video[^>]*\ssrc="([^"]+)"/);
+    return match ? decodeHtmlEntities(match[1]) : null;
+}
+function decodeHtmlEntities(value) {
+    return value
+        .replace(/&amp;/g, "&")
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">");
+}
+async function downloadVideo(input) {
+    const name = path.basename(input.target);
+    if (existsSync(input.target) && !input.refetch) {
+        console.log(`[vidfarm] keep local ${name} (use --refetch to overwrite)`);
+        return { path: name, bytes: safeSize(input.target) };
+    }
+    try {
+        const res = await fetch(input.url, { headers: input.headers });
+        if (!res.ok || !res.body) {
+            console.warn(`[vidfarm] skip ${name} (${input.label}): ${res.status} ${res.statusText}`);
+            return null;
+        }
+        await pipeline(Readable.fromWeb(res.body), createWriteStream(input.target));
+        const bytes = safeSize(input.target);
+        console.log(`[vidfarm] fetched ${name} (${input.label}, ${formatBytes(bytes)})`);
+        return { path: name, bytes };
+    }
+    catch (error) {
+        console.warn(`[vidfarm] skip ${name} (${input.label}): ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+async function extractSceneFrames(input) {
+    const out = new Map();
+    if (input.scenes.length === 0)
+        return out;
+    const ffmpeg = await resolveFfmpegPath();
+    if (!ffmpeg) {
+        console.log("[vidfarm] ffmpeg unavailable — skipping scene frames (videos still downloaded)");
+        return out;
+    }
+    const framesDir = path.join(input.dir, "frames");
+    mkdirSync(framesDir, { recursive: true });
+    const videoPath = path.join(input.dir, input.videoName);
+    input.scenes.forEach((scene, index) => {
+        const slug = scene.slug || `scene-${index + 1}`;
+        const rel = path.join("frames", `${slug}.png`);
+        const target = path.join(input.dir, rel);
+        if (existsSync(target) && !input.refetch) {
+            out.set(index, rel);
+            return;
+        }
+        // Sample the scene midpoint, clamped inside the clip.
+        const mid = scene.start + Math.max(0, scene.duration) / 2;
+        const seek = Number.isFinite(mid) && mid > 0 ? mid : Math.max(0, scene.start);
+        const result = spawnSync(ffmpeg, ["-y", "-ss", seek.toFixed(3), "-i", videoPath, "-frames:v", "1", "-q:v", "3", target], { stdio: "ignore" });
+        if (result.status === 0 && existsSync(target)) {
+            out.set(index, rel);
+        }
+    });
+    console.log(`[vidfarm] extracted ${out.size}/${input.scenes.length} scene frames from ${input.videoName}`);
+    return out;
+}
+async function resolveFfmpegPath() {
+    // ffmpeg-static is already a dependency; import lazily so the common path
+    // (no frame extraction) never pays for it, and degrade gracefully if absent.
+    try {
+        const mod = (await import("ffmpeg-static"));
+        const resolved = typeof mod === "string" ? mod : mod.default;
+        return typeof resolved === "string" && resolved.length > 0 && existsSync(resolved) ? resolved : null;
+    }
+    catch {
+        return null;
+    }
+}
+function safeSize(target) {
+    try {
+        return statSync(target).size;
+    }
+    catch {
+        return 0;
+    }
+}
+function formatBytes(bytes) {
+    if (bytes >= 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    if (bytes >= 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${bytes} bytes`;
+}
 function buildAuthHeaders(input) {
     const headers = { accept: "text/html,application/json" };
     // The server reads exactly these header names (see requireAuth and
@@ -328,6 +815,8 @@ function printEditorBanner(input) {
     console.log(`  local dir   ${input.dir}`);
     console.log(`  dev-serve   http://localhost:${input.port}`);
     console.log("");
+    console.log(`  ${dim}Agent media: original.mp4, source.mp4, frames/*.png, sources.json${reset}`);
+    console.log("");
     console.log(`  ${bold}Open in browser:${reset}`);
     console.log(`  ${cyan}${input.editorUrl}${reset}`);
     console.log(line);
@@ -336,4 +825,476 @@ function printEditorBanner(input) {
 function trimTrailingSlash(value) {
     return value.replace(/\/+$/, "");
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ── Raw escape hatch: call any REST route ───────────────────────────────────
+async function runApiCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), data: { type: "string" }, "data-file": { type: "string" }, query: { type: "string", multiple: true } }
+    });
+    const method = parsed.positionals[0];
+    const routePath = parsed.positionals[1];
+    if (!method || !routePath) {
+        throw new Error(`api requires <METHOD> <path>.\n\nExample: vidfarm api GET /discover/feed`);
+    }
+    const ctx = commonContext(parsed.values);
+    let body;
+    if (parsed.values["data-file"]) {
+        body = JSON.parse(readFileSync(path.resolve(process.cwd(), String(parsed.values["data-file"])), "utf8"));
+    }
+    else if (parsed.values.data) {
+        body = JSON.parse(String(parsed.values.data));
+    }
+    const result = await apiRequest({
+        method,
+        host: ctx.host,
+        path: routePath,
+        auth: ctx.auth,
+        query: collectKeyValues(parsed.values.query),
+        body
+    });
+    if (!ctx.json) {
+        const color = result.ok ? GREEN : RED;
+        console.log(`${color}${method.toUpperCase()} ${routePath} → ${result.status}${RESET}`);
+    }
+    printJson(result.json ?? result.text);
+    if (!result.ok)
+        process.exitCode = 1;
+}
+// ── Discover & inspiration ──────────────────────────────────────────────────
+async function runDiscoverCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: false, options: { ...commonOptions(), limit: { type: "string" } } });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/discover/feed", auth: ctx.auth, query: { limit: parsed.values.limit } });
+    assertApiOk(result, "discover");
+    emitResult(result, ctx.json, [["Browse ", discoverFrontendUrl(ctx.host)]]);
+}
+async function runInspirationAddCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), tagline: { type: "string" }, notes: { type: "string" } } });
+    const sourceUrl = parsed.positionals[0];
+    if (!sourceUrl)
+        throw new Error("inspiration-add requires a video URL (TikTok/YouTube/Instagram/X).");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/discover/templates",
+        auth: ctx.auth,
+        body: { source_url: sourceUrl, tagline: parsed.values.tagline, notes: parsed.values.notes }
+    });
+    assertApiOk(result, "inspiration-add");
+    emitResult(result, ctx.json, [["Discover ", discoverFrontendUrl(ctx.host)]]);
+}
+async function runInspirationRemoveCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const entryId = parsed.positionals[0];
+    if (!entryId)
+        throw new Error("inspiration-rm requires an inspiration_/template_ id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "DELETE", host: ctx.host, path: `/discover/templates/${encodeURIComponent(entryId)}`, auth: ctx.auth });
+    assertApiOk(result, "inspiration-rm");
+    emitResult(result, ctx.json);
+}
+async function runInspirationDecomposeCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), prompt: { type: "string" } } });
+    const inspirationId = parsed.positionals[0];
+    if (!inspirationId)
+        throw new Error("inspiration-decompose requires an inspiration id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/inspirations/${encodeURIComponent(inspirationId)}/decompose`,
+        auth: ctx.auth,
+        body: { user_prompt: parsed.values.prompt ?? null }
+    });
+    assertApiOk(result, "inspiration-decompose");
+    emitResult(result, ctx.json);
+}
+// ── Composition lifecycle ───────────────────────────────────────────────────
+async function runForkCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), title: { type: "string" } } });
+    const templateId = parsed.positionals[0];
+    if (!templateId)
+        throw new Error("fork requires a template id (template_...).");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/compositions",
+        auth: ctx.auth,
+        body: { template_id: templateId, title: parsed.values.title }
+    });
+    assertApiOk(result, "fork");
+    const forkId = result.json?.fork_id;
+    const tId = result.json?.template_id ?? templateId;
+    emitResult(result, ctx.json, [["Open editor ", forkId ? editorFrontendUrl(ctx.host, tId, forkId) : null]]);
+}
+async function runDecomposeCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), mode: { type: "string", default: "smart" }, prompt: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("decompose requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/auto-decompose`,
+        auth: ctx.auth,
+        body: { mode: parsed.values.mode, user_prompt: parsed.values.prompt ?? null }
+    });
+    assertApiOk(result, "decompose");
+    if (!ctx.json && result.json?.ghostcut_pending) {
+        console.log(`${DIM}GhostCut subtitle-removal is running in the background — poll \`vidfarm api POST /api/v1/compositions/${forkId}/ghostcut-poll\` or GET .../ghostcut until done.${RESET}`);
+    }
+    emitResult(result, ctx.json);
+}
+async function runGhostcutCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("ghostcut requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/ghostcut`, auth: ctx.auth });
+    assertApiOk(result, "ghostcut");
+    emitResult(result, ctx.json);
+}
+async function runVersionsCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), limit: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("versions requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/versions`, auth: ctx.auth, query: { limit: parsed.values.limit } });
+    assertApiOk(result, "versions");
+    emitResult(result, ctx.json);
+}
+async function runSnapshotCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), message: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("snapshot requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "POST", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/versions`, auth: ctx.auth, body: { message: parsed.values.message ?? null } });
+    assertApiOk(result, "snapshot");
+    emitResult(result, ctx.json);
+}
+async function runRenderCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), title: { type: "string" }, tracer: { type: "string" }, wait: { type: "boolean", default: false } }
+    });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("render requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/export`,
+        auth: ctx.auth,
+        body: { title: parsed.values.title, tracer: parsed.values.tracer }
+    });
+    assertApiOk(result, "render");
+    const renderId = result.json?.renderId;
+    if (!parsed.values.wait || !renderId) {
+        if (!ctx.json && renderId) {
+            console.log(`${DIM}Poll with: vidfarm render-status ${forkId} ${renderId} (or add --wait next time).${RESET}`);
+        }
+        emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.outputUrl]]);
+        return;
+    }
+    // --wait: poll the render job until it settles.
+    if (!ctx.json)
+        console.log(`${DIM}Rendering ${renderId}… polling every 5s.${RESET}`);
+    let last = result;
+    for (;;) {
+        await sleep(5000);
+        last = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/renders/${encodeURIComponent(renderId)}`, auth: ctx.auth });
+        assertApiOk(last, "render-status");
+        const status = String(last.json?.status ?? "");
+        if (!ctx.json) {
+            const pct = Math.round((Number(last.json?.progress ?? 0)) * 100);
+            console.log(`${DIM}  ${status} ${pct}%${RESET}`);
+        }
+        if (status === "SUCCEEDED" || status === "FAILED")
+            break;
+    }
+    emitResult(last, ctx.json, [["Rendered MP4 ", last.json?.outputUrl]]);
+    if (String(last.json?.status) === "FAILED")
+        process.exitCode = 1;
+}
+async function runRenderStatusCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const forkId = parsed.positionals[0];
+    const renderId = parsed.positionals[1];
+    if (!forkId || !renderId)
+        throw new Error("render-status requires <forkId> <renderId>.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/renders/${encodeURIComponent(renderId)}`, auth: ctx.auth });
+    assertApiOk(result, "render-status");
+    emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.outputUrl]]);
+}
+async function runVisibilityCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const forkId = parsed.positionals[0];
+    const visibility = parsed.positionals[1];
+    if (!forkId || !visibility)
+        throw new Error("visibility requires <forkId> <private|public>.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "PATCH", host: ctx.host, path: `/api/v1/compositions/${encodeURIComponent(forkId)}/visibility`, auth: ctx.auth, body: { visibility } });
+    assertApiOk(result, "visibility");
+    const templateId = result.json?.template_id;
+    emitResult(result, ctx.json, templateId ? [["Open editor ", editorFrontendUrl(ctx.host, templateId, forkId)]] : undefined);
+}
+async function runCloneCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), version: { type: "string" }, title: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("clone requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/clone`,
+        auth: ctx.auth,
+        body: { parent_version: parsed.values.version, title: parsed.values.title }
+    });
+    assertApiOk(result, "clone");
+    const newForkId = result.json?.fork_id;
+    const templateId = result.json?.template_id;
+    emitResult(result, ctx.json, newForkId && templateId ? [["Open editor ", editorFrontendUrl(ctx.host, templateId, newForkId)]] : undefined);
+}
+async function runShareLinkCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), role: { type: "string", default: "viewer" }, expires: { type: "string" } } });
+    const forkId = parsed.positionals[0];
+    if (!forkId)
+        throw new Error("share-link requires a fork id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/compositions/${encodeURIComponent(forkId)}/share-links`,
+        auth: ctx.auth,
+        body: { role: parsed.values.role, expires_at: parsed.values.expires ?? null }
+    });
+    assertApiOk(result, "share-link");
+    emitResult(result, ctx.json, [["Share ", result.json?.share_url]]);
+}
+// ── Approve & schedule ──────────────────────────────────────────────────────
+async function runApproveCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: false,
+        options: {
+            ...commonOptions(),
+            video: { type: "string" },
+            media: { type: "string", multiple: true },
+            caption: { type: "string" },
+            title: { type: "string" },
+            pinned: { type: "string" },
+            tracer: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const caption = parsed.values.caption;
+    if (!caption)
+        throw new Error("approve requires --caption <text>.");
+    const media = [];
+    if (parsed.values.video)
+        media.push({ url: parsed.values.video, kind: "video", role: "primary" });
+    for (const url of parsed.values.media ?? [])
+        media.push({ url });
+    if (media.length === 0) {
+        console.warn(`${DIM}[vidfarm] no --video / --media given; approving a text-only post.${RESET}`);
+    }
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/approved/posts",
+        auth: ctx.auth,
+        body: {
+            caption,
+            title: parsed.values.title,
+            pinned_comment: parsed.values.pinned,
+            tracer: parsed.values.tracer,
+            media
+        }
+    });
+    assertApiOk(result, "approve");
+    // The approved-post preview page is the headline output: it's the prod
+    // frontend URL a human opens to see/share the finished post.
+    emitResult(result, ctx.json, [["Preview post ", result.json?.post?.share_url]]);
+}
+async function runPostsCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: false, options: { ...commonOptions(), limit: { type: "string" }, tracer: { type: "string" } } });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/approved/posts", auth: ctx.auth, query: { limit: parsed.values.limit, tracer: parsed.values.tracer } });
+    assertApiOk(result, "posts");
+    emitResult(result, ctx.json);
+}
+async function runPostCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const postId = parsed.positionals[0];
+    if (!postId)
+        throw new Error("post requires a post id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/approved/posts/${encodeURIComponent(postId)}`, auth: ctx.auth });
+    assertApiOk(result, "post");
+    emitResult(result, ctx.json, [["Preview post ", result.json?.post?.share_url]]);
+}
+async function runScheduleCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), at: { type: "string" }, to: { type: "string" }, type: { type: "string", default: "flockposter" }, timezone: { type: "string" }, notes: { type: "string" } }
+    });
+    const postId = parsed.positionals[0];
+    if (!postId)
+        throw new Error("schedule requires a post id.");
+    if (!parsed.values.at)
+        throw new Error("schedule requires --at <ISO 8601 timestamp>.");
+    if (!parsed.values.to)
+        throw new Error("schedule requires --to <destination_id> (a FlockPoster channel or email).");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: `/api/v1/approved/posts/${encodeURIComponent(postId)}/schedules`,
+        auth: ctx.auth,
+        body: {
+            destination_type: parsed.values.type,
+            destination_id: parsed.values.to,
+            scheduled_at: parsed.values.at,
+            timezone: parsed.values.timezone,
+            additional_notes: parsed.values.notes
+        }
+    });
+    assertApiOk(result, "schedule");
+    emitResult(result, ctx.json);
+}
+async function runSchedulesCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const postId = parsed.positionals[0];
+    if (!postId)
+        throw new Error("schedules requires a post id.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: `/api/v1/approved/posts/${encodeURIComponent(postId)}/schedules`, auth: ctx.auth });
+    assertApiOk(result, "schedules");
+    emitResult(result, ctx.json);
+}
+// ── Account ─────────────────────────────────────────────────────────────────
+async function runLoginCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const email = parsed.positionals[0];
+    if (!email)
+        throw new Error("login requires an email address.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/user/request-otp", auth: ctx.auth, body: { email } });
+    assertApiOk(result, "login");
+    if (!ctx.json)
+        console.log(`${GREEN}OTP requested for ${email}. Run: vidfarm verify ${email} <code>${RESET}`);
+    emitResult(result, ctx.json);
+}
+async function runVerifyCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), name: { type: "string" } } });
+    const email = parsed.positionals[0];
+    const code = parsed.positionals[1];
+    if (!email || !code)
+        throw new Error("verify requires <email> <code>.");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/user/verify-otp", auth: ctx.auth, body: { email, code, name: parsed.values.name } });
+    assertApiOk(result, "verify");
+    const apiKey = result.json?.apiKey;
+    if (!ctx.json && apiKey) {
+        console.log(`${GREEN}${BOLD}Save this API key:${RESET} ${apiKey}`);
+        console.log(`${DIM}export VIDFARM_API_KEY=${apiKey}${RESET}`);
+    }
+    emitResult(result, ctx.json);
+}
+async function runWhoamiCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: false, options: commonOptions() });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me", auth: ctx.auth });
+    assertApiOk(result, "whoami");
+    emitResult(result, ctx.json);
+}
+async function runProviderKeysCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: false, options: commonOptions() });
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "GET", host: ctx.host, path: "/api/v1/user/me/provider-keys", auth: ctx.auth });
+    assertApiOk(result, "provider-keys");
+    emitResult(result, ctx.json);
+}
+async function runAddProviderKeyCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), label: { type: "string" } } });
+    const provider = parsed.positionals[0];
+    const secret = parsed.positionals[1];
+    if (!provider || !secret)
+        throw new Error("add-provider-key requires <provider> <secret> (provider: openai|gemini|openrouter|perplexity).");
+    const ctx = commonContext(parsed.values);
+    const result = await apiRequest({ method: "POST", host: ctx.host, path: "/api/v1/user/me/provider-keys", auth: ctx.auth, body: { provider, secret, label: parsed.values.label } });
+    assertApiOk(result, "add-provider-key");
+    emitResult(result, ctx.json);
+}
+// ── Files ───────────────────────────────────────────────────────────────────
+// Upload is a genuine multi-step flow, so the devcli earns its keep here: it
+// posts the file as multipart/form-data to the temporary-files route and prints
+// the durable URL you can drop into a composition or an approved post.
+async function runUploadCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" } } });
+    const filePath = parsed.positionals[0];
+    if (!filePath)
+        throw new Error("upload requires a local file path.");
+    const ctx = commonContext(parsed.values);
+    const abs = path.resolve(process.cwd(), filePath);
+    if (!existsSync(abs))
+        throw new Error(`No such file: ${abs}`);
+    const buffer = readFileSync(abs);
+    const form = new FormData();
+    form.append("file", new Blob([buffer]), path.basename(abs));
+    if (parsed.values.folder)
+        form.append("folder_path", String(parsed.values.folder));
+    const res = await fetch(new URL("/api/v1/user/me/temporary-files/upload", ctx.host), {
+        method: "POST",
+        headers: buildAuthHeaders(ctx.auth),
+        body: form
+    });
+    const text = await res.text();
+    let json = null;
+    try {
+        json = text ? JSON.parse(text) : null;
+    }
+    catch {
+        json = null;
+    }
+    const result = { status: res.status, ok: res.ok, json, text };
+    assertApiOk(result, "upload");
+    emitResult(result, ctx.json, [["Durable URL ", result.json?.file?.view_url ?? result.json?.file?.s3_url]]);
+}
+async function runDownloadCommand(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
+    const url = parsed.positionals[0];
+    if (!url)
+        throw new Error("download requires a URL.");
+    const ctx = commonContext(parsed.values);
+    const dest = parsed.positionals[1]
+        ? path.resolve(process.cwd(), parsed.positionals[1])
+        : path.resolve(process.cwd(), path.basename(new URL(url).pathname) || "download.bin");
+    const res = await fetch(url, { headers: buildAuthHeaders(ctx.auth) });
+    if (!res.ok || !res.body)
+        throw new Error(`download failed: ${res.status} ${res.statusText} (${url}).`);
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(dest));
+    const bytes = safeSize(dest);
+    if (ctx.json) {
+        printJson({ ok: true, url, path: dest, bytes });
+    }
+    else {
+        console.log(`${GREEN}Downloaded ${formatBytes(bytes)} → ${dest}${RESET}`);
+    }
+}
 //# sourceMappingURL=cli.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Local bridge for the Vidfarm Trackpad Editor. Point it at a template id, edit composition.html on disk (Claude Code, Codex, etc.), preview live in the browser at https://vidfarm.cc/editor/.",
   "type": "module",
   "bin": {