@viralspin/mcp 0.1.0 → 0.3.1

package/dist/tools/find-moments.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findMomentsTool = void 0;
+/**
+ * find_moments — surface highlight windows inside a long/silent local video so
+ * the agent can build a reel without the user pre-splitting it. Shells out to the
+ * engine's moments.mjs (ffmpeg frame sampling + vision scoring via the configured
+ * model — local Ollama when VIRALSPIN_VLM is set, else cloud Gemini).
+ */
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const engine_js_1 = require("../engine.js");
+function runMoments(args, script = "moments.mjs") {
+    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, script), ...args], {
+            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) || `moments engine exited ${code}`));
+        });
+    });
+}
+exports.findMomentsTool = {
+    name: "find_moments",
+    description: "Find the highlight-worthy moments INSIDE a long or silent LOCAL video (e.g. a screen recording or B-roll " +
+        "reel) — no need to split it first. Samples frames and scores them with the configured vision model " +
+        "(free + private local Ollama when local mode is on, else cloud), and returns 0.6–3s windows with " +
+        "descriptions. Pass `query` to bias toward a theme. Set `extract: true` to ALSO cut each highlight into " +
+        "its own small clip LOCALLY — then you upload only those snippets (not the long source). Build a reel from " +
+        "them with create_video_assembly: destination:'hosted' uploads ONLY the snippets + opens the web editor; " +
+        "destination:'local' keeps everything on-device (no upload). Same analysis, two destinations.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            video_path: { type: "string", description: "Local path to the long video to scan." },
+            query: { type: "string", description: "Optional theme to bias toward (e.g. 'surprise reveal', 'on-screen editing')." },
+            threshold: { type: "number", description: "Score cutoff 0..1 for a 'highlight' (default 0.55; lower = more windows)." },
+            extract: { type: "boolean", description: "Also cut each highlight into its own small clip locally (so you upload only the snippets). Default false = just list the windows." },
+            mode: { type: "string", enum: ["highlight", "screen"], description: "'highlight' (default) = VLM-scored striking moments for any footage. 'screen' = SCREEN-RECORDING mode: frame-diff finds where the on-screen ACTION is and returns a focal point (x,y) + suggested punch-in zoom per snippet, so the reel can auto-zoom to exactly where things happen (cursor, typing, output). Use for app/product demos." },
+        },
+        required: ["video_path"],
+    },
+    async execute(args) {
+        if (args.mode === "screen")
+            return runScreenMode(args);
+        if (!(0, engine_js_1.engineAvailable)("moments.mjs")) {
+            return "find_moments needs the local engine (it runs ffmpeg + the vision model). It's unavailable in this install — set VIRALSPIN_ASSEMBLY_DIR, or use the hosted transcript path (get_transcript + keep_windows) for talking/narrated video instead.";
+        }
+        const cli = [args.video_path];
+        if (args.query)
+            cli.push("--query", args.query);
+        if (args.threshold != null)
+            cli.push("--threshold", String(args.threshold));
+        if (args.extract)
+            cli.push("--extract");
+        let json;
+        try {
+            json = JSON.parse(await runMoments(cli));
+        }
+        catch (e) {
+            return `Couldn't scan the video: ${e instanceof Error ? e.message : String(e)}`;
+        }
+        if (!json.windows?.length) {
+            return `Scanned ${json.sampled} frames over ${Math.round(json.duration)}s but found no standout moments — lower the threshold or add a query.`;
+        }
+        const head = `Found ${json.windows.length} highlight window(s) in ${path_1.default.basename(args.video_path)} (${Math.round(json.duration)}s, ${json.sampled} frames sampled, analyzed locally if local mode is on):`;
+        if (json.clips?.length) {
+            const lines = json.clips.map((c, i) => `${i + 1}. ${c.path}  (${c.from_sec.toFixed(1)}–${c.to_sec.toFixed(1)}s)${c.desc ? ` — ${c.desc}` : ""}`);
+            return [
+                head,
+                `Extracted ${json.clips.length} clip(s) → ${json.out_dir}`,
+                ...lines,
+                ``,
+                `Build a reel from these snippets with create_video_assembly:`,
+                `  • destination:"hosted" → uploads ONLY these snippets (not the long source) + opens the web editor.`,
+                `  • destination:"local"  → keeps everything on-device, no upload (fully private).`,
+            ].join("\n");
+        }
+        const lines = json.windows.map((w, i) => `${i + 1}. ${w.from_sec.toFixed(1)}–${w.to_sec.toFixed(1)}s (score ${w.score})${w.desc ? ` — ${w.desc}` : ""}`);
+        return [
+            head,
+            ...lines,
+            ``,
+            `Re-run with extract:true to cut these into clips (then upload only those), or run keep_windows on a hosted project to cut to just these moments.`,
+        ].join("\n");
+    },
+};
+// SCREEN mode — shells to screen-moments.mjs (frame-diff focal + zoom, VLM label).
+// Returns snippets that carry focal_x/focal_y + zoom so the assembly can punch-in to
+// exactly where the on-screen action is. Each screen recording is a B-roll SOURCE;
+// call once per recording and let the story arc stitch the snippets together.
+async function runScreenMode(args) {
+    if (!(0, engine_js_1.engineAvailable)("screen-moments.mjs")) {
+        return "Screen mode needs the local engine (ffmpeg + Python opencv). It's unavailable in this install — set VIRALSPIN_ASSEMBLY_DIR and `pip install opencv-python numpy`.";
+    }
+    const cli = [args.video_path];
+    if (args.threshold != null)
+        cli.push("--threshold", String(args.threshold));
+    if (args.extract)
+        cli.push("--extract");
+    let json;
+    try {
+        json = JSON.parse(await runMoments(cli, "screen-moments.mjs"));
+    }
+    catch (e) {
+        return `Couldn't scan the screen recording: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    if (!json.snippets?.length) {
+        return `Scanned ${json.sampled} frames over ${Math.round(json.duration)}s of ${path_1.default.basename(args.video_path)} but found no clear on-screen action — the recording may be mostly static.`;
+    }
+    const head = `Found ${json.snippets.length} on-screen action moment(s) in ${path_1.default.basename(args.video_path)} (${json.width}×${json.height}, ${Math.round(json.duration)}s). Each carries a focal point + punch-in zoom so the reel can zoom to exactly where the action is:`;
+    const fmt = (s, i) => `${i + 1}. ${s.from_sec.toFixed(1)}–${s.to_sec.toFixed(1)}s — focal (${s.focal_x.toFixed(2)}, ${s.focal_y.toFixed(2)}), zoom ${s.zoom}×${s.label ? ` — “${s.label}”` : ""}`;
+    if (json.clips?.length) {
+        return [
+            head,
+            ...json.snippets.map(fmt),
+            ``,
+            `Extracted ${json.clips.length} snippet clip(s) → ${json.out_dir}`,
+            `These are B-roll candidates: build a screen-demo reel with create_video_assembly (they stitch together with other B-roll; the focal+zoom drive the auto punch-in).`,
+        ].join("\n");
+    }
+    return [
+        head,
+        ...json.snippets.map(fmt),
+        ``,
+        `Re-run with extract:true to cut these into snippet clips, then assemble a screen-demo reel from them (each snippet's focal+zoom drives the punch-in).`,
+    ].join("\n");
+}

package/dist/tools/folder-preview.js

@@ -0,0 +1,71 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.previewFolderTool = void 0;
+/**
+ * preview_folder — a pre-flight cost gate for assembling a local folder.
+ *
+ * create_video_assembly analyzes every clip (Gemini tags) and charges credits on
+ * create. For a big folder that adds up, so the agent should call this FIRST and
+ * confirm with the user before assembling. Counting is local (reads the disk),
+ * so it's instant and free; the exact credit charge is finalized server-side in
+ * the create response. An optional per-asset rate (env) gives a rough estimate.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp"]);
+const VIDEO_EXT = new Set([".mp4", ".mov", ".webm", ".m4v"]);
+exports.previewFolderTool = {
+    name: "preview_folder",
+    description: "Before assembling from a LOCAL folder, count its media so you can warn the user about cost. Each clip is " +
+        "analyzed (tagged for matching) and credits are charged when create_video_assembly runs — so for a big " +
+        "folder, call this first and CONFIRM before proceeding. Counting is instant + free; the exact charge is " +
+        "finalized in the create response. Returns video/image counts (+ a rough credit estimate if a per-asset " +
+        "rate is configured via VIRALSPIN_ANALYZE_CREDITS_PER_ASSET).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            folder: { type: "string", description: "Local folder path to inspect." },
+        },
+        required: ["folder"],
+    },
+    async execute(args) {
+        const folder = args.folder;
+        if (!fs_1.default.existsSync(folder))
+            return `Folder not found: ${folder}`;
+        let names;
+        try {
+            const st = fs_1.default.statSync(folder);
+            if (!st.isDirectory())
+                return `${folder} is a file, not a folder.`;
+            names = fs_1.default.readdirSync(folder);
+        }
+        catch (e) {
+            return `Can't read folder: ${e instanceof Error ? e.message : e}`;
+        }
+        let images = 0;
+        let videos = 0;
+        for (const n of names) {
+            const ext = path_1.default.extname(n).toLowerCase();
+            if (VIDEO_EXT.has(ext))
+                videos++;
+            else if (IMAGE_EXT.has(ext))
+                images++;
+        }
+        const total = images + videos;
+        if (!total)
+            return `No images or videos found in ${folder}.`;
+        const rate = Number(process.env.VIRALSPIN_ANALYZE_CREDITS_PER_ASSET || "");
+        const est = Number.isFinite(rate) && rate > 0 ? ` Rough estimate: ~${Math.round(total * rate)} credits (${rate}/clip).` : "";
+        const warnAt = Number(process.env.VIRALSPIN_FOLDER_WARN || "40");
+        const big = total > warnAt;
+        return (`${folder}\n` +
+            `${total} media file(s): ${videos} video(s), ${images} image(s).\n` +
+            `Each is analyzed when you assemble; credits are charged on create_video_assembly and finalized in its response.${est}\n` +
+            (big
+                ? `⚠️ Large folder — CONFIRM with the user before assembling (it will cost credits). Consider a sub-folder or only the best clips.`
+                : `Small enough to assemble directly.`));
+    },
+};

package/dist/tools/ideas.js

@@ -0,0 +1,158 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listIdeasTool = exports.queueIdeaTool = void 0;
+/**
+ * queue_idea / list_ideas — the Prompt/Idea History bridge. Claude brainstorms
+ * with the user, then queues each idea (hook + script + an asset plan) here; it
+ * persists in Supabase (via /v1/spin/ideas) and shows up in the user's web
+ * /spin/history, cross-session and cross-browser. The asset_plan tells the user
+ * what's needed to execute (existing clips, AI B-roll, web images, kinetic text,
+ * or footage to film).
+ */
+const client_js_1 = require("../client.js");
+exports.queueIdeaTool = {
+    name: "queue_idea",
+    description: "Queue a content idea into the user's persistent Prompt/Idea History (shows in their web /spin/history, " +
+        "cross-browser). Use after brainstorming or after analyzing a saved/pasted post the user wants to replicate. " +
+        "Give it a `hook`, a ready-to-film `script` (they read it off the teleprompter at /create), the `topic`, and " +
+        "an `asset_plan` — per shot, say what to use: existing clip / AI-generated B-roll / web image (logo, person) / " +
+        "kinetic text overlay / footage to film. Set `source_url` if it came from a saved post. " +
+        "For a punchy 5-7s relatable joke where the VALUE IS THE OVERLAY CAPTION (not narration) — e.g. a video of " +
+        "someone on a plane captioned 'Flight attendant: OMG is there anyone onboard who can align cross-functional " +
+        "stakeholders while navigating ambiguity?' — use format:'reel_7s' and put the line in `caption`. " +
+        "GROUND every reel_7s in what is CURRENTLY GOING VIRAL in the creator's niche: call get_creator_profile " +
+        "for their niche + handles + topics, research the caption-reel formats + in-group jokes trending in that " +
+        "niche right now (their and adjacent creators' recent hits), and adapt a PROVEN pattern to their audience — " +
+        "don't invent a random joke. When generating a WEEK's batch of ideas, include AT LEAST ONE reel_7s modeled " +
+        "on that week's viral trend in the niche (set `source_url` to the post it's modeled on when there is one). " +
+        "reel_7s ASSET PLAN — if the caption has a SETUP → PAYOFF shape (before/after, question → reaction, 'four " +
+        "hours later:'), SPLIT the asset_plan into ONE BEAT PER SEGMENT so the shoot app can guide the creator " +
+        "part-by-part; a single-line caption = a single beat. Give each segment its own overlay line QUOTED in " +
+        "`note` (e.g. note: 'Overlay: \"Four hours later:\". Same framing as segment 1 - the contrast IS the joke.'), " +
+        "its own `search_terms`, and kind:'existing' — so the app can AI-pick that segment from the creator's camera " +
+        "roll (a 7s clip OR a photo) and they can still film/overwrite it themselves. " +
+        "HOOK PATTERN — a strong attention-grab is to OPEN ON A SURPRISED REACTION, then demonstrate the payoff " +
+        "('wait, what?!' → here's the thing). For ideas that PROMOTE VIRALSPIN (which are encouraged), lead the " +
+        "asset_plan with a reaction beat: first shot kind:'film' note the creator's surprised/delighted reaction " +
+        "(e.g. 'reacts stunned to how fast the reel was made'), THEN the demonstration beats. The mobile shoot flow " +
+        "(Take → React → Show → Build) mirrors this, so a react-first plan maps cleanly to how it's executed. " +
+        "SHOT PHRASING — write each `shot` as a SHORT, PLAIN, second-person creator ACTION they can just DO, not a " +
+        "cinematic third-person screenplay direction. GOOD: 'Show/gesture a perfect prompt', 'Sift through a bunch of AI " +
+        "output and pick a few good ones', 'React impressed at the polished result'. BAD (too abstract/wordy): 'Creator " +
+        "looking thoughtful, gesturing beyond the camera to a conceptual future', 'Hands sifting through a grid of " +
+        "AI-generated text/images on a tablet, selecting a few'. If a beat is really an EMOTIONAL/impressed MOMENT (e.g. " +
+        "'confidently presenting a refined high-quality result'), make it a REACTION the creator performs to camera — an " +
+        "impressed facial reaction — NOT a staged 'show' of holding up a screen. " +
+        "TAKE vs SHOW — the creator ON CAMERA (talking, gesturing, reacting) belongs to the Take + React steps, so those " +
+        "are kind:'film'. The 'SHOW IT' beats are footage of the SUBJECT — a screen recording, a demo, product/B-roll — " +
+        "NOT the creator; make them kind:'existing' (a clip the user records/provides) or kind:'ai_broll', and describe " +
+        "WHAT'S ON SCREEN, not the person. NEVER write a show/demo beat as 'creator looking thoughtful' or 'creator " +
+        "pointing at a screen' — that's a talking-head (Take). E.g. a demo beat = existing 'Screen-record the bad-vs-good " +
+        "prompt output', not film 'Creator points to the screen'. " +
+        "NO REDUNDANT TAKE BEATS — the creator reads the WHOLE script off the teleprompter in step 1, so NEVER add a " +
+        "kind:'film' beat that is just 'talk/gesture to camera as you tee up the idea': that IS the Take, and it orphans " +
+        "in the shoot UI. A kind:'film' beat must be a PERFORMED MOMENT — a face or a GESTURE — because those become " +
+        "real tasks in the React step (step 2). Reach for a gesture when a phrase invites one: 'the real secret…' → film " +
+        "'Shhh - index finger to your lips as you tease the secret'. " +
+        "EVERY LINE SHOULD HAVE SOMETHING ON SCREEN — the shoot app shows the script beside an 'on screen' column, so " +
+        "cover the script with beats, and lean on the NON-FILM kinds so the creator isn't asked to shoot everything: " +
+        "kind:'web_image' = a logo/graphic/image PULLED FROM THE WEB, floated in a card beside the creator's head (use it " +
+        "when a concept has an obvious visual — 'AI success' → a trending-up chart / trophy); kind:'kinetic' = text " +
+        "overlays AND animated motion graphics. Describe a motion graphic in PLAIN TERMS of what the viewer sees ('a " +
+        "terminal window that types the prompt out') — never name an implementation (don't say 'SVG', 'Lottie' or " +
+        "'Remotion'): these are drawn natively on the phone, so an implementation name is both wrong and meaningless to " +
+        "the creator reading the plan. A terminal/typing animation is the one bespoke motion graphic that renders today " +
+        "(say 'terminal' or 'typing' in the shot and it's picked up); any other kinetic beat renders as its text overlay, " +
+        "so put the words you want burned on screen IN QUOTES. " +
+        "For any web_image/kinetic overlay DON'T pin an exact position — say it floats above the creator's head " +
+        "or wherever there's space, and note that placement is resolved at render so it won't collide with the captions.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            hook: { type: "string", description: "The scroll-stopping opening line / concept." },
+            script: { type: "string", description: "The full narration script to film (teleprompter-ready)." },
+            topic: { type: "string", description: "The core topic / pillar this idea belongs to." },
+            tags: { type: "array", items: { type: "string" }, description: "Optional tags." },
+            asset_plan: {
+                type: "array",
+                description: "Per-shot plan: [{shot, kind:'existing'|'ai_broll'|'web_image'|'kinetic'|'film', note, narration, search_terms, asset_url?}]. " +
+                    "ALWAYS set `search_terms` on any SHOW beat (existing / ai_broll) AND on every `web_image` beat — on a " +
+                    "web_image it's the WEB SEARCH we run to find the graphic, and a result is only kept if its title mentions " +
+                    "one of these terms, so an abstract concept with no concrete nouns finds nothing and the card falls back to " +
+                    "plain text (e.g. 'AI success' → search_terms 'trophy, winner podium, chart going up, success'). " +
+                    "Set `asset_url` instead when a SPECIFIC image is wanted; then no search runs. search_terms are " +
+                    "CONCRETE VISUAL NOUNS, comma-separated, " +
+                    "that could literally appear in a photo — the shoot app matches these against on-device Vision labels of " +
+                    "the creator's camera roll. `shot` is written for a HUMAN to read and is often abstract, which matches " +
+                    "nothing; `search_terms` is what the matcher actually searches. E.g. shot 'Sift through a bunch of AI " +
+                    "output and pick a few good ones' → search_terms 'tablet, laptop screen, computer monitor, grid of images, " +
+                    "hands typing'. Use plain everyday objects/places/people (laptop, screen, desk, phone, coffee, office, " +
+                    "whiteboard) — NOT abstractions ('AI output', 'workflow', 'the future'). " +
+                    "ALWAYS set `narration` to the EXACT word(s) from `script` the creator is SPEAKING while this beat is on " +
+                    "screen — the beats run in order and together cover the whole script, so each beat's narration is its slice of " +
+                    "the script verbatim. A slice does NOT have to be a whole sentence: when an overlay is triggered by SPECIFIC " +
+                    "WORDS, CUT THE SLICE AT THOSE WORDS so the beat lands on the row it belongs to. E.g. for 'The real secret to " +
+                    "AI success isn't learning to prompt.' with a shush gesture on 'the real secret' and a web graphic on 'AI " +
+                    "success', emit TWO beats — narration 'The real secret' then 'to AI success isn't learning to prompt.' — " +
+                    "NOT one sentence-beat plus a graphic pushed onto the NEXT sentence, which mis-times the graphic. This is what the shoot UI shows in quotes under each shot, so the creator knows what " +
+                    "they're saying during it. (A kinetic text-overlay beat still has narration playing under it.)",
+                items: {
+                    type: "object",
+                    properties: {
+                        shot: { type: "string" },
+                        kind: { type: "string", enum: ["existing", "ai_broll", "web_image", "kinetic", "film"] },
+                        note: { type: "string" },
+                        narration: { type: "string", description: "The verbatim script line(s) spoken during this beat." },
+                        search_terms: { type: "string", description: "Concrete visual nouns (comma-separated) to match the creator's camera roll, e.g. 'tablet, laptop screen, grid of images'." },
+                        asset_url: { type: "string" },
+                    },
+                    required: ["shot", "kind"],
+                },
+            },
+            source_url: { type: "string", description: "The saved/pasted post URL this idea is modeled on, if any." },
+            format: { type: "string", enum: ["video", "carousel", "image", "reel_7s"], description: "How it's executed: 'video' (film off the teleprompter) | 'carousel' (image carousel) | 'image' | 'reel_7s' (a 5-7s caption reel — see below). Default video." },
+            caption: { type: "string", description: "For format 'reel_7s' ONLY: the single punchy OVERLAY CAPTION that IS the joke/value (e.g. \"Flight attendant: OMG is there anyone onboard who can align cross-functional stakeholders while navigating ambiguity?\"). The user films 5-7s of themselves reacting / doing a light action (or any B-roll — it barely matters); the caption carries it. Put the caption here AND in `hook`." },
+            week: { type: "string", description: "ISO week tag for weekly batches, e.g. '2026-W27'. Group a week's 5 ideas under the same value." },
+        },
+    },
+    async execute(args) {
+        // For a 7s caption reel the overlay caption IS the content — use it as the hook/script if not given.
+        const hook = args.hook ?? args.caption;
+        const script = args.script ?? (args.format === "reel_7s" ? args.caption : undefined);
+        if (!hook && !script)
+            return "Give the idea at least a `hook` or a `script` (or a `caption` for reel_7s).";
+        const r = await (0, client_js_1.post)("/v1/spin/ideas", {
+            hook,
+            script,
+            topic: args.topic,
+            tags: args.tags,
+            asset_plan: args.asset_plan,
+            source_url: args.source_url,
+            format: args.format,
+            caption: args.caption,
+            week: args.week,
+        });
+        const planNote = args.asset_plan?.length ? ` with a ${args.asset_plan.length}-shot asset plan` : "";
+        return (`Queued idea ${r.id}${planNote} → it's in the user's Prompt/Idea History (/spin/history), saved across sessions + browsers.\n` +
+            `They can open it, film the script on the teleprompter at /create, and the plan says what B-roll to use vs film.`);
+    },
+};
+exports.listIdeasTool = {
+    name: "list_ideas",
+    description: "List the user's queued content ideas (their Prompt/Idea History). Optionally filter by status " +
+        "(queued / scripted / filmed / done / dismissed). Use to resume planning or pick the next idea to execute.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            status: { type: "string", enum: ["queued", "scripted", "filmed", "done", "dismissed"], description: "Optional status filter." },
+        },
+    },
+    async execute(args) {
+        const q = args.status ? `?status=${encodeURIComponent(args.status)}` : "";
+        const r = await (0, client_js_1.get)(`/v1/spin/ideas${q}`);
+        if (!r.ideas.length)
+            return args.status ? `No ideas with status "${args.status}".` : "No ideas queued yet — brainstorm some and queue_idea them.";
+        const lines = r.ideas.map((i) => `- [${i.status}] ${i.hook || "(no hook)"}${i.topic ? ` · ${i.topic}` : ""}${i.source_url ? ` · from ${i.source_url}` : ""}  (id ${i.id})`);
+        return [`${r.ideas.length} idea(s) in the Prompt/Idea History:`, ...lines].join("\n");
+    },
+};

