@amg555/frameforge-mcp 0.0.0-stage → 2.3.1

package/install.sh

@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Install the video-pipeline skill into your Claude/Bob skills folder.
+#
+#   ./install.sh             copy into ~/.claude/skills  (every project)
+#   ./install.sh --project   copy into ./.claude/skills  (this project only)
+#   ./install.sh --link      symlink instead of copy (edits to repo are live)
+#   ./install.sh --bob       copy into ~/.bob/skills  (IBM Bob global)
+#
+# An existing skill with the same name is moved aside to <name>.bak.<ts>.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SRC="$HERE/plugins/video-pipeline/skills"
+DEST="$HOME/.claude/skills"
+MODE=copy
+
+for a in "$@"; do
+  case "$a" in
+    --link)    MODE=link ;;
+    --project) DEST="$PWD/.claude/skills" ;;
+    --bob)     DEST="$HOME/.bob/skills" ;;
+    -h|--help) sed -n 2,10p "$0"; exit 0 ;;
+    *) echo "unknown option: $a"; exit 1 ;;
+  esac
+done
+
+mkdir -p "$DEST"
+
+for dir in "$SRC"/*; do
+  name=$(basename "$dir")
+  target="$DEST/$name"
+  if [ -e "$target" ] || [ -L "$target" ]; then
+    mv "$target" "$target.bak.$(date +%Y%m%d%H%M%S)"
+    echo "  moved existing $name aside"
+  fi
+  if [ "$MODE" = link ]; then
+    ln -s "$dir" "$target"
+  else
+    cp -R "$dir" "$target"
+  fi
+  echo "  installed $name → $target ($MODE)"
+done
+
+echo
+echo "Dependencies (must be available in PATH):"
+for t in ffmpeg ffprobe node npm; do
+  printf "  %-10s %s\n" "$t" "$(command -v "$t" 2>/dev/null || echo 'MISSING — install it')"
+done
+# Optional: edge-tts for free TTS
+if command -v edge-tts >/dev/null 2>&1; then
+  echo "  edge-tts   $(command -v edge-tts) (free TTS, no key)"
+else
+  echo "  edge-tts   not found — run: npm install -g edge-tts"
+fi
+
+echo
+echo "Next steps:"
+echo "  1. cp docs/env.template .env"
+echo "  2. Edit .env with your API keys (run 'npm run setup' for interactive wizard)"
+echo "  3. Deploy Cloudflare Remote MCP (recommended): cd cloudflare-mcp && wrangler deploy"
+echo "     OR start local HTTP MCP: node src/mcp-server/server.js"
+echo "  4. Register the MCP endpoint in your IDE:"
+echo "     Codex / opencode / Cursor / IBM Bob / Claude Code / Windsurf — see README.md"
+echo "  5. Restart your IDE to load the skill."

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "@amg555/frameforge-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.3.1",
+  "description": "FrameForge — AI video production engine for agentic IDEs. npx @amg555/frameforge-mcp. FFmpeg + TTS run on your machine. 17 MCP tools.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "src/mcp-server/server.js",
+  "bin": {
+    "frameforge": "src/cli/make.js",
+    "frameforge-mcp": "src/mcp-server/stdio.js",
+    "frameforge-setup": "src/cli/setup-keys.js",
+    "frameforge-doctor": "src/cli/doctor.js"
+  },
+  "scripts": {
+    "make": "node src/cli/make.js",
+    "setup": "node src/cli/setup-keys.js",
+    "setup:check": "node src/cli/setup-keys.js --check",
+    "doctor": "node src/cli/doctor.js",
+    "mcp": "node src/mcp-server/server.js",
+    "mcp:stdio": "node src/mcp-server/stdio.js",
+    "start": "node src/mcp-server/server.js",
+    "start:worker": "node src/worker/server.js",
+    "start:worker:render": "node src/worker/server-render-free.js",
+    "start:worker:local": "cross-env RENDER_MODE=full node src/worker/server-render-free.js",
+    "start:local-render": "cross-env RENDER_MODE=full WORKER_PORT=3211 node src/worker/server-render-free.js",
+    "db:migrate": "node scripts/db-migrate.js",
+    "validate": "node scripts/deep-validate.js",
+    "test": "node --test src/pipeline/retry-policy.test.js src/pipeline/telemetry.test.js src/pipeline/artifact-manifest.test.js src/pipeline/artifact-retention.test.js src/pipeline/external-adapter.test.js src/workflows/publishing.test.js src/workflows/script.test.js src/animation/animation-system.test.js src/fact-checker/review-gate.test.js src/fact-checker/checker.test.js src/utils/log-redaction.test.js src/worker/server-render-free.test.js src/worker/server.test.js src/mcp-server/server.test.js src/quality-gate/gate.test.js src/shorts-extractor/extractor.test.js src/audio-mixer/mixer.test.js src/video-renderer/renderer.test.js plugins/video-pipeline/skills/video-pipeline/assets/project/reel/engine.test.js src/integration.test.js",
+    "lint": "echo 'No linter configured — add eslint for production'",
+    "check-credentials": "node src/utils/log-redaction.js",
+    "generate-assets": "node scripts/generate-initial-assets.js",
+    "pipeline:research": "node src/workflows/research.js",
+    "pipeline:script": "node src/workflows/script.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "playwright": "^1.64.1"
+  },
+  "keywords": [
+    "frameforge",
+    "video",
+    "ai",
+    "mcp",
+    "cloudflare",
+    "automation",
+    "ibm-bob",
+    "cursor",
+    "windsurf",
+    "codex",
+    "opencode"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AMG555/FrameForge.git"
+  }
+}

package/src/animation/animation-system.js

@@ -0,0 +1,229 @@
+/**
+ * Animation System — Task #11
+ *
+ * Narrative-driven camera movement presets for the video renderer.
+ * Every preset is a pure function: (scene metadata) → FFmpeg filter string.
+ *
+ * Camera hints map directly to the scene.camera_hint field in schema v1.0.0:
+ *   slow_zoom_in | slow_zoom_out | pan_left | pan_right
+ *   tilt_up | tilt_down | ken_burns | static | auto
+ *
+ * Transition types (used between scenes in the concat filter):
+ *   cut | fade | dissolve | wipe_left | wipe_right
+ *
+ * All zoom values stay within ±1.12x to prevent quality loss (safe_zone = 1.12).
+ * All coordinates use FFmpeg expression notation (evaluated per-frame by zoompan).
+ *
+ * Usage:
+ *   const { buildCameraFilter, buildTransitionFilter, selectCameraHint } = require('./animation-system');
+ *   const vf = buildCameraFilter('slow_zoom_in', { duration: 6 });
+ */
+
+'use strict';
+
+// ── Constants ────────────────────────────────────────────────────────────────
+
+const FPS       = 24;         // target frames per second
+const MAX_ZOOM  = 1.12;       // maximum safe zoom factor
+const BASE_ZOOM = 1.0;        // starting zoom (no zoom)
+const DEFAULT_W = 1920;
+const DEFAULT_H = 1080;
+
+// Per-frame zoom step for a smooth motion over ~8s at 24fps
+// 1.12 - 1.00 = 0.12 over (8 * 24) = 192 frames → 0.000625/frame
+// Round to 0.0007 for slightly snappier feel
+const ZOOM_STEP_IN  = 0.0007;
+const ZOOM_STEP_OUT = 0.0007;
+
+// ── Camera filter builders ───────────────────────────────────────────────────
+
+/**
+ * Build an FFmpeg -vf filter string for the given camera preset.
+ *
+ * @param {string} hint   - camera_hint value from scene schema
+ * @param {{ duration?: number, focalX?: number, focalY?: number, w?: number, h?: number }} opts
+ *   duration  scene duration in seconds (used to calibrate speed)
+ *   focalX/Y  focal point override (0-1 relative, default 0.5/0.35)
+ *   w/h       output resolution (default 1920×1080)
+ * @returns {string}  FFmpeg filter chain (ready for -vf)
+ */
+function buildCameraFilter(hint, { duration = 6, focalX = 0.5, focalY = 0.35, w = DEFAULT_W, h = DEFAULT_H } = {}) {
+  const frames   = Math.max(48, Math.round(duration * FPS));
+  const zoomBase = `${w}x${h}`;
+  // Focal point in pixels
+  const px = Math.round(focalX * w);
+  const py = Math.round(focalY * h);
+
+  switch ((hint || 'auto').toLowerCase()) {
+    case 'slow_zoom_in':
+      return _zoomIn(frames, ZOOM_STEP_IN, zoomBase);
+    case 'slow_zoom_out':
+      return _zoomOut(frames, ZOOM_STEP_OUT, zoomBase);
+    case 'zoom_in':
+      return _zoomIn(frames, 0.0012, zoomBase);
+    case 'zoom_out':
+      return _zoomOut(frames, 0.0012, zoomBase);
+    case 'pan_left':
+      return _pan('left', frames, zoomBase);
+    case 'pan_right':
+      return _pan('right', frames, zoomBase);
+    case 'tilt_up':
+      return _tilt('up', frames, zoomBase);
+    case 'tilt_down':
+      return _tilt('down', frames, zoomBase);
+    case 'ken_burns':
+      return _kenBurns(frames, px, py, w, h, zoomBase);
+    case 'static':
+      return _static(w, h);
+    case 'auto':
+    default:
+      // Deterministic selection based on focal-point quadrant
+      return _autoSelect(focalX, focalY, frames, w, h, zoomBase);
+  }
+}
+
+/**
+ * Build the FFmpeg overlay filter for a cross-dissolve transition between
+ * two pre-rendered scene clips.  Used in complex_filter assembly.
+ *
+ * Note: hard cuts require no filter (FFmpeg concat demuxer default).
+ * Fades/dissolves need xfade filter (FFmpeg ≥4.3).
+ *
+ * @param {'cut'|'fade'|'dissolve'|'wipe_left'|'wipe_right'} type
+ * @param {number} offset  time offset (seconds) at which the transition starts
+ * @param {number} duration transition duration in seconds (default 0.5)
+ * @returns {{ xfadeArgs: string[], isCut: boolean }}
+ */
+function buildTransitionFilter(type, offset, duration = 0.5) {
+  if (type === 'cut' || !type) {
+    return { isCut: true, xfadeArgs: [] };
+  }
+  const xfadeType = {
+    fade:       'fade',
+    dissolve:   'dissolve',
+    wipe_left:  'wipeleft',
+    wipe_right: 'wiperight',
+  }[type] || 'fade';
+
+  // xfade filter args (applied in filtergraph)
+  return {
+    isCut: false,
+    xfadeArgs: [`transition=${xfadeType}`, `offset=${offset.toFixed(3)}`, `duration=${duration}`],
+  };
+}
+
+/**
+ * Select an appropriate camera hint for a scene when none is specified
+ * by the LLM.  Alternates between zoom_in / zoom_out / pan to avoid
+ * monotony.
+ *
+ * @param {number} sceneIndex   0-based scene index
+ * @param {{ focalX?: number, focalY?: number }} focal
+ * @returns {string}
+ */
+function selectCameraHint(sceneIndex, { focalX = 0.5, focalY = 0.35 } = {}) {
+  const rotation = ['slow_zoom_in', 'pan_right', 'slow_zoom_out', 'pan_left', 'tilt_up', 'ken_burns'];
+  return rotation[sceneIndex % rotation.length];
+}
+
+// ── Private filter implementations ───────────────────────────────────────────
+
+function _zoomIn(frames, step = ZOOM_STEP_IN, zoomBase = `${DEFAULT_W}x${DEFAULT_H}`) {
+  const maxZ = MAX_ZOOM.toFixed(4);
+  const rangeStep = frames > 0 ? (MAX_ZOOM - BASE_ZOOM) / frames : step;
+  const s = Math.min(rangeStep, step * 2).toFixed(6);
+  return (
+    `zoompan=` +
+    `z='min(zoom+${s},${maxZ})':` +
+    `x='iw/2-(iw/zoom/2)':` +
+    `y='ih/2-(ih/zoom/2)':` +
+    `d=1:s=${zoomBase}:fps=${FPS}`
+  );
+}
+
+function _zoomOut(frames, step = ZOOM_STEP_OUT, zoomBase = `${DEFAULT_W}x${DEFAULT_H}`) {
+  const maxZ = MAX_ZOOM.toFixed(4);
+  const rangeStep = frames > 0 ? (MAX_ZOOM - BASE_ZOOM) / frames : step;
+  const s = Math.min(rangeStep, step * 2).toFixed(6);
+  return (
+    `zoompan=` +
+    `z='if(lte(zoom,1.0),${maxZ},max(zoom-${s},1.0))':` +
+    `x='iw/2-(iw/zoom/2)':` +
+    `y='ih/2-(ih/zoom/2)':` +
+    `d=1:s=${zoomBase}:fps=${FPS}`
+  );
+}
+
+function _pan(direction, frames, zoomBase = `${DEFAULT_W}x${DEFAULT_H}`) {
+  if (direction === 'left') {
+    return (
+      `zoompan=` +
+      `z='1.06':` +
+      `x='if(gte(on,1),x-0.6,iw*0.04)':` +
+      `y='ih*0.06':` +
+      `d=1:s=${zoomBase}:fps=${FPS}`
+    );
+  }
+  return (
+    `zoompan=` +
+    `z='1.06':` +
+    `x='if(gte(on,1),x+0.6,iw*0.02)':` +
+    `y='ih*0.06':` +
+    `d=1:s=${zoomBase}:fps=${FPS}`
+  );
+}
+
+function _tilt(direction, frames, zoomBase = `${DEFAULT_W}x${DEFAULT_H}`) {
+  if (direction === 'up') {
+    return (
+      `zoompan=` +
+      `z='1.06':` +
+      `x='iw*0.06':` +
+      `y='if(gte(on,1),y-0.4,ih*0.12)':` +
+      `d=1:s=${zoomBase}:fps=${FPS}`
+    );
+  }
+  return (
+    `zoompan=` +
+    `z='1.06':` +
+    `x='iw*0.06':` +
+    `y='if(gte(on,1),y+0.4,ih*0.02)':` +
+    `d=1:s=${zoomBase}:fps=${FPS}`
+  );
+}
+
+function _kenBurns(frames, focalPx, focalPy, w = DEFAULT_W, h = DEFAULT_H, zoomBase = `${DEFAULT_W}x${DEFAULT_H}`) {
+  const maxZ   = MAX_ZOOM.toFixed(4);
+  const startX = Math.max(0, focalPx - w / 2);
+  const startY = Math.max(0, focalPy - h / 2);
+  return (
+    `zoompan=` +
+    `z='max(${maxZ}-0.0006*on,1.0)':` +
+    `x='if(eq(on,1),${startX},x+(iw/2-(iw/zoom/2)-x)*0.02)':` +
+    `y='if(eq(on,1),${startY},y+(ih/2-(ih/zoom/2)-y)*0.02)':` +
+    `d=1:s=${zoomBase}:fps=${FPS}`
+  );
+}
+
+function _static(w = DEFAULT_W, h = DEFAULT_H) {
+  return `scale=${w}:${h}:force_original_aspect_ratio=increase:flags=lanczos,crop=${w}:${h}`;
+}
+
+function _autoSelect(focalX, focalY, frames, w = DEFAULT_W, h = DEFAULT_H, zoomBase = `${DEFAULT_W}x${DEFAULT_H}`) {
+  if (focalY < 0.4 && focalX < 0.5)  return _zoomIn(frames, ZOOM_STEP_IN, zoomBase);
+  if (focalY < 0.4 && focalX >= 0.5) return _kenBurns(frames, Math.round(focalX * w), Math.round(focalY * h), w, h, zoomBase);
+  if (focalX < 0.4)                   return _pan('right', frames, zoomBase);
+  if (focalX > 0.6)                   return _pan('left', frames, zoomBase);
+  return _zoomOut(frames, ZOOM_STEP_OUT, zoomBase);
+}
+
+// ── Exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  buildCameraFilter,
+  buildTransitionFilter,
+  selectCameraHint,
+  // constants exposed for testing
+  FPS,
+  MAX_ZOOM,
+};

