@viralspin/mcp 0.2.0 → 0.4.0

package/dist/tools/local-index.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchLocalIndexTool = exports.syncLocalIndexTool = void 0;
+/**
+ * sync_local_index / search_local_index — make the user's LOCAL footage count in
+ * cloud idea-planning. sync_local_index analyzes a folder on the GPU (free when
+ * local mode is on) and pushes TAGS ONLY to the cloud catalog (files stay local);
+ * search_local_index finds existing local clips that fit a script/idea so Claude
+ * can recommend reusing them instead of filming new B-roll.
+ */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const engine_js_1 = require("../engine.js");
+const client_js_1 = require("../client.js");
+function runIndex(folder) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(process.platform === "win32" ? "node.exe" : "node", [path_1.default.join(engine_js_1.ENGINE_DIR, "index-folder.mjs"), folder], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env } });
+        let out = "";
+        child.stdout.on("data", (d) => { out += d.toString(); });
+        child.stderr.on("data", (d) => process.stderr.write(d));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const m = out.match(/RESULT:([\s\S]+)/);
+            if (code === 0 && m)
+                resolve(m[1].trim());
+            else
+                reject(new Error(out.slice(-400) || `index exited ${code}`));
+        });
+    });
+}
+exports.syncLocalIndexTool = {
+    name: "sync_local_index",
+    description: "Analyze a LOCAL folder of footage (free on the user's GPU when local mode is on) and SYNC the tags to the " +
+        "cloud so it's searchable when planning ideas / asset-plans — WITHOUT uploading the files (tags + paths only; " +
+        "media stays local until actually used). Run this once on the user's B-roll folders so search_local_index and " +
+        "idea planning know what they already have.",
+    inputSchema: {
+        type: "object",
+        properties: { folder: { type: "string", description: "Local folder of footage to index + sync." } },
+        required: ["folder"],
+    },
+    async execute(args) {
+        if (!(0, engine_js_1.engineAvailable)("index-folder.mjs")) {
+            return "sync_local_index needs the local engine (ffmpeg + the vision model). Unavailable in this install.";
+        }
+        let r;
+        try {
+            r = JSON.parse(await runIndex(args.folder));
+        }
+        catch (e) {
+            return `Couldn't index the folder: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        if (!r.items.length)
+            return `No media analyzed in ${args.folder}.`;
+        try {
+            const res = await (0, client_js_1.post)("/v1/library/local-sync", { items: r.items });
+            return (`Indexed + synced ${res.synced} local asset(s) from ${args.folder} → searchable in cloud idea-planning. ` +
+                `The files were NOT uploaded (tags only). Use search_local_index to find them by topic when planning a reel.`);
+        }
+        catch (e) {
+            return `Analyzed ${r.indexed} asset(s) but couldn't sync to the cloud: ${e instanceof Error ? e.message : String(e)}`;
+        }
+    },
+};
+exports.searchLocalIndexTool = {
+    name: "search_local_index",
+    description: "Search the user's SYNCED local footage by topic/keyword (from sync_local_index) — use when planning an idea's " +
+        "asset plan to find existing local clips that fit a script BEFORE recommending they film or AI-generate new B-roll.",
+    inputSchema: {
+        type: "object",
+        properties: { query: { type: "string", description: "Topic / keyword (e.g. 'hospital', 'sunset rooftop', 'laptop typing')." } },
+        required: ["query"],
+    },
+    async execute(args) {
+        const r = await (0, client_js_1.get)(`/v1/library/local-search?q=${encodeURIComponent(args.query)}`);
+        if (!r.items.length)
+            return `No synced local footage matched "${args.query}". (Run sync_local_index on the user's folders first, or recommend filming / AI B-roll.)`;
+        const lines = r.items.map((i) => `- ${i.path}${i.subject ? ` (${i.subject})` : ""}${i.descr ? ` — ${i.descr}` : ""}`);
+        return [`Local footage matching "${args.query}":`, ...lines].join("\n");
+    },
+};