package/dist/tools/image-ads.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.publishToMetaTool = exports.assembleImageAdTool = exports.prepareProductAssetTool = void 0;
+const client_js_1 = require("../client.js");
+const APP_BASE = process.env.VIRALSPIN_APP_URL || "https://app.viralspin.ai";
+exports.prepareProductAssetTool = {
+    name: "prepare_product_asset",
+    description: "Download and verify a product image from a local path or public URL, upload it to ViralSpin " +
+        "cloud storage, and return a stable cloud URL ready for Higgsfield image ad generation.",
+    inputSchema: {
+        type: "object",
+        required: ["image_url"],
+        properties: {
+            image_url: {
+                type: "string",
+                description: "Local file path (e.g. C:/photos/product.jpg) or public URL of the product image.",
+            },
+        },
+    },
+    async execute({ image_url }) {
+        if (image_url.startsWith("http://") || image_url.startsWith("https://")) {
+            return `✅ Asset ready (already a URL):\n\n  ${image_url}\n\nPass this to assemble_image_ad.`;
+        }
+        const { urls } = await (0, client_js_1.uploadFiles)([image_url]);
+        return [
+            `✅ Product asset uploaded:`,
+            ``,
+            `  ${urls[0]}`,
+            ``,
+            `Pass this URL to assemble_image_ad.`,
+        ].join("\n");
+    },
+};
+exports.assembleImageAdTool = {
+    name: "assemble_image_ad",
+    description: "Generate image ad variants from a product photo using Higgsfield AI. " +
+        "Uploads the product image, generates styled variants with your prompt, then creates a " +
+        "client review link showing all variants in a carousel. " +
+        "Requires Higgsfield credentials saved in ViralSpin Settings.",
+    inputSchema: {
+        type: "object",
+        required: ["product_image_path", "prompt"],
+        properties: {
+            product_image_path: {
+                type: "string",
+                description: "Local file path (e.g. C:/photos/product.jpg) or public URL of the product image.",
+            },
+            prompt: {
+                type: "string",
+                description: "Higgsfield styling prompt describing the desired ad aesthetic. " +
+                    "Example: 'luxury product shot on white marble, soft studio lighting, premium brand aesthetic'",
+            },
+            pin: {
+                type: "string",
+                description: "Optional 4-digit PIN to protect the client review link.",
+            },
+        },
+    },
+    async execute({ product_image_path, prompt, pin }) {
+        // Upload local files; pass through URLs unchanged
+        let imageUrl = product_image_path;
+        if (!product_image_path.startsWith("http://") && !product_image_path.startsWith("https://")) {
+            const { urls } = await (0, client_js_1.uploadFiles)([product_image_path]);
+            imageUrl = urls[0];
+        }
+        // Start async generation job — Higgsfield lives on Python backend
+        const { job_id } = await (0, client_js_1.pyPost)("/v1/higgsfield/generate", {
+            product_image_url: imageUrl,
+            prompt,
+        });
+        // Poll until done (~3 min timeout)
+        let variants = [];
+        for (let attempt = 0; attempt < 40; attempt++) {
+            await new Promise((r) => setTimeout(r, 5000));
+            const status = await (0, client_js_1.pyGet)(`/v1/higgsfield/status/${job_id}`);
+            if (status.status === "complete") {
+                variants = status.variant_urls ?? [];
+                break;
+            }
+            if (status.status === "failed") {
+                throw new Error(`Higgsfield generation failed: ${status.error ?? "unknown error"}`);
+            }
+        }
+        if (!variants.length) {
+            throw new Error("Generation timed out after ~3 minutes — try again or check Higgsfield credentials");
+        }
+        // Create a review session with image variants displayed as a carousel
+        const { token } = await (0, client_js_1.post)("/v1/review-sessions", {
+            output_path: variants[0],
+            metadata: {
+                media_type: "image",
+                variants,
+                caption: prompt,
+                platform_targets: ["instagram", "facebook"],
+            },
+            pin: pin ?? null,
+            expires_hours: 168,
+        });
+        const reviewUrl = `${APP_BASE}/review/${token}`;
+        return [
+            `✅ ${variants.length} image ad variant${variants.length > 1 ? "s" : ""} generated!`,
+            ``,
+            `Review link: ${reviewUrl}`,
+            ``,
+            `Send this to your client — they'll see all ${variants.length} variants as a carousel`,
+            `and can Approve or Request Changes.`,
+            pin ? `PIN: ${pin}` : ``,
+            ``,
+            `To publish an approved variant:`,
+            `  publish_to_meta with media_url="${variants[0]}" and your caption.`,
+        ]
+            .filter((l) => l !== undefined)
+            .join("\n");
+    },
+};
+exports.publishToMetaTool = {
+    name: "publish_to_meta",
+    description: "Publish an image (or video) to Instagram and/or Facebook. " +
+        "Use after a client approves an image ad variant from assemble_image_ad.",
+    inputSchema: {
+        type: "object",
+        required: ["media_url", "platforms", "caption"],
+        properties: {
+            media_url: {
+                type: "string",
+                description: "Public URL of the approved image or video to publish.",
+            },
+            platforms: {
+                type: "array",
+                items: { type: "string", enum: ["instagram", "facebook"] },
+                description: "Target platforms: 'instagram', 'facebook', or both.",
+            },
+            caption: {
+                type: "string",
+                description: "Post caption (include hashtags here if desired).",
+            },
+        },
+    },
+    async execute({ media_url, platforms, caption }) {
+        const result = await (0, client_js_1.post)("/v1/publish/schedule", {
+            video_url: media_url,
+            platforms,
+            caption,
+            publish_now: true,
+        });
+        const lines = ["📸 Published to Meta:"];
+        const results = result.results ?? {};
+        for (const [platform, res] of Object.entries(results)) {
+            lines.push(`  ${res.success ? "✅" : "❌"} ${platform}${res.error ? `: ${res.error}` : ""}`);
+        }
+        if (!Object.keys(results).length) {
+            lines.push("  (no platform results returned — check your connected accounts in Settings)");
+        }
+        return lines.join("\n");
+    },
+};

