@mevdragon/vidfarm-devcli 0.20.0 → 0.20.2

package/dist/src/cli.js

@@ -25,8 +25,8 @@ import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
 // `serve` command boots the FULL editor locally (single origin, disk-backed
 // records + storage) so power users edit compositions on disk while a browser
-// editor and a coding agent share one source of truth; render stays on the
-// cloud. The remaining commands are thin 1:1 wrappers over the REST API.
+// editor and a coding agent share one source of truth. Render can run locally
+// in-process or hand off to cloud; the remaining commands wrap the REST API.
 const DEFAULT_HOST = "https://vidfarm.cc";
 const DEFAULT_PORT = 4321;
 // Agent skill files the `update-skill` command can install from the live host
@@ -35,18 +35,21 @@ const SKILL_TARGETS = {
     "vidfarm-director": { route: "/skill/vidfarm-director", bundled: "SKILL.director.md" },
     "vidfarm-platform": { route: "/skill/vidfarm-platform", bundled: "SKILL.platform.md" }
 };
-// 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.
+// Most commands below are thin wrappers over ONE Vidfarm REST call (the `→`
+// line documents the exact route). A few convenience commands compose the raw
+// API for you when that is the ergonomic default. 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.
+Most named commands map 1:1 to a REST route (shown as → below). A few compose
+the same routes for file-backed scripting. Use raw REST (or \`vidfarm api\`) when
+you want control; use named commands for ergonomics + prod frontend links.
+Auth: --api-key <key> or VIDFARM_API_KEY.
 
 Usage:
   vidfarm <template_id> [opts]              Start local editor session (default)
@@ -118,7 +121,7 @@ Composition lifecycle (fork → decompose → snapshot → render):
   decompose <forkId>        Split the fork's source into scenes (smart)  → POST .../compositions/:forkId/auto-decompose
 
 Generate AI media and drop it on the timeline (for local coding agents):
-  generate <image|video>    Generate AI media, poll to the finished URL  → POST /api/v1/primitives/{images,videos}/generate
+  generate <image|video>    Generate AI media, poll to the finished public URL  → POST /api/v1/primitives/{images,videos}/generate
     --prompt <text>         What to generate (required)
     --ref <url|@file>       Reference image (repeatable): input_references
                             for video, prompt_attachments for image. @file
@@ -372,9 +375,17 @@ Fine timeline control (trackpad-level verbs on a pulled/served composition — l
   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
+                            --dir <dir|composition.html> pushes local
+                            composition.html + composition.json first
+                            --target local|cloud chooses in-process or
+                            cloud handoff when the backend supports both
                             Cloud render costs ~$0.01-$0.10; against a local
                             'serve' host it renders in-process for FREE.
   render-status <forkId> <renderId>   Poll one render job               → GET  .../compositions/:forkId/renders/:renderId
+  template run <template_id> <operation_name>
+                            Run one template operation via REST          → POST /api/v1/templates/:templateId/operations/:operationName
+                            --payload-file / --payload supply the input
+                            --wait polls GET /api/v1/user/me/jobs/:jobId
   visibility <forkId> <private|public>   Set fork visibility            → PATCH .../compositions/:forkId/visibility
   clone <forkId> [--from current|default] [--version N]
                             New fork: --from current (default) branches this
@@ -495,7 +506,10 @@ Cost spectrum (default to the cheapest approach that works; see SKILL.director.m
 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>)
+    --body-file <path>      Literal request body file (for HTML/text payloads)
+    --content-type <mime>   Content-Type for --body-file (default text/plain)
     --query k=v             Repeatable query param
+    --raw                   Print the exact response body, not pretty JSON
   Examples:
     vidfarm api GET /discover/feed
     vidfarm api POST /api/v1/compositions --data '{"template_id":"template_..."}'
@@ -643,6 +657,9 @@ async function main() {
         case "render-status":
             await runRenderStatusCommand(rest);
             return;
+        case "template":
+            await runTemplateCommand(rest);
+            return;
         case "visibility":
             await runVisibilityCommand(rest);
             return;
@@ -818,8 +835,14 @@ async function apiRequest(input) {
     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 (typeof input.body === "string") {
+            body = input.body;
+            headers["content-type"] = input.contentType ?? "text/plain; charset=utf-8";
+        }
+        else {
+            headers["content-type"] = input.contentType ?? "application/json";
+            body = JSON.stringify(input.body);
+        }
     }
     const res = await fetch(url, { method: input.method.toUpperCase(), headers, body });
     const text = await res.text();
@@ -1631,7 +1654,15 @@ 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 } }
+        options: {
+            ...commonOptions(),
+            data: { type: "string" },
+            "data-file": { type: "string" },
+            "body-file": { type: "string" },
+            "content-type": { type: "string" },
+            query: { type: "string", multiple: true },
+            raw: { type: "boolean", default: false }
+        }
     });
     const method = parsed.positionals[0];
     const routePath = parsed.positionals[1];
@@ -1639,10 +1670,16 @@ async function runApiCommand(argv) {
         throw new Error(`api requires <METHOD> <path>.\n\nExample: vidfarm api GET /discover/feed`);
     }
     const ctx = commonContext(parsed.values);
+    if (parsed.values["data-file"] && parsed.values["body-file"]) {
+        throw new Error("api accepts either --data-file (JSON) or --body-file (literal), not both.");
+    }
     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["body-file"]) {
+        body = readFileSync(path.resolve(process.cwd(), String(parsed.values["body-file"])), "utf8");
+    }
     else if (parsed.values.data) {
         body = JSON.parse(String(parsed.values.data));
     }
@@ -1652,16 +1689,139 @@ async function runApiCommand(argv) {
         path: routePath,
         auth: ctx.auth,
         query: collectKeyValues(parsed.values.query),
-        body
+        body,
+        contentType: parsed.values["body-file"] ? parsed.values["content-type"] : undefined
     });
     if (!ctx.json) {
         const color = result.ok ? GREEN : RED;
         console.log(`${color}${method.toUpperCase()} ${routePath} → ${result.status}${RESET}`);
     }
-    printJson(result.json ?? result.text);
+    if (parsed.values.raw)
+        process.stdout.write(result.text);
+    else
+        printJson(result.json ?? result.text);
     if (!result.ok)
         process.exitCode = 1;
 }
+function parseJsonInput(raw, label) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${label} must be valid JSON.`);
+    }
+}
+async function waitForJobCompletion(ctx, jobId, pollMs) {
+    const intervalMs = Number.isFinite(pollMs) && pollMs > 0 ? pollMs : 2000;
+    while (true) {
+        const result = await dispatch(ctx, {
+            method: "GET",
+            path: `/api/v1/user/me/jobs/${encodeURIComponent(jobId)}`
+        }, ctx.target === "cloud" ? "cloud" : "local");
+        if (!result.ok) {
+            return result;
+        }
+        const status = String(result.json?.status ?? "").toLowerCase();
+        if (!["queued", "running", "waiting_for_provider", "waiting_for_render", "waiting_for_child", "waiting_for_human"].includes(status)) {
+            return result;
+        }
+        await sleep(intervalMs);
+    }
+}
+async function runTemplateCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            tracer: { type: "string" },
+            wait: { type: "boolean", default: false },
+            "poll-ms": { type: "string" },
+            body: { type: "string" },
+            "body-file": { type: "string" },
+            payload: { type: "string" },
+            "payload-file": { type: "string" },
+            "webhook-url": { type: "string" }
+        }
+    });
+    const subcommand = parsed.positionals[0];
+    if (subcommand === "help" || subcommand === "--help" || subcommand === "-h" || !subcommand) {
+        console.log(`vidfarm template — run template operations via REST
+  template run <template_id> <operation_name> [--payload-file payload.json | --payload '{...}']
+    [--tracer <id>] [--webhook-url <url>] [--wait] [--poll-ms 2000]
+    --body-file / --body can send the exact REST envelope instead of auto-wrapping
+`);
+        return;
+    }
+    if (subcommand !== "run") {
+        throw new Error(`Unknown template subcommand: ${subcommand}`);
+    }
+    const templateId = parsed.positionals[1];
+    const operationName = parsed.positionals[2];
+    if (!templateId || !operationName) {
+        throw new Error("template run requires <template_id> <operation_name>.");
+    }
+    const ctx = commonContext(parsed.values);
+    if (ctx.target === "both") {
+        throw new Error("template run only supports one backend at a time. Use --cloud or omit it for the local backend.");
+    }
+    const rawBody = parsed.values["body-file"]
+        ? readFileSync(path.resolve(process.cwd(), String(parsed.values["body-file"])), "utf8")
+        : typeof parsed.values.body === "string"
+            ? parsed.values.body
+            : null;
+    const payloadSource = parsed.values["payload-file"]
+        ? readFileSync(path.resolve(process.cwd(), String(parsed.values["payload-file"])), "utf8")
+        : typeof parsed.values.payload === "string"
+            ? parsed.values.payload
+            : null;
+    let body;
+    if (rawBody !== null) {
+        body = parseJsonInput(rawBody, "template body");
+    }
+    else {
+        const payload = payloadSource === null ? {} : parseJsonInput(payloadSource, "template payload");
+        if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+            throw new Error("template payload must be a JSON object.");
+        }
+        body = {
+            tracer: typeof parsed.values.tracer === "string" && parsed.values.tracer.trim()
+                ? parsed.values.tracer.trim()
+                : `template_run_${templateId}_${operationName}_${Date.now()}`,
+            payload,
+            ...(typeof parsed.values["webhook-url"] === "string" && parsed.values["webhook-url"].trim()
+                ? { webhook_url: parsed.values["webhook-url"].trim() }
+                : {})
+        };
+    }
+    const result = await dispatch(ctx, {
+        method: "POST",
+        path: `/api/v1/templates/${encodeURIComponent(templateId)}/operations/${encodeURIComponent(operationName)}`,
+        body
+    }, ctx.target);
+    if (!result.ok && result.status !== 202) {
+        assertApiOk(result, `template run ${templateId}:${operationName}`);
+    }
+    if (!parsed.values.wait) {
+        emitResult(result, ctx.json);
+        return;
+    }
+    const jobId = result.json?.job_id;
+    if (typeof jobId !== "string" || !jobId.trim()) {
+        emitResult(result, ctx.json);
+        return;
+    }
+    const pollMs = Number(parsed.values["poll-ms"] ?? 2000);
+    const final = await waitForJobCompletion(ctx, jobId, pollMs);
+    emitResult(final, ctx.json);
+    const finalStatus = String(final.json?.status ?? "").toLowerCase();
+    if (!final.ok || !["succeeded", "completed"].includes(finalStatus)) {
+        process.exitCode = 1;
+    }
+}
 // ── Discover & inspiration ──────────────────────────────────────────────────
 // `discover` lists TEMPLATES; `--query` keyword-searches the catalog so an agent
 // CLI (Claude Code / Codex) can answer "which templates suit my <offer>?". Each