package/dist/tools/local-mode.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLocalModeTool = void 0;
+/**
+ * set_local_mode — a persistent toggle between LOCAL analysis (free + private,
+ * a vision model on the user's GPU via Ollama) and CLOUD (Gemini). The choice is
+ * saved to ~/.viralspin/config.json, which the engine reads — so the user flips
+ * it once with no env vars to edit. (The VIRALSPIN_VLM env var still works as an
+ * explicit override.) Enabling local also verifies Ollama + the model are ready
+ * and, if not, returns the one-time setup steps.
+ */
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const CONFIG = path_1.default.join(os_1.default.homedir(), ".viralspin", "config.json");
+function readCfg() {
+    try {
+        return JSON.parse(fs_1.default.readFileSync(CONFIG, "utf8")) || {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeCfg(c) {
+    try {
+        fs_1.default.mkdirSync(path_1.default.dirname(CONFIG), { recursive: true });
+    }
+    catch { /* ignore */ }
+    fs_1.default.writeFileSync(CONFIG, JSON.stringify(c, null, 2));
+}
+async function ollamaStatus(model) {
+    try {
+        const r = await fetch("http://localhost:11434/api/tags");
+        if (!r.ok)
+            return { up: false, hasModel: false };
+        const d = (await r.json());
+        const base = model.split(":")[0];
+        const hasModel = (d.models || []).some((m) => m.name === model || m.name.startsWith(base));
+        return { up: true, hasModel };
+    }
+    catch {
+        return { up: false, hasModel: false };
+    }
+}
+exports.setLocalModeTool = {
+    name: "set_local_mode",
+    description: "Toggle ViralSpin video analysis between LOCAL (free + private — runs a vision model on the user's GPU via " +
+        "Ollama) and CLOUD (Gemini). The choice persists in ~/.viralspin/config.json — no env vars to edit, no restart. " +
+        "Enabling local verifies Ollama + the model and, if missing, returns the one-time setup steps.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            enabled: { type: "boolean", description: "true = LOCAL (GPU/Ollama), false = CLOUD (Gemini)." },
+            model: { type: "string", description: "Optional Ollama vision model (default qwen2.5vl:7b)." },
+        },
+        required: ["enabled"],
+    },
+    async execute(args) {
+        const cfg = readCfg();
+        if (!args.enabled) {
+            cfg.vlm = "cloud";
+            writeCfg(cfg);
+            return "Switched to CLOUD analysis (Gemini). Local mode is OFF.";
+        }
+        const model = args.model || cfg.ollama_model || "qwen2.5vl:7b";
+        cfg.vlm = "ollama";
+        cfg.ollama_model = model;
+        writeCfg(cfg);
+        const { up, hasModel } = await ollamaStatus(model);
+        if (!up) {
+            return (`Local mode is ON in settings, but Ollama isn't running. One-time setup:\n` +
+                `  1) Install Ollama → https://ollama.com/download (or: winget install Ollama.Ollama / brew install ollama)\n` +
+                `  2) ollama pull ${model}   (~6GB, one-time)\n` +
+                `Once Ollama is running with the model, local analysis works automatically — no restart.`);
+        }
+        if (!hasModel) {
+            return `Local mode is ON and Ollama is running, but the model isn't pulled. Run:  ollama pull ${model}  (~6GB, one-time). Then it's ready.`;
+        }
+        return `Local mode is ON ✓ — video analysis now runs on your GPU via Ollama (${model}): free + private. Say "switch to cloud" to use Gemini instead.`;
+    },
+};

package/dist/tools/profile.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCreatorProfileTool = exports.setCreatorProfileTool = void 0;
+/**
+ * set_creator_profile / get_creator_profile — the user's niche + social handles +
+ * topics, so the weekly idea routine knows their context. Capture it at setup
+ * (ask the user, or read their connected accounts via list_connections), and the
+ * weekly routine reads it to research what's working in their niche.
+ */
+const client_js_1 = require("../client.js");
+exports.setCreatorProfileTool = {
+    name: "set_creator_profile",
+    description: "Save the user's creator profile — their NICHE, social HANDLES (instagram/tiktok/youtube), and core TOPICS — " +
+        "so the weekly idea routine can research WHAT'S CURRENTLY GOING VIRAL in their niche (trending formats, hooks, " +
+        "and 5-7s caption reels — queue_idea format 'reel_7s') and model that week's ideas on proven winners. Capture " +
+        "this at setup: ask the user, or infer handles from list_connections. Call get_creator_profile first.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            niche: { type: "string", description: "The user's niche / what their content is about (e.g. 'AI tech for founders')." },
+            handles: {
+                type: "object",
+                description: "Their social handles: { instagram, tiktok, youtube }.",
+                properties: { instagram: { type: "string" }, tiktok: { type: "string" }, youtube: { type: "string" } },
+            },
+            topics: { type: "array", items: { type: "string" }, description: "Core content pillars / recurring topics." },
+            weekly_routine: { type: "boolean", description: "Whether the weekly 5-ideas routine is on for them." },
+        },
+    },
+    async execute(args) {
+        await (0, client_js_1.post)("/v1/spin/profile", args);
+        return `Saved the creator profile${args.niche ? ` (niche: ${args.niche})` : ""}. The weekly idea routine will research this niche + their accounts.`;
+    },
+};
+exports.getCreatorProfileTool = {
+    name: "get_creator_profile",
+    description: "Read the user's saved creator profile (niche, handles, topics, whether the weekly routine is on). Use at the " +
+        "start of a brainstorming or weekly-idea session so you target their actual niche/accounts. If it's empty, ask " +
+        "the user for their niche + handles (or read list_connections) and set_creator_profile.",
+    inputSchema: { type: "object", properties: {} },
+    async execute() {
+        const r = await (0, client_js_1.get)("/v1/spin/profile");
+        if (!r.profile || (!r.profile.niche && !r.profile.handles)) {
+            return "No creator profile set yet. Ask the user for their niche + social handles (or read list_connections), then set_creator_profile.";
+        }
+        const p = r.profile;
+        const handles = p.handles ? Object.entries(p.handles).filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join(", ") : "";
+        return [
+            `Creator profile:`,
+            `- niche: ${p.niche || "(not set)"}`,
+            handles ? `- handles: ${handles}` : `- handles: (none)`,
+            p.topics?.length ? `- topics: ${p.topics.join(", ")}` : "",
+            `- weekly routine: ${p.weekly_routine ? "on" : "off"}`,
+        ].filter(Boolean).join("\n");
+    },
+};

