@mevdragon/vidfarm-devcli 0.3.0 → 0.3.2

package/SKILL.director.md

@@ -254,17 +254,20 @@ For agents that operate Vidfarm headlessly, the typical loop is:
 
 Always send a stable `tracer` on publish to make retries idempotent.
 
-## Local dev loop with `vidfarm dev-serve`
+## Local dev loop with `vidfarm-devcli`
 
-For iterating on a composition on disk (e.g. Claude Code editing HTML directly), skip the cloud entirely:
+For iterating on a composition on disk (e.g. Claude Code editing HTML directly), pair the hosted editor with a local composition directory:
 
 ```bash
-npm install -g @mevdragon/vidfarm-devcli
-vidfarm dev-serve --dir ./my-fork --port 4321
-# ./my-fork must contain composition.html; composition.json + manifest.json optional
+npx -y @mevdragon/vidfarm-devcli <template_id>
+# → downloads composition.html/json + manifest.json into .vidfarm/<template_id>/
+# → starts dev-serve on http://localhost:4321
+# → prints https://vidfarm.cc/editor/<template_id>?fork=<forkId>&dev=http%3A%2F%2Flocalhost%3A4321
 ```
 
-Then open the Trackpad Editor with `?dev=1` appended to the URL (or `?dev=host:port` / `?dev=<full-url>`). An orange **LOCAL DEV MODE** banner pins to the top with an Exit button. All fork API fetches route to the devcli instead of the deployed API; file saves on disk push an SSE reload event and the iframe re-fetches automatically.
+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.
 
 The dev source is persisted in `localStorage.VIDFARM_DEV_SOURCE`, so you don't need to keep the `?dev=` param in the URL after the first load.
 

package/dist/src/dev-serve.js

@@ -1,5 +1,5 @@
 import { createServer } from "node:http";
-import { existsSync, mkdirSync, readFileSync, watch, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, statSync, watch, writeFileSync } from "node:fs";
 import path from "node:path";
 import { parseArgs } from "node:util";
 // vidfarm dev-serve — a tiny HTTP layer that lets the browser editor point at
@@ -14,6 +14,17 @@ const CORS_HEADERS = {
     "access-control-allow-headers": "content-type,authorization",
     "access-control-max-age": "600"
 };
