@mevdragon/vidfarm-devcli 0.17.0 → 0.18.1

package/dist/src/cli.js

@@ -12,6 +12,7 @@ import { computeCompositionGaps, insertMediaLayer, inspectComposition, replaceLa
 import { runCaptionsCommand } from "./devcli/captions.js";
 import { runClipsCommand } from "./devcli/clips.js";
 import { runTransitionsCommand } from "./devcli/transitions.js";
+import { runKeyframesCommand, runMoveCommand, runRestackCommand, runRippleCommand, runTrimCommand } from "./devcli/timeline-edit.js";
 import { MAX_LOCAL_TRANSCRIBE_AUDIO_BYTES, loadSpeechAudioLocally, localGenerateSpeech, localTranscribeSpeech, resolveLocalSpeechAuth } from "./devcli/speech.js";
 import { buildSrtFromSegments, inferSpeechProviderForVoice } from "./services/speech.js";
 import { formatCompositionLintIssues, lintCompositionHtml } from "./services/composition-lint.js";
@@ -168,22 +169,22 @@ Generate AI media and drop it on the timeline (for local coding agents):
                             original vs decomposed (caption-free),
                             non-billing (alias: ghostcut)
 
-Clip hunting (the third library — mine long-form video into a reusable clip store):
-  clips scan <video-path>   Hunt short clips out of a long video.        LOCAL-FIRST: local ffmpeg +
+Raws (the third library — mine long-form video into a reusable raws store):
+  raws scan <video-path>    Hunt short clips out of a long video.        LOCAL-FIRST: local ffmpeg +
                             Detect → tag/transcribe → embed → persist    your local claude/codex CLI
                             to ~/.vidfarm/clips.db.                      (keys are fallback)
     --range "MM:SS-MM:SS"     Only hunt these source windows (repeatable; big cost saver)
     --duration <sec>          Target clip length as a SOFT band (10→5-20s, 30→20-40s)
     --aspect 9:16|16:9|4:3|1:1  Crop clips (also: vertical/horizontal/square) [--crop-focus <f>]
     --no-text                 Prefer scenes WITHOUT captions/on-screen text (selection only)
-    --cloud [--url <url>]     BACKUP: run on the deployed pipeline       → POST /clips/scan (+ poll)
+    --cloud [--url <url>]     BACKUP: run on the deployed pipeline       → POST /raws/scan (+ poll)
                               (uploads to your temp folder — 30-day TTL — bills AWS compute only)
     --dry-run                 Show the estimated cost and stop (over $1 needs --yes/confirm)
-  clips list                List the local clip library                  → GET  /clips
-  clips search "<text>"     Hybrid structured + semantic search          → POST /clips/search
-  clips preset list|run <name>|save <name> --from-query '<...>'          → /clips/presets
-  clips export <ids...> --to <dir>   Copy clip mp4s + metadata out
-                            (run 'vidfarm clips' for the full clips help)
+  raws list                 List the local raws library                  → GET  /raws
+  raws search "<text>"      Hybrid structured + semantic search          → POST /raws/search
+  raws preset list|run <name>|save <name> --from-query '<...>'          → /raws/presets
+  raws export <ids...> --to <dir>   Copy raw mp4s + metadata out
+                            (run 'vidfarm raws' for the full raws help)
 
 Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit backup:
   tts "<text>"              Text → narration audio file.                 LOCAL: your OPENAI/GEMINI/
@@ -236,6 +237,20 @@ Scene transitions (between clips on a pulled/served composition — local file w
   transitions list <dir>    Show transitions on every scene clip [--json]
   transitions clear <dir>   Remove all transitions
                             (run 'vidfarm transitions' for presets & all flags)
+
+Fine timeline control (trackpad-level verbs on a pulled/served composition — local file write):
+  keyframes <dir> --layer <key> --preset <name>|--keyframes '<json>'   Script-free CSS
+                            @keyframes animation on ONE layer (opacity/translate/
+                            scale/rotate); previews AND renders. --easing --duration
+  move <dir> --layer <key> [--layer …]   Shift layers by --delta-start (sec) and/or
+                            --delta-track (lanes); group-aware. (alias: nudge)
+  ripple <dir> --at <sec> --delta <sec>   Insert (+) or close (-) time at --at and
+                            shift every downstream clip so the rest stays in sync
+  trim <dir> --layer <key> --edge start|end --to <sec>   Move one edge to a time
+                            (left trim couples the media in-point on video/audio)
+  restack <dir> --layer <key> --order front|back|forward|backward|--track <n>   Change
+                            stacking (== track index; higher = on top). (alias: zindex)
+                            (run 'vidfarm keyframes|move|ripple|trim|restack help' for all flags)
   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/render
@@ -319,10 +334,19 @@ Files (multi-step flows the devcli handles for you):
     --folder <path>         Only files under this folder (e.g. a product/offer)
     --search <query>        Find files by MEANING (keyword + vector over  → POST /api/v1/user/me/attachments/search
                             name/folder/notes) instead of listing everything
+    --content-type <a,b>    With --search: filter the /raws branch by shot-KIND tag
+                            (talking_head,b_roll,product_shot,screen_recording,demo,
+                            reaction,interview,establishing,lifestyle,text_graphic)
   get-file <id> [dest]      Resolve a My Files id to its URL and download it
     --print                 Print text contents (md/txt/csv/json) instead of saving
   annotate-file <id|name>   Set metadata notes on one My Files entry     → PATCH /api/v1/user/me/attachments/:id
     --notes <text>          The notes to attach (empty string clears); embedded for vector search
+  directory ls [path]       Browse the unified file tree (/files·/temp·/raws) → GET /api/v1/user/me/directory
+    --limit <n> --offset <n>  Paginate (folders + files under a path; default "/")
+  directory search <query>  Ranked search across the whole tree           → POST /api/v1/user/me/directory/search
+    --path <scope>          Scope to a subtree · --mode auto|semantic|substring|path · --limit <n>
+    --content-type <a,b>    Filter the /raws branch by shot-KIND tag (talking_head, b_roll, …)
+    (alias: dir)
   put-file / get-file / files / annotate-file are the My Files (persistent) set;
   upload is the throwaway temp store for dropping media into a composition.
   Annotate assets you'll want back — esp. character refs (character_sprite_card.png
@@ -528,6 +552,11 @@ async function main() {
         case "annotate-file":
             await runAnnotateFileCommand(rest);
             return;
+        case "directory":
+        case "dir":
+            await runDirectoryCommand(rest);
+            return;
+        case "raws":
         case "clips":
             await runClipsCommand(rest);
             return;
@@ -537,6 +566,24 @@ async function main() {
         case "transitions":
             await runTransitionsCommand(rest);
             return;
+        // Fine timeline control — local-file twins of the editor's trackpad verbs.
+        case "keyframes":
+            await runKeyframesCommand(rest);
+            return;
+        case "move":
+        case "nudge":
+            await runMoveCommand(rest);
+            return;
+        case "ripple":
+            await runRippleCommand(rest);
+            return;
+        case "trim":
+            await runTrimCommand(rest);
+            return;
+        case "restack":
+        case "zindex":
+            await runRestackCommand(rest);
+            return;
         // Local media engines + toolchain (bundled HyperFrames local commands —
         // free, no account — plus vidfarm-native lint/stills/doctor/skills).
         case "remove-background":
@@ -653,7 +700,7 @@ function emitResult(result, json, frontend) {
 // 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;
+    return forkId ? `${base}/fork/${encodeURIComponent(forkId)}` : base;
 }
 function discoverFrontendUrl(host) {
     return `${host}/discover`;
@@ -722,7 +769,7 @@ async function runServeCommand(argv) {
     // render_target="cloud" upstream handoff (the editor's "Render in Cloud").
     process.env.VIDFARM_JOB_STATE_MACHINE_ARN = "";
     // Same trap for clip hunts: a dev-shell .env carrying the staging clip-scan
-    // ARN would route this box's /clips/scan to the cloud Step Functions. serve
+    // ARN would route this box's /raws/scan to the cloud Step Functions. serve
     // hunts are LOCAL-FIRST (local agent CLI / BYOK keys); the upstream cloud is
     // the explicit backup inside the scan route itself.
     process.env.VIDFARM_CLIP_SCAN_STATE_MACHINE_ARN = "";
@@ -778,7 +825,7 @@ async function runServeCommand(argv) {
     }
     const base = `http://localhost:${port}`;
     const editorPath = openTemplateId
-        ? `/editor/${encodeURIComponent(openTemplateId)}${openForkId ? `?fork=${encodeURIComponent(openForkId)}` : ""}`
+        ? `/editor/${encodeURIComponent(openTemplateId)}${openForkId ? `/fork/${encodeURIComponent(openForkId)}` : ""}`
         : "/discover";
     const openUrl = `${base}/auto-login?api_key=${encodeURIComponent(apiKey)}&redirect=${encodeURIComponent(editorPath)}`;
     printServeBanner({ base, dataDir, openUrl, editorPath, cloud: cloudEnabled ? { host, hasKey: Boolean(cloudApiKey) } : null });
@@ -981,9 +1028,9 @@ function printPublishBanner(input) {
     console.log("");
 }
 async function resolveForkId(input) {
-    // /editor/<template_id> issues a 302 → /editor/<template_id>?fork=<id>
+    // /editor/<template_id> issues a 302 → /editor/<template_id>/fork/<id>
     // whenever the caller (or the template's default fork) has one. Follow the
-    // redirect once by hand so we can read the fork id off the query string.
+    // redirect once by hand so we can read the fork id off the path.
     const url = `${input.host}/editor/${encodeURIComponent(input.templateId)}`;
     const res = await fetch(url, {
         method: "GET",
@@ -995,7 +1042,7 @@ async function resolveForkId(input) {
         if (location) {
             try {
                 const target = new URL(location, input.host);
-                const fork = target.searchParams.get("fork");
+                const fork = parseForkFromEditorPath(target.pathname);
                 if (fork)
                     return fork;
             }
@@ -1006,6 +1053,12 @@ async function resolveForkId(input) {
     }
     return null;
 }
+// Parse the fork id out of a canonical editor path
+// /editor/<template_id>/fork/<fork_id> → "<fork_id>" (else null).
+function parseForkFromEditorPath(pathname) {
+    const match = pathname.match(/^\/editor\/[^/]+\/fork\/([^/]+)\/?$/);
+    return match ? decodeURIComponent(match[1]) : null;
+}
 async function fetchCompositionFiles(input) {
     // video-context.json carries the source video's audio transcript and
     // per-scene visual descriptions so desktop agents (Claude Code, Codex)
@@ -2001,6 +2054,13 @@ async function resolveReferenceUrls(ctx, refs) {
 function inferMediaKindFromUrl(url) {
     return /\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(url) ? "video" : "image";
 }
+// Comma-separated shot-KIND filter (talking_head, b_roll, product_shot, …) →
+// the content_type array the /raws branch of the search endpoints honors.
+function parseContentTypeFlag(value) {
+    if (typeof value !== "string" || !value.trim())
+        return [];
+    return value.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
 // Resolve a composition.html on disk from a file path or a directory holding one.
 function resolveCompositionHtmlPath(target) {
     const abs = path.resolve(process.cwd(), target);
@@ -2256,7 +2316,7 @@ async function runGenerateCommand(argv) {
     }
 }
 // ── Speech: tts / stt ────────────────────────────────────────────────────────
-// LOCAL-FIRST like `clips scan`: both commands default to running on the
+// LOCAL-FIRST like `raws scan`: both commands default to running on the
 // user's OWN AI key (GEMINI_API_KEY / OPENAI_API_KEY / OPENROUTER_API_KEY or
 // the --*-key flags) via src/services/speech.ts — local ffmpeg demux, direct
 // provider call, no cloud job, no wallet. The REST primitive routes
@@ -3213,18 +3273,20 @@ async function runDownloadCommand(argv) {
 // This is the same filesystem the /editor AI agent browses via the browse_files
 // tool, so an agent CLI (Claude Code / Codex) can find assets the same way.
 async function runFilesCommand(argv) {
-    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" }, search: { type: "string" } } });
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), folder: { type: "string" }, search: { type: "string" }, "content-type": { type: "string" } } });
     const ctx = commonContext(parsed.values);
     const folderFilter = parsed.values.folder ? String(parsed.values.folder).replace(/^\/+|\/+$/g, "") : undefined;
+    const contentTypes = parseContentTypeFlag(parsed.values["content-type"]);
     if (parsed.values.search) {
         // Meaning-first lookup: keyword + vector search over every file's
         // name/folder/notes (BYOK embeddings; keyword-only without a saved key).
+        // content_type filters the /raws branch by shot-KIND tag (server-honored).
         const result = await apiRequest({
             method: "POST",
             host: ctx.host,
             path: "/api/v1/user/me/attachments/search",
             auth: ctx.auth,
-            body: { query: String(parsed.values.search), ...(folderFilter ? { folder_path: folderFilter } : {}) }
+            body: { query: String(parsed.values.search), ...(folderFilter ? { folder_path: folderFilter } : {}), ...(contentTypes.length ? { content_type: contentTypes } : {}) }
         });
         assertApiOk(result, "files --search");
         emitResult(result, ctx.json);
@@ -3240,6 +3302,165 @@ async function runFilesCommand(argv) {
     }
     emitResult(result, ctx.json);
 }
+// ── directory (unified virtual file tree) ────────────────────────────────────
+// Browse + search the three file roots (/files, /temp, /raws) as one tree via
+// the cloud REST directory endpoints. Same cloud auth (--api-key/VIDFARM_API_KEY,
+// --host, --json) as the rest of the wrapper commands.
+const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/files · /temp · /raws)
+
+  directory ls [path]              List folders + files under a path (default "/")   → GET /api/v1/user/me/directory
+    --limit <n> --offset <n>       Paginate (server returns next_offset when more)
+    --json                         Raw JSON response
+
+  directory search <query>         Ranked search across the tree                     → POST /api/v1/user/me/directory/search
+    --path <scope>                 Scope the search to a subtree (e.g. /raws/demos)
+    --mode auto|semantic|substring|path   Signal(s) to use (default: auto)
+    --content-type <a,b>           Filter the /raws branch by shot-KIND tag (comma-separated:
+                                   talking_head, b_roll, product_shot, screen_recording, demo,
+                                   reaction, interview, establishing, lifestyle, text_graphic)
+    --limit <n> --json
+
+  Aliases: directory | dir   ·   Auth: --api-key <key> or VIDFARM_API_KEY, --host <url>
+  Move a raw between folders with: vidfarm api PATCH /raws/<clipId> --data '{"folder_path":"…"}'`;
+async function runDirectoryCommand(argv) {
+    const sub = argv[0];
+    const rest = argv.slice(1);
+    switch (sub) {
+        case "ls":
+        case "list":
+            return runDirectoryLs(rest);
+        case "search":
+        case "find":
+            return runDirectorySearch(rest);
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(DIRECTORY_HELP);
+            return;
+        default:
+            console.error(`Unknown directory subcommand: ${sub}\n`);
+            console.log(DIRECTORY_HELP);
+            process.exitCode = 1;
+    }
+}
+async function runDirectoryLs(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), limit: { type: "string" }, offset: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const dirPath = parsed.positionals[0] ?? "/";
+    const result = await apiRequest({
+        method: "GET",
+        host: ctx.host,
+        path: "/api/v1/user/me/directory",
+        auth: ctx.auth,
+        query: {
+            path: dirPath,
+            limit: parsed.values.limit,
+            offset: parsed.values.offset
+        }
+    });
+    assertApiOk(result, "directory ls");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    printDirectoryListing(result.json, dirPath);
+}
+async function runDirectorySearch(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), path: { type: "string" }, mode: { type: "string" }, "content-type": { type: "string" }, limit: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const query = parsed.positionals.join(" ").trim();
+    if (!query) {
+        throw new Error('directory search requires a query: vidfarm directory search "<query>" [--path /raws] [--mode auto|semantic|substring|path] [--content-type talking_head,b_roll] [--limit N]');
+    }
+    const mode = parsed.values.mode;
+    if (mode && !["auto", "semantic", "substring", "path"].includes(mode)) {
+        throw new Error(`--mode must be auto | semantic | substring | path (got "${mode}")`);
+    }
+    const contentTypes = parseContentTypeFlag(parsed.values["content-type"]);
+    const limit = parsed.values.limit != null ? Number(parsed.values.limit) : undefined;
+    const result = await apiRequest({
+        method: "POST",
+        host: ctx.host,
+        path: "/api/v1/user/me/directory/search",
+        auth: ctx.auth,
+        body: {
+            query,
+            ...(parsed.values.path ? { path: String(parsed.values.path) } : {}),
+            ...(mode ? { mode } : {}),
+            ...(contentTypes.length ? { content_type: contentTypes } : {}),
+            ...(limit != null && Number.isFinite(limit) ? { limit } : {})
+        }
+    });
+    assertApiOk(result, "directory search");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    printDirectorySearch(result.json, query);
+}
+// Compact "12.3s · 4.2 MB · video/mp4" line for a directory file item.
+function directoryFileMeta(item) {
+    const parts = [];
+    if (typeof item?.durationSec === "number" && item.durationSec > 0)
+        parts.push(`${item.durationSec.toFixed(1)}s`);
+    if (typeof item?.sizeBytes === "number" && item.sizeBytes > 0)
+        parts.push(formatBytes(item.sizeBytes));
+    if (typeof item?.contentType === "string" && item.contentType)
+        parts.push(item.contentType);
+    return parts.join(" · ");
+}
+function printDirectoryListing(data, requestedPath) {
+    const listedPath = data && typeof data.path === "string" ? data.path : requestedPath;
+    const root = data?.root ? ` ${DIM}[${data.root}]${RESET}` : "";
+    console.log(`${BOLD}${listedPath}${RESET}${root}`);
+    const folders = Array.isArray(data?.folders) ? data.folders : [];
+    const files = Array.isArray(data?.files) ? data.files : [];
+    if (folders.length === 0 && files.length === 0) {
+        console.log(`  ${DIM}(empty)${RESET}`);
+    }
+    for (const f of folders) {
+        console.log(`  ${DIM}dir ${RESET}  ${f?.name ?? ""}/    ${DIM}${f?.path ?? ""}${RESET}`);
+    }
+    for (const f of files) {
+        const meta = directoryFileMeta(f);
+        console.log(`  file  ${f?.name ?? ""}${meta ? `    ${DIM}${meta}${RESET}` : ""}    ${DIM}${f?.path ?? ""}${RESET}`);
+        if (f?.viewUrl)
+            console.log(`        ${FRONTEND}${f.viewUrl}${RESET}`);
+    }
+    const total = folders.length + files.length;
+    const more = data?.next_offset != null ? `  (more: --offset ${data.next_offset})` : "";
+    console.log(`\n  ${total} item${total === 1 ? "" : "s"} (${folders.length} folder${folders.length === 1 ? "" : "s"}, ${files.length} file${files.length === 1 ? "" : "s"})${more}`);
+}
+function printDirectorySearch(data, query) {
+    const results = Array.isArray(data?.results) ? data.results : [];
+    const scope = data?.scope ? ` in ${data.scope}` : "";
+    const modeLabel = data?.mode ? ` · mode=${data.mode}` : "";
+    const semantic = data?.semantic === true ? " · semantic" : data?.semantic === false ? " · keyword-only" : "";
+    console.log(`${BOLD}"${query}"${RESET}${scope}${modeLabel}${semantic}  →  ${results.length} result${results.length === 1 ? "" : "s"}\n`);
+    if (results.length === 0) {
+        console.log(`  ${DIM}(no matches)${RESET}`);
+        return;
+    }
+    results.forEach((r, i) => {
+        const score = typeof r?.score === "number" ? ` ${DIM}score=${r.score.toFixed(3)}${RESET}` : "";
+        const kind = r?.kind === "folder" ? "dir " : "file";
+        console.log(`  ${String(i + 1).padStart(2)}. ${kind}  ${r?.path ?? r?.name ?? ""}${score}`);
+        const meta = directoryFileMeta(r);
+        if (meta)
+            console.log(`      ${DIM}${meta}${RESET}`);
+        if (r?.viewUrl)
+            console.log(`      ${FRONTEND}${r.viewUrl}${RESET}`);
+    });
+}
 // Attach metadata notes to one My Files entry (by id, or file name as a
 // fallback). Notes describe what the file IS and when to use it; the server
 // vector-embeds them so `files --search` finds the asset by meaning later —

package/dist/src/devcli/clip-store.js

@@ -130,7 +130,12 @@ export class ClipStore {
             this.attachEmbeddings([clip]);
         return clip;
     }
-    /** All clips (metadata only), newest first, optionally scoped to a source video. */
+    /**
+     * All clips (metadata only), newest first, optionally scoped to a source
+     * video. `contentTypes` filters by the shot-KIND tag (tags.content_type,
+     * exact match, case-insensitive); when present the limit/offset are applied
+     * AFTER the JS filter (the tag lives in tags_json, not a column).
+     */
     listClips(opts = {}) {
         let sql = "SELECT * FROM clips";
         const args = [];
@@ -139,9 +144,30 @@ export class ClipStore {
             args.push(opts.sourceVideoId);
         }
         sql += " ORDER BY created_at DESC";
-        if (opts.limit) {
+        const wanted = (opts.contentTypes ?? []).map((s) => s.trim().toLowerCase()).filter(Boolean);
+        if (wanted.length) {
+            // Content-type filter can't ride SQL (tag is in JSON), so filter every
+            // matching row in JS, then window with offset/limit.
+            let clips = this.db.prepare(sql).all(...args)
+                .map(rowToClip)
+                .filter((c) => (c.tags.content_type ?? []).some((t) => wanted.includes(String(t).toLowerCase())));
+            if (opts.offset)
+                clips = clips.slice(Math.max(0, Math.floor(opts.offset)));
+            if (opts.limit)
+                clips = clips.slice(0, opts.limit);
+            return clips;
+        }
+        if (opts.limit != null) {
             sql += " LIMIT ?";
             args.push(opts.limit);
+            if (opts.offset) {
+                sql += " OFFSET ?";
+                args.push(Math.max(0, Math.floor(opts.offset)));
+            }
+        }
+        else if (opts.offset) {
+            sql += " LIMIT -1 OFFSET ?";
+            args.push(Math.max(0, Math.floor(opts.offset)));
         }
         return this.db.prepare(sql).all(...args).map(rowToClip);
     }
@@ -313,6 +339,7 @@ function rowToClip(row) {
 }
 function emptyTags() {
     return {
+        content_type: [],
         subject: [],
         action: [],
         emotion: [],