@amg555/frameforge-mcp 2.3.1 → 2.3.3

package/plugins/video-pipeline/skills/video-pipeline/assets/project/reel/virtual-clock.js

@@ -0,0 +1,138 @@
+/**
+ * virtual-clock.js — FrameForge Deterministic Virtual Clock Shim
+ *
+ * Intercepts browser timing primitives to enable frame-exact, deterministic
+ * time control for headless video rendering.
+ *
+ * Laws enforced:
+ *   1. Read time, not frames (seek(t) is absolute time in seconds).
+ *   2. Seed everything (Math.random replaced with seeded PRNG).
+ *   3. No integrating physics (timers scheduled along virtual timeline).
+ *   4. Await document.fonts.ready before resolving seek().
+ */
+(() => {
+  let virtualTime = 0;
+  const rafCallbacks = new Map();
+  let rafIdCounter = 0;
+  const timeoutQueue = [];
+  let timeoutIdCounter = 0;
+  const startDate = Date.now();
+
+  window.__playwright = true;
+
+  // 1. Hijack performance.now & Date
+  window.performance.now = () => virtualTime;
+  const OriginalDate = window.Date;
+  class VirtualDate extends OriginalDate {
+    constructor(...args) {
+      if (args.length === 0) {
+        super(startDate + virtualTime);
+      } else {
+        super(...args);
+      }
+    }
+    static now() {
+      return Math.floor(startDate + virtualTime);
+    }
+  }
+  window.Date = VirtualDate;
+
+  // 2. Hijack requestAnimationFrame & cancelAnimationFrame
+  window.requestAnimationFrame = (callback) => {
+    const id = ++rafIdCounter;
+    rafCallbacks.set(id, callback);
+    return id;
+  };
+  window.cancelAnimationFrame = (id) => {
+    rafCallbacks.delete(id);
+  };
+
+  // 3. Hijack setTimeout / clearTimeout / setInterval / clearInterval
+  window.setTimeout = (callback, delay = 0, ...args) => {
+    const id = ++timeoutIdCounter;
+    timeoutQueue.push({ id, runAt: virtualTime + Math.max(0, delay), callback, args, repeat: 0 });
+    timeoutQueue.sort((a, b) => a.runAt - b.runAt);
+    return id;
+  };
+  window.clearTimeout = (id) => {
+    const idx = timeoutQueue.findIndex(item => item.id === id);
+    if (idx !== -1) timeoutQueue.splice(idx, 1);
+  };
+  window.setInterval = (callback, interval = 0, ...args) => {
+    const id = ++timeoutIdCounter;
+    const step = Math.max(16, interval);
+    timeoutQueue.push({ id, runAt: virtualTime + step, callback, args, repeat: step });
+    timeoutQueue.sort((a, b) => a.runAt - b.runAt);
+    return id;
+  };
+  window.clearInterval = (id) => {
+    const idx = timeoutQueue.findIndex(item => item.id === id);
+    if (idx !== -1) timeoutQueue.splice(idx, 1);
+  };
+
+  // 4. Seeded PRNG replacement for Math.random()
+  let seed = 0x2F6E2B1;
+  window.Math.random = () => {
+    seed = (seed + 0x6D2B79F5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+
+  // 5. Global seek contract
+  window.seek = async (tSeconds) => {
+    virtualTime = tSeconds * 1000;
+
+    // Flush due timeouts
+    while (timeoutQueue.length > 0 && timeoutQueue[0].runAt <= virtualTime) {
+      const item = timeoutQueue.shift();
+      try {
+        item.callback(...item.args);
+      } catch (err) {
+        console.error("VirtualClock Timeout Error:", err);
+      }
+      if (item.repeat > 0) {
+        item.runAt = virtualTime + item.repeat;
+        timeoutQueue.push(item);
+        timeoutQueue.sort((a, b) => a.runAt - b.runAt);
+      }
+    }
+
+    // Flush current RAF callbacks
+    const currentRafs = Array.from(rafCallbacks.values());
+    rafCallbacks.clear();
+    for (const cb of currentRafs) {
+      try {
+        cb(virtualTime);
+      } catch (err) {
+        console.error("VirtualClock RAF Error:", err);
+      }
+    }
+
+    // Pause & seek CSS animations
+    try {
+      if (document.getAnimations) {
+        document.getAnimations().forEach(a => {
+          if (a.playState !== 'paused') a.pause();
+          a.currentTime = virtualTime;
+        });
+      }
+    } catch (_) {}
+
+    // Custom scene render hook if exposed
+    if (typeof window.renderFrame === "function") {
+      await window.renderFrame(tSeconds);
+    }
+
+    // Await font readiness
+    if (document.fonts && document.fonts.ready) {
+      await document.fonts.ready;
+    }
+  };
+
+  // Bridge for renderer
+  window.__seek = window.seek;
+
+  window.__VIRTUAL_CLOCK_INSTALLED__ = true;
+})();
+

package/plugins/video-pipeline/skills/video-pipeline/references/mcp-tools.md

@@ -0,0 +1,167 @@
+# MCP Tool Reference
+
+FrameForge exposes 13 tools on the HTTP MCP server (`http://localhost:3210`)
+and via the Cloudflare Remote MCP proxy. Any MCP-compatible client works:
+IBM Bob, Claude Code, Codex, opencode, Cursor, Windsurf.
+
+---
+
+## Agent-first path (recommended)
+
+The IDE writes the scenes array; FrameForge renders it.
+
+### create_video_from_script
+
+```json
+{
+  "scenes": [
+    {
+      "narration": "WiFi sends data as invisible radio waves.",
+      "caption": "RADIO WAVES",
+      "visual_description": "router emitting waves, flat illustration",
+      "camera_hint": "slow_zoom_in",
+      "music_mood": "calm"
+    }
+  ],
+  "title": "How WiFi Works",
+  "skipImages": false,
+  "withMusic": true
+}
+```
+
+Returns: `{ productionId, masterPath, passed, sizeBytes, sceneCount }`
+
+---
+
+## Full pipeline path
+
+### research_topic
+
+```json
+{ "topic": "How does GPS work?", "claimCount": 10, "style": "educational" }
+```
+
+### write_script
+
+```json
+{
+  "productionId": "prod-001",
+  "claims": ["..."],
+  "topic": "How does GPS work?",
+  "persona": "tech explainer",
+  "sceneCount": 15
+}
+```
+
+Returns: `{ productionId, scenes, title, description, tags, sceneCount }`
+
+### render_from_scenes
+
+```json
+{ "productionId": "prod-001", "skipImages": false, "withMusic": true }
+```
+
+### publish_video
+
+```json
+{
+  "productionId": "prod-001",
+  "masterPath": "/path/to/final_video.mp4",
+  "channels": ["file"],
+  "outputDir": "/path/to/output"
+}
+```
+
+Channels:
+- `file` — copy master + shorts to `outputDir` (or `N8N_FILES_DIR/published/`)
+- `webhook` — POST JSON summary to `PUBLISH_WEBHOOK_URL`
+
+---
+
+## Edit path
+
+### ingest_media
+
+```json
+{ "files": ["/path/to/clip1.mp4", "/path/to/clip2.mp4"], "title": "My Video" }
+```
+
+### edit_scenes
+
+```json
+{
+  "productionId": "prod-001",
+  "edits": [{ "sceneIndex": 0, "field": "caption", "value": "NEW CAPTION" }]
+}
+```
+
+---
+
+## TTS
+
+### multi_voice_tts
+
+```json
+{
+  "text": "The text to speak aloud.",
+  "outputPath": "/files-dir/voice_0.m4a",
+  "platform": "elevenlabs",
+  "voice": "your_cloned_voice_id",
+  "apiKey": "sk_..."
+}
+```
+
+---
+
+## Async job control
+
+### queue_full_pipeline
+
+```json
+{
+  "topic": "Why planes avoid straight lines",
+  "style": "educational",
+  "channels": ["file"]
+}
+```
+
+Returns `{ jobId, status }` immediately. Poll `get_job_status` for completion.
+
+### get_job_status
+
+```json
+{ "jobId": "job_1234567890_abc123" }
+```
+
+Returns `{ status: "RUNNING"|"SUCCEEDED"|"FAILED", result, error }`
+
+---
+
+## External platform
+
+### external_platform_call
+
+```json
+{ "action": "ingest", "files": ["/path/to/clip.mp4"] }
+```
+
+Actions: `ingest` | `render` | `status` | `download`.
+Configure with `EXTERNAL_PLATFORM_URL` + `EXTERNAL_PLATFORM_KEY` in `.env`.
+
+---
+
+## Calling from any IDE
+
+Any IDE that supports MCP calls these tools via JSON-RPC:
+
+```json
+POST http://localhost:3210
+{
+  "method": "tools/call",
+  "params": {
+    "name": "create_video_from_script",
+    "arguments": { "scenes": [...] }
+  },
+  "id": 1
+}
+```

package/plugins/video-pipeline/skills/video-pipeline/references/providers.md

@@ -0,0 +1,163 @@
+# Provider Environment Variable Reference
+
+All secrets come from environment variables. Never hardcode them.
+Copy `docs/env.template` → `.env` to get started.
+
+---
+
+## LLM Providers (`PROVIDER_LLM`)
+
+### groq (default)
+```bash
+PROVIDER_LLM=groq
+GROQ_API_KEY=gsk_...
+# Optional overrides:
+LLM_MODEL=llama-3.3-70b-versatile   # default
+LLM_BASE_URL=https://api.groq.com/openai/v1
+```
+
+### watsonx (IBM — enterprise / data-residency)
+```bash
+PROVIDER_LLM=watsonx
+WATSONX_API_KEY=...                  # IBM Cloud API key
+WATSONX_PROJECT_ID=...               # from IBM Cloud → watsonx.ai → Projects
+LLM_BASE_URL=https://us-south.ml.cloud.ibm.com/ml/v1   # or eu-de / jp-tok
+LLM_MODEL=ibm/granite-3-3-8b-instruct   # or granite-3-3-2b-instruct
+```
+Granite 3.3 supports function calling and 128 K context. All inference stays
+in your IBM Cloud region — no data leaves your residency boundary.
+
+### openai
+```bash
+PROVIDER_LLM=openai
+OPENAI_API_KEY=sk-...
+LLM_MODEL=gpt-4o        # default
+```
+
+### ollama (local, no key)
+```bash
+PROVIDER_LLM=ollama
+LLM_BASE_URL=http://localhost:11434/api
+LLM_MODEL=llama3.2      # whatever you have pulled
+```
+
+---
+
+## TTS Providers (`PROVIDER_TTS`)
+
+### edge-tts (default — free, no key, 300+ voices, offline)
+```bash
+PROVIDER_TTS=edge-tts
+# No key required. Needs: npm install -g edge-tts
+# Voice list: edge-tts --list-voices
+```
+
+### elevenlabs (voice cloning)
+```bash
+PROVIDER_TTS=elevenlabs
+ELEVENLABS_API_KEY=sk_...
+# Optional:
+ELEVENLABS_VOICE_ID=21m00Tcm4TlvDq8ikWAM  # default: Rachel
+```
+
+### azure (enterprise)
+```bash
+PROVIDER_TTS=azure
+AZURE_SPEECH_KEY=...
+AZURE_SPEECH_REGION=eastus   # or westeurope, etc.
+```
+
+### openai
+```bash
+PROVIDER_TTS=openai
+OPENAI_API_KEY=sk-...
+# Uses tts-1-hd model, alloy voice by default
+```
+
+---
+
+## Visuals & Media
+
+FrameForge is **code-driven first**. By default, scenes render using vector animations, kinetic typography, and user-provided media (`image_path` / `video_path`). Diffusion image generation is optional and disabled by default.
+
+### Code-driven animation (default)
+```bash
+# Default mode — zero keys needed, broadcast vector quality
+# Automatically creates animated cards, syntax blocks, terminals, and typography
+```
+
+### Optional Diffusion Image Providers (`ENABLE_AI_IMAGES=true`)
+
+### pollinations (default — free, no key)
+```bash
+PROVIDER_IMAGE=pollinations
+# No key required. Uses flux model.
+```
+
+### fal (fast, FLUX-based — recommended for production)
+```bash
+PROVIDER_IMAGE=fal
+FAL_API_KEY=...
+# Also accepted as: FALAI_API_KEY (legacy alias)
+```
+
+### replicate
+```bash
+PROVIDER_IMAGE=replicate
+REPLICATE_API_TOKEN=r8_...
+```
+
+### dalle (DALL-E 3)
+```bash
+PROVIDER_IMAGE=dalle
+OPENAI_API_KEY=sk-...
+```
+
+---
+
+## Delivery
+
+### Webhook
+```bash
+PUBLISH_WEBHOOK_URL=https://your-receiver.example.com/webhook
+REVIEW_NOTIFY_URL=https://your-receiver.example.com/review
+```
+
+### Local File (default)
+```bash
+# Copies master and shorts to output folder
+# No external credentials needed
+```
+
+---
+
+## Telemetry / state (optional PostgreSQL)
+
+```bash
+DATABASE_URL=postgresql://user:pass@localhost:5432/vidpipeline
+```
+Without this, state is stored to `.n8n-files/productions/` (JSON files)
+and telemetry is written to `logs/usage.ndjson`.
+
+---
+
+## IBM Bob specific
+
+Bob discovers MCP servers from `~/.bob/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "video-pipeline": {
+      "command": "node",
+      "args": ["/absolute/path/to/src/mcp-server/server.js"],
+      "env": {
+        "PROVIDER_LLM": "watsonx",
+        "WATSONX_API_KEY": "${WATSONX_API_KEY}",
+        "WATSONX_PROJECT_ID": "${WATSONX_PROJECT_ID}",
+        "PROVIDER_TTS": "edge-tts"
+      }
+    }
+  }
+}
+```
+Restart Bob after adding. The 6 tools appear in Bob's tool palette.

package/scripts/db-migrate.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * db-migrate.js — Apply FrameForge PostgreSQL schema.
+ *
+ * Reads DATABASE_URL from environment and runs the production state-machine
+ * schema (CREATE TABLE IF NOT EXISTS productions).  Safe to run multiple
+ * times — all statements are idempotent.
+ *
+ * Usage:
+ *   DATABASE_URL=postgresql://user:pass@host:5432/frameforge npm run db:migrate
+ *
+ * Or directly:
+ *   DATABASE_URL=... node scripts/db-migrate.js
+ *
+ * Required:  pg  (automatically available when DATABASE_URL is set on Render,
+ *            Railway, Supabase, Neon, or any managed PostgreSQL host)
+ *
+ * The script uses only Node.js built-in pg calls — no ORM, no migration
+ * framework, no extra dependencies beyond the 'pg' package.
+ */
+
+'use strict';
+
+const DATABASE_URL = process.env.DATABASE_URL;
+
+if (!DATABASE_URL) {
+  console.error('[db:migrate] ERROR: DATABASE_URL environment variable is not set.');
+  console.error('  Set it in .env or export it before running:');
+  console.error('  DATABASE_URL=postgresql://user:pass@localhost:5432/frameforge npm run db:migrate');
+  process.exit(1);
+}
+
+// ── Schema SQL ────────────────────────────────────────────────────────────────
+// Mirrors the inline CREATE TABLE in src/pipeline/state-machine.js _pgInit().
+// Keep in sync if the state-machine schema changes.
+
+const MIGRATIONS = [
+  {
+    name: '001_create_productions',
+    sql: `
+      CREATE TABLE IF NOT EXISTS productions (
+        production_id  VARCHAR(64)  PRIMARY KEY,
+        status         VARCHAR(20)  NOT NULL DEFAULT 'QUEUED',
+        pipeline_version VARCHAR(20),
+        schema_version VARCHAR(20),
+        topic          TEXT,
+        created_at     TIMESTAMP    DEFAULT NOW(),
+        started_at     TIMESTAMP,
+        completed_at   TIMESTAMP,
+        config_hash    VARCHAR(32),
+        stages         JSONB        DEFAULT '{}',
+        metadata       JSONB        DEFAULT '{}'
+      );
+    `,
+  },
+  {
+    name: '002_productions_indexes',
+    sql: `
+      CREATE INDEX IF NOT EXISTS productions_status_idx
+        ON productions (status);
+      CREATE INDEX IF NOT EXISTS productions_created_at_idx
+        ON productions (created_at DESC);
+    `,
+  },
+];
+
+// ── Run migrations ────────────────────────────────────────────────────────────
+
+async function run() {
+  let pg;
+  try {
+    pg = require('pg');
+  } catch {
+    console.error('[db:migrate] ERROR: "pg" package not found.');
+    console.error('  Install it:  npm install pg');
+    console.error('  (Only required when DATABASE_URL is set — not needed for file-mode operation.)');
+    process.exit(1);
+  }
+
+  const { Pool } = pg;
+  const pool = new Pool({ connectionString: DATABASE_URL, ssl: DATABASE_URL.includes('sslmode=disable') ? false : { rejectUnauthorized: false } });
+
+  try {
+    await pool.query('SELECT 1'); // connectivity check
+    console.log('[db:migrate] Connected to PostgreSQL.');
+  } catch (err) {
+    console.error(`[db:migrate] ERROR: could not connect — ${err.message}`);
+    console.error('  Check DATABASE_URL and that the database server is reachable.');
+    process.exit(1);
+  }
+
+  for (const migration of MIGRATIONS) {
+    try {
+      await pool.query(migration.sql);
+      console.log(`[db:migrate] ✔  ${migration.name}`);
+    } catch (err) {
+      console.error(`[db:migrate] FAILED: ${migration.name} — ${err.message}`);
+      await pool.end();
+      process.exit(1);
+    }
+  }
+
+  await pool.end();
+  console.log('[db:migrate] All migrations applied. FrameForge PostgreSQL schema is ready.');
+  console.log('');
+  console.log('  Next steps:');
+  console.log('  1. Set RENDER_MODE=api_only in your deployment environment variables.');
+  console.log('  2. The StateMachine will switch to pg mode automatically when DATABASE_URL is set.');
+  console.log('  3. Run `npm run doctor` to verify the full stack.');
+}
+
+run();