package/src/asset-library/README.md

@@ -0,0 +1,188 @@
+# Asset Library System
+
+Composable asset management for consistent video production.
+
+## Architecture
+
+### Composable Asset System
+
+Instead of pre-generating all combinations (2 chars × 4 poses × 6 emotions = 48 combinations), we store:
+
+- **Character identities:** 2 base characters (ancient_man, modern_man)
+- **Pose variants:** 4 poses per character (standing, running, sitting, jumping)
+- **Emotion overlays:** 6 emotions per character (neutral, happy, angry, sad, surprised, determined)
+- **Props:** 15 reusable items (spear, phone, fire, etc.)
+- **Backgrounds:** 10 scenes (forest, cave, city, etc.)
+- **Effects:** 10 SVG overlays (arrow, question, etc.)
+
+**Total:** ~47 composable assets vs 67-83 pre-generated combinations
+
+### Runtime Composition
+
+```
+Request: character=ancient_man, pose=running, emotion=determined
+
+Composition:
+  1. Load identity: ancient_man_identity.png
+  2. Load pose: ancient_man/poses/running.png
+  3. Load emotion: ancient_man/emotions/determined.png
+  4. Composite layers → final image
+```
+
+## Directory Structure
+
+```
+assets/
+├── characters/
+│   ├── ancient_man/
+│   │   ├── identity_v1.png          # Base character
+│   │   ├── schema_version.json      # Metadata
+│   │   ├── poses/
+│   │   │   ├── standing.png
+│   │   │   ├── running.png
+│   │   │   ├── sitting.png
+│   │   │   └── jumping.png
+│   │   └── emotions/
+│   │       ├── neutral.png
+│   │       ├── happy.png
+│   │       ├── angry.png
+│   │       ├── sad.png
+│   │       ├── surprised.png
+│   │       └── determined.png
+│   └── modern_man/
+│       ├── identity_v1.png
+│       ├── schema_version.json
+│       ├── poses/
+│       └── emotions/
+├── props/
+│   ├── spear.png
+│   ├── phone.png
+│   ├── fire.png
+│   └── ... (15 total)
+├── backgrounds/
+│   ├── forest.png
+│   ├── cave.png
+│   ├── city.png
+│   └── ... (10 total)
+├── effects/
+│   ├── arrow.svg
+│   ├── question.svg
+│   └── ... (10 total)
+└── metadata/
+    ├── assets.json              # Asset registry
+    └── embeddings.json          # Semantic search cache
+```
+
+## Asset Metadata Schema
+
+```json
+{
+  "asset_id": "ancient_man_identity_v1",
+  "asset_type": "character_identity",
+  "character_id": "ancient_man",
+  "pose": null,
+  "emotion": null,
+  "visual_description": "Caveman with wild hair, tattered animal skin clothing",
+  "file_path": "assets/characters/ancient_man/identity_v1.png",
+  "style_parameters": {
+    "ink_style": "clean_line",
+    "color_palette": ["#000000", "#FFFFFF", "#8B4513"],
+    "line_weight": 3,
+    "resolution": "1920x1080"
+  },
+  "metadata": {
+    "creation_date": "2026-09-09T10:00:00Z",
+    "usage_count": 42,
+    "variants": ["pose:running", "emotion:determined"]
+  },
+  "schema_version": "1.0.0"
+}
+```
+
+## Matching Algorithm
+
+### 1. Metadata Filtering (Primary)
+
+```sql
+SELECT * FROM assets 
+WHERE asset_type = 'character_identity'
+  AND character_id = 'ancient_man'
+  AND (pose = 'running' OR pose IS NULL)
+  AND (emotion = 'determined' OR emotion IS NULL);
+```
+
+Fast metadata lookup in PostgreSQL for exact matches.
+
+### 2. Semantic Fallback (Secondary)
+
+If no metadata match:
+1. Compute embedding of visual description
+2. Search embeddings with cosine similarity
+3. Return if similarity > 0.85
+4. Otherwise, generate new asset
+
+## Style Consistency
+
+All generated assets must match:
+
+- **Ink style:** clean_line (Simple History / Doodle style)
+- **Color palette:** Limited colors (black, white, earth tones)
+- **Line weight:** 2-4px (consistent thickness)
+- **Resolution:** 1920x1080 (landscape master)
+- **Background:** White or transparent
+- **Character scale:** Consistent proportions
+
+## Asset Generation
+
+When no match found:
+
+```javascript
+const prompt = `
+Simple History doodle style illustration.
+Character: ${character_id}
+Pose: ${pose}
+Emotion: ${emotion}
+Style: Thick black ink lines, clean line art, white background.
+No photorealism. Exaggerated facial expression.
+Single character only.
+1920x1080 landscape.
+`;
+
+const imageUrl = await pollinations.generate({
+  prompt,
+  width: 1920,
+  height: 1080,
+  seed: deterministicSeed
+});
+```
+
+## API
+
+See `asset-library.js` for implementation:
+
+- `initialize()` - Load asset registry
+- `findAsset(query)` - Search with metadata + semantic fallback
+- `generateAsset(description)` - Create new asset
+- `validateAsset(asset)` - Check style consistency
+- `composeCharacter(identity, pose, emotion)` - Layer composition
+
+## Schema Versioning
+
+All assets track `schema_version: "1.0.0"` for evolution:
+
+- **1.0.0:** Initial composable system
+- **1.1.0:** (Future) Add animation keyframes
+- **2.0.0:** (Future) 3D pose variants
+
+## Performance
+
+- **Metadata lookup:** <10ms (PostgreSQL indexed)
+- **Semantic search:** <200ms (cached embeddings)
+- **Asset composition:** <500ms (image layering)
+- **Asset generation:** 5-15s (Pollinations API)
+
+## Storage
+
+- **Per identity:** ~2MB (base + poses + emotions)
+- **Total library:** ~100MB for 47 composable assets
+- **Cache efficiency:** 70%+ asset reuse across videos