+// Cap request bodies at 8MB so a runaway or malicious client can't OOM the
+// dev server. A composition.html + inlined asset is normally <1MB.
+const MAX_REQUEST_BODY_BYTES = 8 * 1024 * 1024;
+// Ignore filesystem events for this long after we write from an HTTP handler,
+// so the editor's own PUT/PATCH doesn't trigger a self-reload loop. `fs.watch`
+// on macOS fires 1–3 events per rename, plus a tail event from the editor's
+// auto-format step.
+const SELF_WRITE_SUPPRESS_MS = 500;
+// Bump on every new dev-serve process so a reconnecting SSE client can tell
+// whether the server restarted (and therefore whether it must resync files).
+const SERVER_INSTANCE_ID = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 export async function runDevServeCommand(argv) {
     const parsed = parseArgs({
         args: argv,
@@ -24,14 +35,22 @@ export async function runDevServeCommand(argv) {
     });
     const rootDir = path.resolve(process.cwd(), parsed.values.dir);
     const port = Number(parsed.values.port);
+    if (!Number.isFinite(port) || port <= 0 || port > 65535) {
+        throw new Error(`Invalid --port: ${parsed.values.port}`);
+    }
     if (!existsSync(rootDir)) {
         mkdirSync(rootDir, { recursive: true });
     }
     let nextClientId = 1;
+    let mutationCursor = 0;
     const clients = new Set();
+    const selfWriteSuppressUntil = new Map();
     function broadcast(event, data) {
         const payload = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
-        for (const client of clients) {
+        // Snapshot the client set before iterating: `client.res.write` can
+        // synchronously destroy the response (broken pipe), which mutates the
+        // Set mid-iteration and can skip healthy clients.
+        for (const client of [...clients]) {
             try {
                 client.res.write(payload);
             }
@@ -40,16 +59,45 @@ export async function runDevServeCommand(argv) {
             }
         }
     }
+    function isSelfWriteSuppressed(filename) {
+        if (!filename)
+            return false;
+        const until = selfWriteSuppressUntil.get(filename);
+        if (!until)
+            return false;
+        if (Date.now() > until) {
+            selfWriteSuppressUntil.delete(filename);
+            return false;
+        }
+        return true;
+    }
+    function suppressReloadFromSelfWrite(filePath) {
+        const rel = path.relative(rootDir, filePath);
+        if (!rel || rel.startsWith(".."))
+            return;
+        // fs.watch reports filenames relative to the watched root — match both the
+        // basename and the relative path, since macOS emits either form.
+        selfWriteSuppressUntil.set(rel, Date.now() + SELF_WRITE_SUPPRESS_MS);
+        selfWriteSuppressUntil.set(path.basename(filePath), Date.now() + SELF_WRITE_SUPPRESS_MS);
+    }
     // fs.watch fires on any child change. Coalesce bursts so a single save
-    // doesn't spam the editor with 3 reload events.
+    // doesn't spam the editor with 3 reload events. Also drop events for files
+    // we JUST wrote ourselves so PUT/PATCH doesn't loop into a client reload.
     let reloadTimer = null;
+    let pendingReloadFile = null;
     const scheduleReload = (filename) => {
+        if (isSelfWriteSuppressed(filename))
+            return;
+        pendingReloadFile = filename ?? pendingReloadFile;
         if (reloadTimer)
             clearTimeout(reloadTimer);
         reloadTimer = setTimeout(() => {
             reloadTimer = null;
-            broadcast("reload", { file: filename, at: Date.now() });
-            console.log(`[dev-serve] reload → ${filename ?? "(unknown)"}`);
+            const file = pendingReloadFile;
+            pendingReloadFile = null;
+            mutationCursor += 1;
+            broadcast("reload", { file, at: Date.now(), cursor: mutationCursor });
+            console.log(`[dev-serve] reload → ${file ?? "(unknown)"}`);
         }, 80);
     };
     try {
@@ -59,19 +107,50 @@ export async function runDevServeCommand(argv) {
     }
     catch (error) {
         console.warn(`[dev-serve] watch failed: ${error instanceof Error ? error.message : String(error)}`);
+        console.warn("[dev-serve] file changes will NOT trigger editor reloads. On Linux, install inotify-tools or run inside a supported filesystem.");
     }
-    const server = createServer((req, res) => handleRequest(req, res, rootDir, clients, nextClientId++));
+    const server = createServer((req, res) => handleRequest(req, res, {
+        rootDir,
+        clients,
+        clientId: nextClientId++,
+        mutationCursor: () => mutationCursor,
+        suppressReloadFromSelfWrite
+    }));
+    server.on("error", (error) => {
+        if (error.code === "EADDRINUSE") {
+            console.error(`[dev-serve] port ${port} is already in use.`);
+            console.error(`[dev-serve] pass --port <n> to pick a different port, or stop the process bound to ${port}.`);
+            process.exit(1);
+        }
+        console.error(`[dev-serve] server error: ${error.message}`);
+        process.exit(1);
+    });
     server.listen(port, () => {
         console.log(`[dev-serve] serving ${rootDir}`);
         console.log(`[dev-serve] listening on http://localhost:${port}`);
         console.log(`[dev-serve] editor: open with ?dev=${encodeURIComponent(`http://localhost:${port}`)}`);
     });
-    process.on("SIGINT", () => {
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
         console.log("\n[dev-serve] shutting down");
+        for (const client of clients) {
+            try {
+                client.res.end();
+            }
+            catch { }
+        }
+        clients.clear();
         server.close(() => process.exit(0));
-    });
+        // Fallback: if in-flight sockets keep the server open, force-exit after 2s.
+        setTimeout(() => process.exit(0), 2000).unref();
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
 }
-function handleRequest(req, res, rootDir, clients, clientId) {
+function handleRequest(req, res, ctx) {
     const method = (req.method ?? "GET").toUpperCase();
     const url = new URL(req.url ?? "/", `http://localhost`);
     const pathname = url.pathname;
@@ -85,15 +164,35 @@ function handleRequest(req, res, rootDir, clients, clientId) {
             ...CORS_HEADERS,
             "content-type": "text/event-stream",
             "cache-control": "no-cache",
-            connection: "keep-alive"
+            connection: "keep-alive",
+            "x-accel-buffering": "no"
         });
-        res.write(`event: hello\ndata: ${JSON.stringify({ at: Date.now() })}\n\n`);
-        const client = { res, id: clientId };
-        clients.add(client);
-        req.on("close", () => clients.delete(client));
+        // Include instance id + current cursor so a reconnecting client can tell
+        // if the server restarted (missed events) or if it just needs to catch up.
+        res.write(`event: hello\ndata: ${JSON.stringify({
+            at: Date.now(),
+            instance: SERVER_INSTANCE_ID,
+            cursor: ctx.mutationCursor()
+        })}\n\n`);
+        const client = { res, id: ctx.clientId };
+        ctx.clients.add(client);
+        // Heartbeat keeps intermediate proxies (and iOS Safari) from timing out
+        // the long-lived SSE connection.
+        const heartbeat = setInterval(() => {
+            try {
+                res.write(`: heartbeat ${Date.now()}\n\n`);
+            }
+            catch { }
+        }, 20_000);
+        const cleanup = () => {
+            clearInterval(heartbeat);
+            ctx.clients.delete(client);
+        };
+        req.on("close", cleanup);
+        req.on("error", cleanup);
         return;
     }
-    const filePath = resolveFilePath(rootDir, pathname);
+    const filePath = resolveFilePath(ctx.rootDir, pathname);
     if (!filePath) {
         respondJson(res, 404, { ok: false, error: `Not found: ${pathname}` });
         return;
@@ -103,10 +202,21 @@ function handleRequest(req, res, rootDir, clients, clientId) {
             respondJson(res, 404, { ok: false, error: `Missing ${path.basename(filePath)}` });
             return;
         }
-        const body = readFileSync(filePath);
-        const contentType = pathname.endsWith(".html") ? "text/html; charset=utf-8" : "application/json";
-        res.writeHead(200, { ...CORS_HEADERS, "content-type": contentType });
-        res.end(body);
+        try {
+            const body = readFileSync(filePath);
+            const stat = statSync(filePath);
+            const contentType = pathname.endsWith(".html") ? "text/html; charset=utf-8" : "application/json";
+            res.writeHead(200, {
+                ...CORS_HEADERS,
+                "content-type": contentType,
+                "cache-control": "no-store",
+                etag: `"${stat.size}-${stat.mtimeMs}"`
+            });
+            res.end(body);
+        }
+        catch (error) {
+            respondJson(res, 500, { ok: false, error: `Read failed: ${error instanceof Error ? error.message : String(error)}` });
+        }
         return;
     }
     if (method === "PUT" && pathname.endsWith("/composition.html")) {
@@ -116,27 +226,41 @@ function handleRequest(req, res, rootDir, clients, clientId) {
                 respondJson(res, 400, { ok: false, error: "Composition HTML is missing data-composition-id" });
                 return;
             }
-            mkdirSync(path.dirname(filePath), { recursive: true });
-            writeFileSync(filePath, html, "utf8");
-            respondJson(res, 200, { ok: true, bytes: html.length });
-        }).catch((error) => respondJson(res, 500, { ok: false, error: String(error) }));
+            try {
+                mkdirSync(path.dirname(filePath), { recursive: true });
+                ctx.suppressReloadFromSelfWrite(filePath);
+                writeFileSync(filePath, html, "utf8");
+                respondJson(res, 200, { ok: true, bytes: html.length });
+            }
+            catch (error) {
+                respondJson(res, 500, { ok: false, error: `Write failed: ${error instanceof Error ? error.message : String(error)}` });
+            }
+        }).catch((error) => respondJson(res, 400, { ok: false, error: String(error) }));
         return;
     }
     if (method === "PATCH" && pathname.endsWith("/composition.json")) {
         readBody(req).then((body) => {
-            const patch = JSON.parse(body.toString("utf8") || "{}");
-            const existing = existsSync(filePath) ? JSON.parse(readFileSync(filePath, "utf8") || "{}") : {};
-            const merged = { ...existing, ...patch };
-            mkdirSync(path.dirname(filePath), { recursive: true });
-            writeFileSync(filePath, JSON.stringify(merged, null, 2), "utf8");
-            respondJson(res, 200, merged);
-        }).catch((error) => respondJson(res, 500, { ok: false, error: String(error) }));
+            try {
+                const patch = JSON.parse(body.toString("utf8") || "{}");
+                const existing = existsSync(filePath) ? JSON.parse(readFileSync(filePath, "utf8") || "{}") : {};
+                const merged = { ...existing, ...patch };
+                mkdirSync(path.dirname(filePath), { recursive: true });
+                ctx.suppressReloadFromSelfWrite(filePath);
+                writeFileSync(filePath, JSON.stringify(merged, null, 2), "utf8");
+                respondJson(res, 200, merged);
+            }
+            catch (error) {
+                respondJson(res, 400, { ok: false, error: `PATCH failed: ${error instanceof Error ? error.message : String(error)}` });
+            }
+        }).catch((error) => respondJson(res, 400, { ok: false, error: String(error) }));
         return;
     }
     respondJson(res, 405, { ok: false, error: `Method ${method} not allowed on ${pathname}` });
 }
 // Restrict served paths to the working/version composition files. Anything