package/dist/tools/publish.js

@@ -38,18 +38,35 @@ function expandPaths(inputs) {
     }
     return result;
 }
+/** A deck rarely posts the same way everywhere. Say so, or the caller reads
+ *  "Published to: tiktok" and assumes the slides went out as prepared. */
+function noticeLines(notices) {
+    if (!notices?.length)
+        return "";
+    return `\nNote — this deck does not post the same way everywhere:\n` +
+        notices.map((n) => `- ${n.headline}. ${n.detail}`).join("\n");
+}
 const publishSchema = {
     type: "object",
     properties: {
         paths: {
             type: "array",
             items: { type: "string" },
-            description: "Local file path(s) or a folder path. Single video → video post. Multiple images or image folder → carousel.",
+            description: "Local file path(s) or a folder path. Single video → video post. Multiple files → carousel. " +
+                "A video slide is fine for Instagram, but TikTok has no mixed carousel — it stays a carousel there " +
+                "and each video slide publishes as a still. YouTube takes slide 1 only, LinkedIn stills only.",
         },
         platforms: {
             type: "array",
-            items: { type: "string", enum: ["tiktok", "instagram", "youtube"] },
-            description: "Platforms to publish to. Must be connected.",
+            items: { type: "string", enum: ["tiktok", "instagram", "youtube", "linkedin"] },
+            description: "Platforms to publish to (uses the first connected account per platform). Omit when using account_ids.",
+        },
+        account_ids: {
+            type: "array",
+            items: { type: "string" },
+            description: "Specific connection IDs to publish to. Use list_connections to get IDs. " +
+                "Required when you have multiple accounts on the same platform and want to target a specific one. " +
+                "Takes precedence over 'platforms' when both are provided.",
         },
         caption: { type: "string", description: "Post caption." },
         hashtags: {
@@ -58,13 +75,18 @@ const publishSchema = {
             description: "Hashtags without # prefix.",
         },
     },
-    required: ["paths", "platforms", "caption"],
+    required: ["paths", "caption"],
 };
 exports.publishNowTool = {
     name: "publish_now",
-    description: "Upload local file(s) and publish immediately to TikTok, Instagram, and/or YouTube. Pass a folder path to publish all images in it as a carousel.",
+    description: "Upload local file(s) and publish immediately to TikTok, Instagram, and/or YouTube. " +
+        "Pass a folder path to publish all images in it as a carousel. " +
+        "Use account_ids (from list_connections) to target a specific account when you have multiple accounts on the same platform.",
     inputSchema: publishSchema,
     async execute(args) {
+        if (!args.platforms?.length && !args.account_ids?.length) {
+            throw new Error("Provide 'platforms' (e.g. [\"instagram\"]) or 'account_ids' from list_connections.");
+        }
         const filePaths = expandPaths(args.paths);
         if (!filePaths.length)
             throw new Error("No media files found in the provided paths.");
@@ -79,7 +101,8 @@ exports.publishNowTool = {
             result = await (0, client_js_1.post)("/v1/publish/schedule", {
                 media_urls: urls,
                 media_type: mediaType,
-                platforms: args.platforms,
+                platforms: args.platforms ?? [],
+                ...(args.account_ids?.length ? { connection_ids: args.account_ids } : {}),
                 caption: args.caption,
                 hashtags: args.hashtags ?? [],
                 publish_now: true,
@@ -96,7 +119,7 @@ exports.publishNowTool = {
             summary += `Published to: ${published.join(", ")}\n`;
         if (failed_reason)
             summary += `Errors: ${failed_reason}`;
-        return summary.trim();
+        return (summary.trim() + noticeLines(result.notices)).trim();
     },
 };
 exports.sendToDraftsTool = {
@@ -130,6 +153,9 @@ exports.sendToDraftsTool = {
         required: ["paths", "platforms", "caption"],
     },
     async execute(args) {
+        if (!args.platforms?.length && !args.account_ids?.length) {
+            throw new Error("Provide 'platforms' (e.g. [\"tiktok\"]) or 'account_ids' from list_connections.");
+        }
         const filePaths = expandPaths(args.paths);
         if (!filePaths.length)
             throw new Error("No media files found in the provided paths.");
@@ -138,7 +164,7 @@ exports.sendToDraftsTool = {
             throw new Error(`Carousel max is 10 images. Found ${filePaths.length} files.`);
         }
         // Surface the IG-not-supported gotcha before consuming credits / uploading.
-        if (args.platforms.includes("instagram")) {
+        if (args.platforms?.includes("instagram")) {
             throw new Error("Instagram does not support drafts via API. IG drafts are local to the mobile app only — " +
                 "there is no API endpoint to send to drafts. Remove 'instagram' from platforms, or use schedule_post / publish_now instead.");
         }
@@ -148,7 +174,8 @@ exports.sendToDraftsTool = {
             result = await (0, client_js_1.post)("/v1/publish/schedule", {
                 media_urls: urls,
                 media_type: mediaType,
-                platforms: args.platforms,
+                platforms: args.platforms ?? [],
+                ...(args.account_ids?.length ? { connection_ids: args.account_ids } : {}),
                 caption: args.caption,
                 hashtags: args.hashtags ?? [],
                 publish_now: true,
@@ -167,12 +194,13 @@ exports.sendToDraftsTool = {
         }
         if (failed_reason)
             summary += `\nErrors: ${failed_reason}`;
-        return summary.trim();
+        return (summary.trim() + noticeLines(result.notices)).trim();
     },
 };
 exports.schedulePostTool = {
     name: "schedule_post",
-    description: "Upload local file(s) and schedule a post for a future time. Pass a folder path to schedule all images as a carousel.",
+    description: "Upload local file(s) and schedule a post for a future time. Pass a folder path to schedule all images as a carousel. " +
+        "TikTok has no mixed carousel, so a video slide publishes there as a still — the return value says so, and the frame is pickable in the app.",
     inputSchema: {
         type: "object",
         properties: {
@@ -186,9 +214,12 @@ exports.schedulePostTool = {
                 description: "IANA timezone name (e.g. 'America/New_York'). Defaults to UTC.",
             },
         },
-        required: ["paths", "platforms", "caption", "scheduled_time"],
+        required: ["paths", "caption", "scheduled_time"],
     },
     async execute(args) {
+        if (!args.platforms?.length && !args.account_ids?.length) {
+            throw new Error("Provide 'platforms' (e.g. [\"instagram\"]) or 'account_ids' from list_connections.");
+        }
         const filePaths = expandPaths(args.paths);
         if (!filePaths.length)
             throw new Error("No media files found in the provided paths.");
@@ -199,7 +230,8 @@ exports.schedulePostTool = {
         const result = await (0, client_js_1.post)("/v1/publish/schedule", {
             media_urls: urls,
             media_type: mediaType,
-            platforms: args.platforms,
+            platforms: args.platforms ?? [],
+            ...(args.account_ids?.length ? { connection_ids: args.account_ids } : {}),
             caption: args.caption,
             hashtags: args.hashtags ?? [],
             scheduled_time: args.scheduled_time,
@@ -209,7 +241,11 @@ exports.schedulePostTool = {
         // Note: storage_paths are NOT deleted here — the cron job needs the URLs to stay valid.
         // They expire after 1 hour. For posts scheduled further out, re-upload closer to publish time.
         void storage_paths;
+        const targets = args.account_ids?.length
+            ? `account IDs: ${args.account_ids.join(", ")}`
+            : (args.platforms ?? []).join(", ");
         const { post: p } = result;
-        return `Scheduled post ${p.id}\nPlatforms: ${args.platforms.join(", ")}\nTime: ${args.scheduled_time}\nStatus: ${p.status}`;
+        return `Scheduled post ${p.id}\nTargets: ${targets}\nTime: ${args.scheduled_time}\nStatus: ${p.status}` +
+            noticeLines(result.notices);
     },
 };

package/dist/tools/relight-clip.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.relightClipTool = void 0;
+/**
+ * relight_clip — relight / re-scene a SHORT clip (3–10s) via Fal.ai (bundled
+ * relight.py: nano-banana-2 relights one frame, Kling O3 Pro transfers it onto
+ * the clip with audio preserved). PAID, so it's two-phase with a cost gate:
+ *   phase 1 (no confirm): prep + relight ONE frame (~$0.10) → preview + the video
+ *     cost estimate + the folder.
+ *   phase 2 (confirm + folder): run the paid Kling video step.
+ * Needs FAL_KEY in the environment. Best on B-roll / short hero shots — a full
+ * talking-head monologue can drift on the mouth.
+ */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const engine_js_1 = require("../engine.js");
+function pythonBin() { return process.platform === "win32" ? "python" : "python3"; }
+function runRelight(args) {
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(pythonBin(), [path_1.default.join(engine_js_1.ENGINE_DIR, "relight.py"), ...args], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env } });
+        let out = "";
+        let err = "";
+        child.stdout.on("data", (d) => { out += d.toString(); });
+        child.stderr.on("data", (d) => { err += d.toString(); process.stderr.write(d); });
+        child.on("error", reject);
+        child.on("close", (code) => (code === 0 ? resolve(out.trim()) : reject(new Error(err.slice(-300) || out.slice(-300) || `relight exited ${code}`))));
+    });
+}
+function lastJson(s) {
+    const m = s.match(/\{[\s\S]*\}\s*$/);
+    return JSON.parse(m ? m[0] : s);
+}
+exports.relightClipTool = {
+    name: "relight_clip",
+    description: "Relight or re-scene a SHORT clip (3–10s — best on B-roll / short hero shots) via Fal.ai: change the lighting " +
+        "or drop the subject into a new environment, audio preserved. PAID (~$0.10 for the reference frame + ~$0.168/sec " +
+        "for the video). COST-GATED two-step: call WITHOUT confirm → it preps + relights ONE frame and returns a preview " +
+        "+ the video cost + a `folder`; review it, show the user the cost, then call again WITH confirm:true and that " +
+        "`folder` to run the paid video step. Write a geometry-locked, LIGHTING-focused scene_prompt (same framing/pose; " +
+        "change only lighting + background). Needs FAL_KEY in the environment. For a free non-AI color look, use color_grade.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            video_path: { type: "string", description: "Local path to a 3–10s clip." },
+            scene_prompt: { type: "string", description: "Relight/re-scene prompt — keep the EXACT framing/pose; change only lighting + background (e.g. 'hard key from high front-left, deep shadow on the other side, warm rim; soft golden-hour rooftop bokeh behind him')." },
+            reference_image: { type: "string", description: "Optional reference image of the scene/lighting to match." },
+            confirm: { type: "boolean", description: "true = run the PAID video step (only after the user approved the preview + cost)." },
+            folder: { type: "string", description: "The `folder` returned by the first (no-confirm) call — required with confirm:true." },
+            model: { type: "string", enum: ["o3", "o1"], description: "o3 (default, best lip-sync) or o1 (cheaper/faster draft)." },
+        },
+        required: ["video_path", "scene_prompt"],
+    },
+    async execute(args) {
+        if (!process.env.FAL_KEY) {
+            return "relight_clip needs FAL_KEY in the environment. Set it (Windows: setx FAL_KEY \"<key>\") and restart, then try again.";
+        }
+        // Phase 2 — the PAID video transfer.
+        if (args.confirm) {
+            if (!args.folder)
+                return "To run the paid video step, pass the `folder` returned by the first call.";
+            try {
+                const res = lastJson(await runRelight(["video", "--folder", args.folder, ...(args.model ? ["--model", args.model] : [])]));
+                return `Relit clip rendered (audio preserved): ${res.video_path}\nSwap it into your project, or publish it.`;
+            }
+            catch (e) {
+                return `Relight video step failed: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        // Phase 1 — prep + relight ONE frame (cheap), then quote the video cost.
+        let prep;
+        try {
+            prep = lastJson(await runRelight(["prep", "--video", args.video_path, "--title", "relight"]));
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return /3.?10|second|duration/i.test(msg) ? `That clip is outside the 3–10s limit — trim to a ≤10s segment first. (${msg})` : `Couldn't prep the clip: ${msg}`;
+        }
+        try {
+            await runRelight(["image", "--frame", prep.frame_path, "--folder", prep.folder, "--aspect-ratio", String(prep.aspect_ratio), "--prompt", args.scene_prompt, ...(args.reference_image ? ["--reference", args.reference_image] : [])]);
+        }
+        catch (e) {
+            return `Couldn't relight the reference frame: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        const sec = Number(prep.duration) || 0;
+        const perSec = args.model === "o1" ? 0.168 : 0.168;
+        const cost = (0.1 + sec * perSec).toFixed(2);
+        return [
+            `Relit a reference frame ✓ — preview in: ${prep.folder}`,
+            ``,
+            `The PAID video step transfers that look onto the whole ${sec}s clip (audio kept) ≈ $${cost}.`,
+            `Show this cost to the user. To run it, call:`,
+            `  relight_clip(video_path: "${args.video_path}", scene_prompt: "…", confirm: true, folder: "${prep.folder}")`,
+        ].join("\n");
+    },
+};

package/dist/tools/render-locally.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderLocallyStatusTool = exports.renderLocallyTool = void 0;
+exports.tm = tm;
+const client_js_1 = require("../client.js");
+const tokens_js_1 = require("../local-render/tokens.js");
+const render_js_1 = require("../local-render/render.js");
+const login_js_1 = require("../local-render/login.js");
+const jobs = new Map();
+let tokens = null;
+function tm() {
+    if (!tokens) {
+        // Nothing to sign in with (first time, or the 30-day refresh ran out): open the browser and let the person approve. No pasted tokens.
+        const interactive = process.env.VIRALSPIN_NO_BROWSER_LOGIN !== "1";
+        tokens = new tokens_js_1.TokenManager({
+            apiBase: client_js_1.PY_API_URL,
+            signIn: interactive ? async () => { await (0, login_js_1.login)({ apiBase: client_js_1.PY_API_URL, log: (l) => process.stderr.write(`[render_locally] ${l}\n`) }); } : undefined,
+        });
+    }
+    return tokens;
+}
+/** "Which reel?" with no arguments: the newest one the app sent to this person's computer and nobody has taken yet. */
+async function discover(log) {
+    const jobs = await (0, render_js_1.listPendingJobs)({ apiBase: client_js_1.PY_API_URL, tokens: tm() });
+    const { job, others, busy } = (0, render_js_1.pickJob)(jobs);
+    if (!job) {
+        if (busy.length) {
+            return { job: null, message: `Your reel "${busy[0].title || busy[0].job_id.slice(0, 8)}" is already being drawn on a computer (sent ${(0, render_js_1.ago)(busy[0].created_at)}). ` +
+                    `If that is this computer, call render_locally_status; to draw it again here, pass job_id "${busy[0].job_id}".` };
+        }
+        return { job: null, message: "There is no reel waiting for your computer. In the ViralSpin app, open a reel's style picker, choose \"On my computer\" and tap \"Send to my computer\" - then say \"Render my ViralSpin reel\" again." };
+    }
+    const name = job.title ? `"${job.title}"` : `job ${job.job_id.slice(0, 8)}`;
+    log(`[pick] your newest waiting reel: ${name}${job.duration_sec ? `, ${Math.round(Number(job.duration_sec))} s` : ""}, sent ${(0, render_js_1.ago)(job.created_at)}` +
+        (job.phase === "planning" ? " (ViralSpin is still preparing it - waiting for that)" : "") +
+        (others.length ? `; ${others.length} older one${others.length > 1 ? "s" : ""} also waiting - ask again afterwards to render the next` : ""));
+    return { job };
+}
+function tail(lines, n = 14) {
+    return lines.slice(-n).join("\n");
+}
+function report(r, lines) {
+    const head = r.dry_run
+        ? `Dry run OK - everything except the draw works on this computer (job ${r.job_id}).`
+        : `Rendered on this computer: ${r.output_path}`;
+    return [
+        head,
+        r.timing_path ? `timing: ${r.timing_path}` : "",
+        r.timing ? `draw ${r.timing.drawSeconds}s + mux ${r.timing.muxSeconds}s, ${r.timing.frames} frames, concurrency ${r.timing.concurrency}, ${r.timing.cores} threads, ${r.timing.ramGB} GB RAM, file ${r.timing.fileBytes} bytes` : "",
+        `prep: toolkit ${r.seconds.kit}s, plan ${r.seconds.plan}s, media ${r.seconds.download}s (${r.media.downloaded} downloaded, ${r.media.cached} cached); total ${r.seconds.total}s`,
+        r.completed ? (r.output_url ? "Done. The finished reel is in your ViralSpin app now (0 credits)." : "Reported back to ViralSpin (0 credits).") : "",
+        "",
+        "last log lines:",
+        tail(lines),
+        "",
+        JSON.stringify(r),
+    ].filter((x) => x !== "").join("\n");
+}
+exports.renderLocallyTool = {
+    name: "render_locally",
+    description: "Render a ViralSpin REEL on THIS computer (Mac or Windows) instead of the cloud: ViralSpin plans the reel and hands over the media, " +
+        "this machine does the Remotion draw and the audio mix, and the finished mp4 stays on disk (nothing is published or uploaded; 0 credits). " +
+        "First use downloads a ~0.5 GB render kit into ~/.viralspin/kit (needs Node 20+ and 8 GB free disk); later runs reuse it. " +
+        "WITH NO ARGUMENTS it renders the newest reel the person sent to their computer from the ViralSpin app (it says which one it picked); " +
+        "the first time it opens the browser once so they can approve ViralSpin (no tokens to paste). The finished reel is uploaded back so it appears in the app. " +
+        "Or give a job_id, a render_id (a reel the app already planned) or a reel request {plan, aroll_url}. dry_run:true does everything except the draw, to check the setup. " +
+        "A real run takes minutes; pass background:true to return at once and poll with render_locally_status.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            job_id: { type: "string", description: "A job the app sent to this computer. Leave out to take the newest waiting one." },
+            upload: { type: "boolean", description: "Upload the finished mp4 so it appears in the app. Default true for app jobs." },
+            render_id: { type: "string", description: "A reel ViralSpin already planned (its render_id)." },
+            request: {
+                type: "object",
+                description: "OR the same body as POST /v1/reel/renders: { plan, aroll_url, style?, style_source? }.",
+                properties: { plan: { type: "object" }, aroll_url: { type: "string" }, style: { type: "string" }, style_source: { type: "object" } },
+                required: ["plan", "aroll_url"],
+            },
+            concurrency: { type: "number", description: `Frames drawn in parallel. Default min(4, cores/2) = ${(0, render_js_1.defaultConcurrency)()} here; 6+ was measured slower.` },
+            dry_run: { type: "boolean", description: "Install/update the kit, prepare the reel, download media, start the draw stack - then stop before drawing." },
+            complete: { type: "boolean", description: "After the draw, tell ViralSpin it finished (status + timing). Nothing is uploaded. Default false." },
+            background: { type: "boolean", description: "Return immediately with a job id; check progress with render_locally_status." },
+        },
+    },
+    async execute(args = {}, onProgress) {
+        const lines = [];
+        const log = (l) => {
+            lines.push(l);
+            process.stderr.write(`[render_locally] ${l}\n`);
+            onProgress?.(l);
+        };
+        // An app job (picked or named by job_id) is reported back and uploaded by default: the app is waiting for it.
+        let job_id = args.job_id;
+        const explicit = Boolean(args.render_id || args.request);
+        if (!job_id && !explicit) {
+            const found = await discover(log);
+            if (!found.job)
+                return found.message;
+            job_id = found.job.job_id;
+        }
+        const appJob = Boolean(job_id);
+        const run = () => (0, render_js_1.renderLocally)({
+            apiBase: client_js_1.PY_API_URL, tokens: tm(), render_id: args.render_id, request: args.request, job_id,
+            concurrency: args.concurrency, dryRun: args.dry_run, complete: args.complete ?? (appJob && !args.dry_run),
+            upload: args.upload, log,
+        });
+        if (args.background) {
+            const id = `bg-${Date.now().toString(36)}`;
+            const job = { state: "running", lines, started: Date.now() };
+            jobs.set(id, job);
+            run().then((r) => { job.state = "done"; job.result = r; }).catch((e) => { job.state = "failed"; job.error = String(e?.message || e); });
+            return `Started in the background: ${id}. Call render_locally_status with job_id "${id}" to follow it.`;
+        }
+        const r = await run();
+        return report(r, lines);
+    },
+};
+exports.renderLocallyStatusTool = {
+    name: "render_locally_status",
+    description: "Progress of a render_locally job started with background:true. With no job_id: your reels waiting for / being drawn on a computer, from ViralSpin.",
+    inputSchema: {
+        type: "object",
+        properties: { job_id: { type: "string" } },
+    },
+    async execute(args = {}) {
+        if (args.job_id) {
+            const j = jobs.get(args.job_id);
+            if (j) {
+                const secs = Math.round((Date.now() - j.started) / 1000);
+                if (j.state === "running")
+                    return `running (${secs}s)\n${tail(j.lines)}`;
+                if (j.state === "failed")
+                    return `failed after ${secs}s: ${j.error}\n${tail(j.lines)}`;
+                return report(j.result, j.lines);
+            }
+            // not a background handle of this process: it may be an app job id
+            const v = await tm().request("GET", `${client_js_1.PY_API_URL}/v1/reel/local-jobs/${encodeURIComponent(args.job_id)}`).catch(() => null);
+            if (!v)
+                return `No such local render job: ${args.job_id}`;
+            return describeJob(v);
+        }
+        const running = [...jobs.entries()].filter(([, j]) => j.state === "running");
+        const lines = running.map(([id, j]) => `${id}: running here (${Math.round((Date.now() - j.started) / 1000)}s)\n${tail(j.lines, 4)}`);
+        const pending = await (0, render_js_1.listPendingJobs)({ apiBase: client_js_1.PY_API_URL, tokens: tm() });
+        for (const p of pending)
+            lines.push(describeJob(p));
+        return lines.length ? lines.join("\n\n") : "Nothing is waiting or rendering. Send a reel from the ViralSpin app (style picker > On my computer > Send to my computer).";
+    },
+};
+function describeJob(v) {
+    const name = v.title ? `"${v.title}"` : v.job_id.slice(0, 8);
+    const says = {
+        planning: "ViralSpin is preparing it", waiting: "ready, waiting for your computer", rendering: "being drawn on a computer",
+        done: "finished - it is in the app", failed: `failed: ${v.error_message || "no reason given"}`, cancelled: "cancelled",
+    };
+    return `${name} (${v.job_id}): ${says[v.phase ?? ""] ?? v.status}, sent ${(0, render_js_1.ago)(v.created_at)}`;
+}