@@ -2168,18 +2328,40 @@ async function runRenderCommand(argv) {
     const parsed = parseArgs({
         args: argv,
         allowPositionals: true,
-        options: { ...commonOptions(), title: { type: "string" }, tracer: { type: "string" }, wait: { type: "boolean", default: false } }
+        options: {
+            ...commonOptions(),
+            dir: { type: "string" },
+            title: { type: "string" },
+            tracer: { type: "string" },
+            target: { type: "string", default: "local" },
+            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 renderTarget = String(parsed.values.target ?? "local");
+    if (renderTarget !== "local" && renderTarget !== "cloud") {
+        throw new Error(`render --target must be local or cloud, got: ${renderTarget}`);
+    }
+    const sourceDir = parsed.values.dir ? resolveCompositionSourceDir(String(parsed.values.dir)) : null;
+    if (sourceDir) {
+        await pushCompositionFromDir({
+            forkId,
+            rootDir: sourceDir,
+            host: ctx.host,
+            auth: ctx.auth,
+            json: ctx.json,
+            action: "render"
+        });
+    }
     const result = await apiRequest({
         method: "POST",
         host: ctx.host,
         path: `/api/v1/compositions/${encodeURIComponent(forkId)}/render`,
         auth: ctx.auth,
-        body: { title: parsed.values.title, tracer: parsed.values.tracer }
+        body: { title: parsed.values.title, tracer: parsed.values.tracer, render_target: renderTarget }
     });
     assertApiOk(result, "render");
     const renderId = result.json?.renderId;
@@ -2187,7 +2369,7 @@ async function runRenderCommand(argv) {
         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]]);
+        emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.expectedOutputPublicUrl ?? result.json?.outputUrl]]);
         return;
     }
     // --wait: poll the render job until it settles.