package/dist/tools/kinetic-text.js

@@ -0,0 +1,122 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKineticTextTool = void 0;
+const child_process_1 = require("child_process");
+const path_1 = __importDefault(require("path"));
+const engine_js_1 = require("../engine.js");
+const EFFECTS = ["typing", "billboard_flip", "isometric"];
+const STYLES = ["terminal", "cinematic", "minimal"];
+const FORMATS = ["9x16", "16x9", "1x1"];
+function runKinetic(args) {
+    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, "kinetic.mjs"), ...args], { cwd: engine_js_1.ENGINE_DIR, env: { ...process.env } });
+        let stdout = "";
+        child.stdout.on("data", (d) => { stdout += d.toString(); });
+        child.stderr.on("data", (d) => process.stderr.write(d));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const m = stdout.match(/RESULT:(.+)/);
+            if (code === 0 && m)
+                resolve(m[1].trim());
+            else
+                reject(new Error(`Kinetic render failed (exit ${code}). ${stdout.slice(-300)}`));
+        });
+    });
+}
+exports.createKineticTextTool = {
+    name: "create_kinetic_text",
+    description: "Render a standalone cinematic typing-animation video — great for explainer intros that visually demo " +
+        "what a user types into the prompt. Text is typed out character-by-character with a blinking cursor " +
+        "while a 3D camera slowly pans, giving a cinematic 'Star Wars pull-back' feel. " +
+        "Three effects: 'typing' (character-by-character with 3D camera), " +
+        "'billboard_flip' (words fly from Z-depth and snap into place), " +
+        "'isometric' (letters extrude upward on a tilted plane). " +
+        "Three styles: 'terminal' (green-on-dark, monospace, scanlines), " +
+        "'cinematic' (white-on-black, serif, vignette), " +
+        "'minimal' (transparent background, for overlay use). " +
+        "Returns the path to a finished MP4 — feed it to publish_now or as A-roll in create_video_assembly.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            text: {
+                type: "string",
+                description: "The text to animate — e.g. the prompt the user would type.",
+            },
+            effect: {
+                type: "string",
+                enum: EFFECTS,
+                description: "Animation style. Default: typing.",
+            },
+            style: {
+                type: "string",
+                enum: STYLES,
+                description: "Visual theme. terminal = green monospace; cinematic = white serif; minimal = transparent BG. Default: terminal.",
+            },
+            format: {
+                type: "string",
+                enum: FORMATS,
+                description: "Output aspect ratio. Default: 9x16 (vertical).",
+            },
+            font_size: {
+                type: "number",
+                description: "Font size in px. Auto-sized by format if omitted (72px for 9x16, 96px for 16x9).",
+            },
+            camera: {
+                type: "object",
+                description: "Override the 3D camera end position. Each field defaults to the effect's cinematic preset.",
+                properties: {
+                    rotateX: { type: "number", description: "X-axis tilt in degrees (positive = tilt top toward viewer)." },
+                    rotateY: { type: "number", description: "Y-axis turn in degrees." },
+                    rotateZ: { type: "number", description: "Z-axis roll in degrees." },
+                    translateZ: { type: "number", description: "Z-depth offset in px (negative = pull back/zoom out)." },
+                },
+            },
+            duration_sec: {
+                type: "number",
+                description: "Override clip length in seconds. Default: auto (≈ text.length × 0.1s + 1.5s hold).",
+            },
+            out: {
+                type: "string",
+                description: "Output MP4 path. Defaults to engine/out/kinetic_<timestamp>.mp4.",
+            },
+        },
+        required: ["text"],
+    },
+    async execute(args) {
+        if (!(0, engine_js_1.engineAvailable)("kinetic.mjs")) {
+            return ("create_kinetic_text needs the ViralSpin engine, which isn't bundled in this install.\n" +
+                "Set VIRALSPIN_ASSEMBLY_DIR to a local engine checkout to enable it.");
+        }
+        const cli = ["--text", args.text];
+        if (args.effect)
+            cli.push("--effect", args.effect);
+        if (args.style)
+            cli.push("--style", args.style);
+        if (args.format)
+            cli.push("--format", args.format);
+        if (args.font_size)
+            cli.push("--font-size", String(args.font_size));
+        if (args.duration_sec)
+            cli.push("--duration-sec", String(args.duration_sec));
+        if (args.out)
+            cli.push("--out", args.out);
+        if (args.camera) {
+            const c = args.camera;
+            if (c.rotateX != null)
+                cli.push("--camera-rx", String(c.rotateX));
+            if (c.rotateY != null)
+                cli.push("--camera-ry", String(c.rotateY));
+            if (c.rotateZ != null)
+                cli.push("--camera-rz", String(c.rotateZ));
+            if (c.translateZ != null)
+                cli.push("--camera-tz", String(c.translateZ));
+        }
+        const outPath = await runKinetic(cli);
+        return (`Kinetic text render complete.\n` +
+            `Output: ${outPath}\n` +
+            `Use this as a hook intro by passing it as A-roll to create_video_assembly, or publish directly with publish_now.`);
+    },
+};