-// else 404s so this server isn't a random static host.
+// else 404s so this server isn't a random static host. Also canonicalise the
+// resolved path so `..` segments cannot escape rootDir even through a future
+// refactor of the allowlist.
 function resolveFilePath(rootDir, pathname) {
     const clean = pathname.replace(/^\/+/, "");
     const parts = clean.split("/").filter(Boolean);
@@ -146,13 +270,22 @@ function resolveFilePath(rootDir, pathname) {
     const allowed = ["composition.html", "composition.json", "manifest.json"];
     if (!allowed.includes(filename))
         return null;
+    let candidate;
     // Allow: `composition.html`, `versions/1/composition.html`.
     if (parts.length === 1)
-        return path.join(rootDir, filename);
-    if (parts.length === 3 && parts[0] === "versions" && /^\d+$/.test(parts[1])) {
-        return path.join(rootDir, "versions", parts[1], filename);
+        candidate = path.join(rootDir, filename);
+    else if (parts.length === 3 && parts[0] === "versions" && /^\d+$/.test(parts[1])) {
+        candidate = path.join(rootDir, "versions", parts[1], filename);
     }
-    return null;
+    else {
+        return null;
+    }
+    const resolved = path.resolve(candidate);
+    const rootResolved = path.resolve(rootDir);
+    const rel = path.relative(rootResolved, resolved);
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return null;
+    return resolved;
 }
 function respondJson(res, status, body) {
     res.writeHead(status, { ...CORS_HEADERS, "content-type": "application/json" });
@@ -161,9 +294,36 @@ function respondJson(res, status, body) {
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        req.on("data", (chunk) => chunks.push(chunk));
-        req.on("end", () => resolve(Buffer.concat(chunks)));
-        req.on("error", reject);
+        let total = 0;
+        let settled = false;
+        // Guard against a slow client stringing the connection open forever.
+        const timeout = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            req.destroy();
+            reject(new Error("Request body read timed out after 15s."));
+        }, 15_000);
+        const done = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            fn();
+        };
+        req.on("data", (chunk) => {
+            if (settled)
+                return;
+            total += chunk.length;
+            if (total > MAX_REQUEST_BODY_BYTES) {
+                done(() => reject(new Error(`Request body exceeds ${MAX_REQUEST_BODY_BYTES} bytes.`)));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => done(() => resolve(Buffer.concat(chunks))));
+        req.on("error", (error) => done(() => reject(error)));
     });
 }
 //# sourceMappingURL=dev-serve.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mevdragon/vidfarm-devcli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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": {