@@ -2206,10 +2388,52 @@ async function runRenderCommand(argv) {
         if (status === "SUCCEEDED" || status === "FAILED")
             break;
     }
-    emitResult(last, ctx.json, [["Rendered MP4 ", last.json?.outputUrl]]);
+    emitResult(last, ctx.json, [["Rendered MP4 ", last.json?.expectedOutputPublicUrl ?? last.json?.outputUrl]]);
     if (String(last.json?.status) === "FAILED")
         process.exitCode = 1;
 }
+function resolveCompositionSourceDir(inputPath) {
+    const absolute = path.resolve(process.cwd(), inputPath);
+    if (!existsSync(absolute)) {
+        throw new Error(`render --dir path does not exist: ${absolute}`);
+    }
+    const stat = statSync(absolute);
+    if (stat.isDirectory())
+        return absolute;
+    if (stat.isFile() && path.basename(absolute) === "composition.html")
+        return path.dirname(absolute);
+    throw new Error("render --dir must point to a directory or composition.html.");
+}
+async function pushCompositionFromDir(input) {
+    const htmlPath = path.join(input.rootDir, "composition.html");
+    if (!existsSync(htmlPath)) {
+        throw new Error(`No composition.html at ${htmlPath}.`);
+    }
+    const html = readFileSync(htmlPath, "utf8");
+    if (!html.includes("data-composition-id=")) {
+        throw new Error("composition.html is missing data-composition-id — refusing to render a malformed composition.");
+    }
+    const jsonPath = path.join(input.rootDir, "composition.json");
+    const compositionJson = existsSync(jsonPath) ? readFileSync(jsonPath, "utf8") : null;
+    if (compositionJson !== null) {
+        try {
+            JSON.parse(compositionJson || "{}");
+        }
+        catch (error) {
+            throw new Error(`composition.json is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (!input.json)
+        console.log(`[vidfarm] ${input.action}: pushing ${input.rootDir} → ${input.forkId}`);
+    await putComposition(`${input.host}/api/v1/compositions/${encodeURIComponent(input.forkId)}/composition.html`, "PUT", html, "text/html; charset=utf-8", input.auth);
+    if (!input.json)
+        console.log(`[vidfarm] pushed composition.html (${Buffer.byteLength(html)} bytes)`);
+    if (compositionJson !== null) {
+        await putComposition(`${input.host}/api/v1/compositions/${encodeURIComponent(input.forkId)}/composition.json`, "PATCH", compositionJson, "application/json", input.auth);
+        if (!input.json)
+            console.log(`[vidfarm] pushed composition.json (${Buffer.byteLength(compositionJson)} bytes)`);
+    }
+}
 async function runRenderStatusCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: true, options: commonOptions() });
     const forkId = parsed.positionals[0];
@@ -2219,7 +2443,7 @@ async function runRenderStatusCommand(argv) {
     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]]);
+    emitResult(result, ctx.json, [["Rendered MP4 ", result.json?.expectedOutputPublicUrl ?? result.json?.outputUrl]]);
 }
 // ── AI generation + timeline placement (for local coding agents) ────────────
 // `generate` submits an AI image/video primitive job and (by default) polls it

package/dist/src/devcli/sync.js

@@ -66,16 +66,42 @@ async function readBytes(ctx, space, item) {
         const { withLocalBackend } = await import("./local-backend.js");
         const backend = await withLocalBackend({ home: ctx.home, apiKey: ctx.apiKey });
         const u = new URL(item.viewUrl, "http://vidfarm.local");
+        if (!isLocalFileViewPath(u.pathname)) {
+            throw new Error(`Refusing local sync read outside Vidfarm file storage: ${item.path}`);
+        }
         const res = await backend.app.request(u.pathname + u.search, { headers: authHeaders(ctx.apiKey) });
         if (!res.ok)
             throw new Error(`local read ${item.path} → HTTP ${res.status}`);
         return Buffer.from(await res.arrayBuffer());
     }
-    const res = await fetch(item.viewUrl, { headers: authHeaders(ctx.apiKey) });
+    const url = validateCloudFileViewUrl(ctx, item);
+    const res = await fetch(url, { headers: authHeaders(ctx.apiKey) });
     if (!res.ok)
         throw new Error(`cloud read ${item.path} → HTTP ${res.status}`);
     return Buffer.from(await res.arrayBuffer());
 }
+function isLocalFileViewPath(pathname) {
+    return pathname === "/api/v1/user/me/files/view" || pathname === "/template-media" || pathname.startsWith("/storage/");
+}
+function validateCloudFileViewUrl(ctx, item) {
+    let url;
+    try {
+        url = new URL(item.viewUrl || "", ctx.host);
+    }
+    catch {
+        throw new Error(`Invalid cloud view URL for ${item.path}`);
+    }
+    const host = new URL(ctx.host);
+    const isSameOrigin = url.origin === host.origin;
+    const isS3 = /^https:\/\/[^/]+\.s3[.-][a-z0-9-]+\.amazonaws\.com$/i.test(url.origin)
+        || /^https:\/\/s3[.-][a-z0-9-]+\.amazonaws\.com$/i.test(url.origin)
+        || /\.s3[.-][a-z0-9-]+\.amazonaws\.com$/i.test(url.hostname);
+    if (isSameOrigin && isLocalFileViewPath(url.pathname))
+        return url;
+    if (isS3)
+        return url;
+    throw new Error(`Refusing cloud sync read from non-Vidfarm URL for ${item.path}`);
+}
 /** Upload bytes into a space's My Files at folderPath/fileName (multipart — the
  *  one transport that works on both S3 and local storage). */
 async function uploadBytes(ctx, space, input) {
@@ -213,9 +239,10 @@ export async function runSyncCommand(argv) {
         home: values.home
     };
     // Scope: a /files subtree (default the whole root).
-    let rootPath = (positionals[0] ?? "/files").trim();
-    if (!rootPath.startsWith("/files")) {
-        throw new Error(`sync currently covers the /files (My Files) root — got "${rootPath}". Raws sync is a follow-up.`);
+    const rawRootPath = positionals[0] ?? "/files";
+    const rootPath = normalizeSyncRoot(rawRootPath);
+    if (!rootPath) {
+        throw new Error(`sync currently covers the /files (My Files) root — got "${rawRootPath}". Raws sync is a follow-up.`);
     }
     const srcSpace = direction === "push" ? "local" : "cloud";
     const dstSpace = direction === "push" ? "cloud" : "local";
@@ -235,7 +262,7 @@ export async function runSyncCommand(argv) {
                 console.log(`  ${GREEN}+ new${RESET}     ${src.path}`);
             }
             else {
-                await transfer(ctx, srcSpace, dstSpace, src, src.name);
+                await transfer(ctx, srcSpace, dstSpace, src, fileNameFromSyncPath(src.path));
                 console.log(`  ${GREEN}✓ sent${RESET}    ${src.path}`);
             }
             transferred += 1;
@@ -260,14 +287,15 @@ export async function runSyncCommand(argv) {
             continue;
         }
         if (resolution === "keep-both") {
-            await transfer(ctx, srcSpace, dstSpace, src, suffixName(src.name, srcSpace));
-            console.log(`  ${YELLOW}✓ both${RESET}    ${src.path} ${DIM}→ ${suffixName(src.name, srcSpace)}${RESET}`);
+            const keepBothName = suffixName(fileNameFromSyncPath(src.path), srcSpace);
+            await transfer(ctx, srcSpace, dstSpace, src, keepBothName);
+            console.log(`  ${YELLOW}✓ both${RESET}    ${src.path} ${DIM}→ ${keepBothName}${RESET}`);
         }
         else {
             // Overwrite: drop the target copy first so we replace rather than dup.
             if (dst.id)
                 await deleteAttachment(ctx, dstSpace, dst.id);
-            await transfer(ctx, srcSpace, dstSpace, src, src.name);
+            await transfer(ctx, srcSpace, dstSpace, src, fileNameFromSyncPath(src.path));
             console.log(`  ${GREEN}✓ over${RESET}    ${src.path}`);
         }
         transferred += 1;
@@ -277,15 +305,44 @@ export async function runSyncCommand(argv) {
         console.log(`  ${DIM}(dry run — nothing was written)${RESET}`);
 }
 async function transfer(ctx, from, to, item, fileName) {
+    if (!item.path.startsWith("/files/")) {
+        throw new Error(`Refusing to sync item outside /files: ${item.path}`);
+    }
+    const folderPath = folderPathFromSyncPath(item.path);
     const bytes = await readBytes(ctx, from, item);
     await uploadBytes(ctx, to, {
         fileName,
-        folderPath: item.folderPath.replace(/^files\/?/, "").replace(/^\/+|\/+$/g, ""),
+        folderPath,
         contentType: item.contentType,
         notes: item.notes,
         bytes
     });
 }
+function normalizeSyncRoot(value) {
+    const raw = value.trim();
+    const withSlash = raw.startsWith("/") ? raw : `/${raw}`;
+    const normalized = path.posix.normalize(withSlash).replace(/\/+$/, "") || "/files";
+    if (normalized === "/files" || normalized.startsWith("/files/"))
+        return normalized;
+    return null;
+}
+function fileNameFromSyncPath(value) {
+    const name = path.posix.basename(value);
+    if (!name || name === "." || name === ".." || name.includes("/")) {
+        throw new Error(`Invalid sync file path: ${value}`);
+    }
+    return name;
+}
+function folderPathFromSyncPath(value) {
+    if (!value.startsWith("/files/"))
+        throw new Error(`Invalid sync file path: ${value}`);
+    const dir = path.posix.dirname(value);
+    if (dir === "/files")
+        return "";
+    if (!dir.startsWith("/files/"))
+        throw new Error(`Invalid sync file path: ${value}`);
+    return dir.slice("/files/".length);
+}
 function normalizePolicy(v) {
     const s = String(v ?? "").trim().toLowerCase();
     if (["newest", "skip", "keep-both", "local", "cloud"].includes(s))

package/dist/src/editor-chat.js

@@ -79,7 +79,7 @@ export function buildTemplateEditorChatSystemPrompt(input) {
         "FINE TIMELINE CONTROL — you have trackpad-level verbs; use them instead of rewriting the whole document for small changes: (1) set_layer_keyframes authors a custom, script-free CSS @keyframes animation on ONE layer that previews AND renders — pass layer_key + keyframes:[{offset(0..1), opacity?, translate_x?, translate_y?, scale?, rotate?}, …] (>=2 stops), optional keyframe_easing (linear/ease/ease-in/ease-out/ease-in-out/cubic-bezier(...)) and keyframe_duration (seconds, default = clip duration). translate_x/translate_y are percentages of the layer's OWN box. Example fly-up-and-fade-in: keyframes=[{offset:0,opacity:0,translate_y:40},{offset:1,opacity:1,translate_y:0}]. This is the durable way to hand-author motion beyond the Ken Burns / transition / caption presets — the JS runtime adapters (anime.js/GSAP/Lottie) are devcli-only. (2) nudge_layers shifts one or more layers by a RELATIVE delta_start (seconds) and/or delta_track (lanes) — pass layer_key or layer_keys; grouped clips move together. (3) ripple_edit inserts (delta_start>0) or closes (delta_start<0) time at at_time and shifts every downstream clip so the rest of the timeline stays in sync — use it to make room before an insert or to close a gap you can see in timeline_gaps. (4) trim_layer moves ONE edge to a time: edge='start' (left; advances the in-point, and for video/audio pushes the media start so the visible frame is unchanged) or edge='end' (right; changes duration), with to_time in composition seconds. (5) set_layer_zindex restacks: z_order='front'|'back'|'forward'|'backward' (stacking == track index; higher draws on top) or an explicit track. All of these auto-resolve track collisions and note it in the summary; read the NEXT editor_context to confirm the new start/duration/track/animation landed.",
         "If the user asks to export, render, publish, or produce the final MP4 for this composition (phrases like 'export it', 'render this', 'kick off the export', 'make the mp4'), call editor_action with action_type=export_composition and a brief explanation. This is the same action as the editor's Export button — it queues the composition on production AWS Lambda. Do NOT try to hit any /api/v1/compositions/:id/export route via http_request for this; use the editor_action tool. After calling export_composition, tell the user the export has started and that the finished MP4 URL will appear once the render succeeds; do not fabricate a URL or claim success until a later turn shows last_export_url populated in editor_context.",
         "CONFIRM BEFORE RENDERING — DO NOT auto-render. Rendering the final MP4 is a slow, costly, screen-taking action, so by DEFAULT you must NOT call export_composition on your own initiative. After you finish an edit (a swap, a re-theme, a scene rebuild), STOP and let the user review the live preview, then ASK a short question like 'Happy with the preview? Want me to render the final MP4?' and wait for a yes. Only fire export_composition when EITHER (a) the user explicitly asks to render/export/'make the mp4' in that turn, or (b) the user has told you up front to just render without asking (e.g. 'edit and render it', 'no need to check, just export'). If in doubt, ask — never surprise the user with a render. Never render merely because you judged the edit 'done'.",
-        "MEDIA SWAP — TARGET A REAL LAYER KEY, NOT A SCENE NAME. To swap a clip's media with set_layer_media, the layer_key MUST be an EXACT key (or its slug) from editor_context.layers — that array lists every targetable layer with its key, slug, kind (video/image/audio), and current src. Read it and copy the real key of the video/image layer you mean; do NOT invent a semantic name (like 'growth_examples' or 'mistakes_reflection') unless that exact string appears as a layer key/slug in editor_context, and never target a scene label/group when you mean the video inside it. If set_layer_media returns 'No change applied' or 'Layer not found', the error now lists the actual media layers — re-read it and retry with one of those exact keys. NEVER report a swap as done until the NEXT editor_context shows the layer's src changed.",
+        "MEDIA SWAP — TARGET A REAL LAYER KEY, NOT A SCENE NAME. To swap a clip's media with set_layer_media, the layer_key MUST be an EXACT key (or its slug) from editor_context.layers — that array lists every targetable layer with its key, slug, kind (video/image/audio), and current src. Read it and copy the real key of the video/image layer you mean; do NOT invent a semantic name (like 'growth_examples' or 'mistakes_reflection') unless that exact string appears as a layer key/slug in editor_context, and never target a scene label/group when you mean the video inside it. If set_layer_media returns 'No change applied' or 'Layer not found', the error now lists the actual media layers — re-read it and retry with one of those exact keys. This applies to EVERY set_layer_media field (src, object_fit, object_position, volume, muted, ken_burns, transitions), not just src: the layer_key you used to add a layer (e.g. add_layer layer_key='vf-fishing-snippet-1') becomes an 'element_'-prefixed key on the timeline, so target the real key/slug shown in editor_context, not the bare name you passed earlier. NEVER report a swap or fit/position change as done while any editor_action in this turn came back with a ⚠ / 'Layer not found' error — those calls did NOT apply; re-read the listed keys, retry against a real one, and only confirm success once the action returns ✓ (and, for src, the NEXT editor_context shows the layer changed). Do not claim you changed layers you never successfully targeted.",
         "GETTING THE MEDIA URL IS EASY — USE browse_files. When the user says 'use my raws' / 'it's in my file directory' / 'the fishing clips', you do NOT need them to paste a URL. Call browse_files action=search (or list path='/raws') to find the clip, then action=read with its file_id — the read result's view_url IS the public, ready-to-use media URL. Drop that view_url straight into set_layer_media src (or add_layer src). Do not stall asking the user for a URL you can look up yourself, and never pass a placeholder like 'please-ignore' as src.",
         "The editor_context block includes last_export_url, last_export_title, last_export_status, and last_export_render_id when a render has succeeded in this session. Treat last_export_url as the current 'finished Export MP4' for this composition. If the user asks to approve, package, share, or schedule the exported video without providing an explicit URL, use last_export_url as the primary MP4 media (kind=video, role=primary) for POST /api/v1/approved/posts. If last_export_url is null, tell the user to Export first (or offer to call editor_action with action_type=export_composition on their behalf) instead of guessing a URL.",
         "Each layer in editor_context includes element_id (data-hf-id), optional slug (data-hf-slug), and optional note (data-hf-note). layer_key on any editor_action may be EITHER the element_id or the slug — prefer the slug when the user (or a viral DNA blurb) refers to a layer by its human name like 'the hero_image'. Use set_layer_identity to add/change a layer's slug or note. Slugs are the stable AI-friendly handle: when planning viral DNA notes, reference the element by its slug (e.g., 'raise the {{hero_image}} to full canvas at 4s') so future turns can resolve it deterministically.",

package/dist/src/frontend/file-directory.js

@@ -501,20 +501,23 @@ export function createDirectoryExplorer(mount, opts = {}) {
             return;
         selbar.innerHTML = "";
         selbar.appendChild(el("span", "rk-dir-selcount", n + " selected"));
-        if (mode === "attach") {
-            const att = el("button", "rk-dir-selbtn", "Attach");
-            att.type = "button";
-            att.addEventListener("click", () => { emitAttach(Array.from(selection.values())); clearSelection(); });
-            selbar.appendChild(att);
-        }
-        const cp = el("button", "rk-dir-selbtn", "Copy paths");
+        const picked = () => Array.from(selection.values());
+        // Primary action stays on the bar; everything else tucks into a "⋯" menu so
+        // the toolbar never overflows in the narrow editor dock.
+        const cp = el("button", "rk-dir-selbtn is-primary", "Copy paths");
         cp.type = "button";
-        cp.addEventListener("click", () => copyPath(Array.from(selection.values()).map((s) => s.path).join("\n")));
-        const clr = el("button", "rk-dir-selbtn is-ghost", "Clear");
-        clr.type = "button";
-        clr.addEventListener("click", clearSelection);
+        cp.addEventListener("click", () => copyPath(picked().map((s) => s.path).join("\n")));
         selbar.appendChild(cp);
-        selbar.appendChild(clr);
+        const more = [];
+        if (mode === "attach")
+            more.push({ label: "Attach", run: () => { emitAttach(picked()); clearSelection(); } });
+        more.push({ label: "Copy paths", run: () => copyPath(picked().map((s) => s.path).join("\n")) });
+        more.push({ label: "Clear selection", run: clearSelection });
+        const menuBtn = el("button", "rk-dir-selbtn is-ghost rk-dir-selmore", "⋯");
+        menuBtn.type = "button";
+        menuBtn.setAttribute("aria-label", "More actions");
+        menuBtn.addEventListener("click", (e) => { e.stopPropagation(); openMenuAt(menuBtn, more); });
+        selbar.appendChild(menuBtn);
     }
     function checkbox(it) {
         const box = el("input", "rk-dir-check");
@@ -719,15 +722,27 @@ export function createDirectoryExplorer(mount, opts = {}) {
             return;
         uploading = true;
         const folder = currentFolder();
+        const root = currentRoot();
         const arr = Array.from(list);
         let done = 0, failed = 0;
+        // The server may re-home an upload (e.g. /temp files land in a dated
+        // subfolder). Track where the bytes actually landed so we can reveal them —
+        // otherwise the refresh shows the folder we uploaded FROM, which looks empty.
+        let landedFolder = null;
         dropText.textContent = "Uploading " + arr.length + " file(s)…";
+        const finish = () => {
+            uploading = false;
+            if (failed)
+                toast(failed + " of " + arr.length + " failed");
+            const target = root && landedFolder != null ? buildDirectoryPath(root, landedFolder) : null;
+            if (target && target !== currentPath)
+                navigate(target); // reveal the uploads
+            else
+                load(true);
+        };
         const next = (i) => {
             if (i >= arr.length) {
-                uploading = false;
-                if (failed)
-                    toast(failed + " of " + arr.length + " failed");
-                load(true);
+                finish();
                 return;
             }
             const fd = new FormData();
@@ -735,7 +750,13 @@ export function createDirectoryExplorer(mount, opts = {}) {
             fd.append("folder_path", folder);
             fetch(endpoint, { method: "POST", credentials: "same-origin", body: fd })
                 .then((r) => { if (!r.ok)
-                throw new Error("http " + r.status); done++; })
+                throw new Error("http " + r.status); return r.json().catch(() => null); })
+                .then((j) => {
+                done++;
+                const fp = j && ((j.file && j.file.folderPath) ?? (j.attachment && j.attachment.folderPath));
+                if (typeof fp === "string" && landedFolder == null)
+                    landedFolder = fp;
+            })
                 .catch(() => { failed++; })
                 .then(() => next(i + 1));
         };
@@ -943,7 +964,9 @@ export function openDirectoryPicker(opts = {}) {
         mode: "standalone",
         showSearch: true,
         showMultiSelect: false,
-        showUpload: false, // the picker only selects; it doesn't upload
+        // Opt-in upload: when allowed, the explorer shows its drop zone so users can
+        // add a file to the currently-open folder (Files/Temp), then click it to pick.
+        showUpload: opts.allowUpload === true,
         // In file mode a name-click resolves the pick; folders still navigate.
         primaryClick: select === "file" ? "attach" : "copyPath",
         onNavigate: (p) => syncFooter(p),