@amg555/frameforge-mcp 0.0.0-stage → 2.3.1

package/src/workflows/render.js

@@ -0,0 +1,102 @@
+/**
+ * Workflow D — Rendering
+ * Task #31: assets → TTS → audio mix → master video
+ *
+ * Returns: { productionId, masterPath, qcReport, sizeBytes }
+ */
+'use strict';
+
+const path   = require('path');
+const crypto = require('crypto');
+const { StateMachine }  = require('../pipeline/state-machine');
+const { RetryPolicy }   = require('../pipeline/retry-policy');
+const { Telemetry }     = require('../pipeline/telemetry');
+const { VideoRenderer } = require('../video-renderer/renderer');
+const { AudioMixer }    = require('../audio-mixer/mixer');
+const { QualityGate }   = require('../quality-gate/gate');
+
+const os = require('os');
+const FILES_DIR = process.env.N8N_FILES_DIR || require('path').join(os.homedir(), '.frameforge-files');
+const STATE_DIR = `${FILES_DIR}/state`;
+
+/**
+ * Render all scene assets into a final master video.
+ * @param {{ productionId: string, sceneAssets: object[], withMusic?: boolean, musicVolume?: number }} opts
+ * @returns {Promise<RenderResult>}
+ */
+async function runRender({ productionId, sceneAssets, withMusic = true, musicVolume = 0.07, renderWidth = 1920, renderHeight = 1080 }) {
+  const sm        = new StateMachine({ mode: 'file', stateDir: STATE_DIR });
+  const retryPol  = new RetryPolicy({ maxAttempts: 2, baseDelayMs: 15000 });
+  const telemetry = new Telemetry({ mode: 'file', logPath: `${FILES_DIR}/usage.ndjson` });
+  const renderer  = new VideoRenderer({ filesDir: FILES_DIR });
+  const mixer     = new AudioMixer({ filesDir: FILES_DIR });
+  const qc        = new QualityGate();
+
+  await sm.init();
+  await telemetry.init();
+  await sm.startStage(productionId, 'Video_Rendering');
+
+  // ── Phase 1: Render individual scenes ─────────────────────────────────
+  const sceneFiles = [];
+  for (const asset of sceneAssets) {
+    const idx = asset.sceneId - 1;
+    try {
+      const scenePath = renderer.renderScene({
+        sceneIndex: idx,
+        imagePath:  asset.imagePath,
+        videoPath:  asset.videoPath,
+        voicePath:  asset.voicePath,
+        caption:    asset.caption || '',
+        camera:     asset.camera  || 'static',
+        focalPoint: asset.focalPoint || null,
+        renderWidth,
+        renderHeight,
+      });
+      sceneFiles.push(scenePath);
+    } catch (err) {
+      console.error(`[Render] Scene ${idx} failed: ${err.message} — skipping`);
+    }
+  }
+
+  if (sceneFiles.length < 1) {
+    await sm.failStage(productionId, 'Video_Rendering', `No scenes rendered successfully`);
+    throw new Error(`No scenes rendered successfully`);
+  }
+  if (sceneFiles.length < 3) {
+    console.warn(`[Render] WARNING: only ${sceneFiles.length} scene(s) rendered — video will be short. Minimum 3 recommended.`);
+  }
+
+  // ── Phase 2: Assemble master ──────────────────────────────────────────
+  const masterPath = await retryPol.executeStage('Video_Rendering', async () =>
+    renderer.assembleMain({ productionId, sceneCount: sceneFiles.length, withMusic, musicVolume })
+  );
+
+  // ── Phase 3: Quality gate ─────────────────────────────────────────────
+  const qcReport = await qc.validateMaster(masterPath);
+  if (!qcReport.passed) {
+    const failed = qcReport.checks.filter(c => !c.passed).map(c => c.name).join(', ');
+    await sm.failStage(productionId, 'Video_Rendering', `QC failed: ${failed}`);
+    return { productionId, passed: false, qcReport, masterPath: null };
+  }
+
+  const stat = require('fs').statSync(masterPath);
+  const outputHash = crypto.createHash('sha256')
+    .update(`${productionId}:${stat.size}:${sceneFiles.length}`)
+    .digest('hex').slice(0, 16);
+
+  await sm.completeStage(productionId, 'Video_Rendering', {
+    outputHash,
+    metrics: { sceneCount: sceneFiles.length, sizeBytes: stat.size },
+  });
+  await telemetry.track({
+    productionId,
+    stage: 'Video_Rendering',
+    provider: 'ffmpeg',
+    operation: 'master_render',
+    units: Math.round(stat.size / 1024 / 1024),
+  });
+
+  return { productionId, masterPath, passed: true, qcReport, sizeBytes: stat.size, sceneCount: sceneFiles.length, outputHash };
+}
+
+module.exports = { runRender };

package/src/workflows/research.js

@@ -0,0 +1,151 @@
+/**
+ * Workflow A — Research
+ *
+ * Generic topic researcher. Works for any content type: tech explainers,
+ * cooking tutorials, travel vlogs, educational shorts, etc.
+ *
+ * The caller (agentic IDE or CLI) controls persona, format and style.
+ * This module does NOT hardcode any domain or narrator persona.
+ *
+ * Can be called from:
+ *   1. MCP server:  research_topic tool
+ *   2. CLI:         node src/workflows/research.js --topic "..."
+ *   3. Worker API:  full_pipeline job type
+ *
+ * Returns: { productionId, topic, claims[], myths[], angles[], hookIdeas[] }
+ */
+'use strict';
+
+const crypto = require('crypto');
+const { LLMProvider }  = require('../pipeline/providers');
+const { StateMachine } = require('../pipeline/state-machine');
+const { RetryPolicy }  = require('../pipeline/retry-policy');
+const { Telemetry }    = require('../pipeline/telemetry');
+const { FactChecker }  = require('../fact-checker/checker');
+
+const os = require('os');
+const FILES_DIR = process.env.N8N_FILES_DIR || require('path').join(os.homedir(), '.frameforge-files');
+const STATE_DIR = `${FILES_DIR}/state`;
+
+/**
+ * Run the research workflow for a single topic.
+ *
+ * @param {string} topic
+ * @param {{
+ *   claimCount?:   number,
+ *   productionId?: string,
+ *   persona?:      string,  // e.g. "tech journalist", "travel blogger", "cooking instructor"
+ *   format?:       string,  // e.g. "short-form reel", "long YouTube video", "explainer"
+ *   style?:        string,  // e.g. "educational", "comedic", "documentary", "tutorial"
+ *   audience?:     string,  // e.g. "beginners", "professionals", "general public"
+ * }} opts
+ * @returns {Promise<ResearchResult>}
+ */
+async function runResearch(topic, {
+  claimCount = 10,
+  productionId = null,
+  persona = 'video content researcher',
+  format = 'video',
+  style = 'informative',
+  audience = 'general public',
+} = {}) {
+  const llm       = new LLMProvider();
+  const sm        = new StateMachine({ mode: 'file', stateDir: STATE_DIR });
+  const retryPol  = new RetryPolicy({ maxAttempts: 3, baseDelayMs: 10000 });
+  const telemetry = new Telemetry({ mode: 'file', logPath: `${FILES_DIR}/usage.ndjson` });
+  const checker   = new FactChecker({ llm });
+
+  await sm.init();
+  await telemetry.init();
+
+  const pid = productionId || await sm.createProduction({ topic, pipelineVersion: '2.0.0' });
+  await sm.startStage(pid, 'Research');
+
+  // ── Phase 1: Initial research ─────────────────────────────────────────────
+  const researchRaw = await retryPol.executeStage('Research', async () => {
+    const system = [
+      `You are a ${persona} specialising in ${format} content.`,
+      'Output ONLY raw JSON. No markdown. No code fences. Start with { and end with }.',
+    ].join(' ');
+
+    const user = [
+      `TOPIC: ${topic}`,
+      `FORMAT: ${format}`,
+      `STYLE: ${style}`,
+      `AUDIENCE: ${audience}`,
+      '',
+      `Return ${claimCount} factual claims as JSON:`,
+      '{"topic":"...","claims":[{"claim":"...","confidence":"high|medium|low","safe_wording":"..."}],',
+      '"common_myths":["..."],"modern_comparisons":["..."],"story_angles":["..."],',
+      '"hook_ideas":["...","...","..."]}',
+    ].join('\n');
+
+    return llm.chat({ system, user, temperature: 0.7, maxTokens: 4000 });
+  });
+
+  let research;
+  try { research = LLMProvider.parseJson(researchRaw); }
+  catch (e) { throw new Error(`Research JSON parse failed: ${e.message}`); }
+  if (!Array.isArray(research.claims) || research.claims.length < 5) {
+    throw new Error(`Research returned too few claims: ${research.claims?.length}`);
+  }
+
+  // ── Phase 2: Fact-check all claims ───────────────────────────────────────
+  const checkedClaims = await Promise.all(
+    research.claims.map(async c => {
+      try {
+        const result = await checker.checkClaim(c, { context: topic });
+        return {
+          ...c,
+          factCheckResult: result.decision,
+          riskLevel:       result.riskLevel,
+          requiresReview:  result.requiresHumanReview,
+          sources:         result.evidence || [],
+        };
+      } catch {
+        return { ...c, factCheckResult: 'UNVERIFIED', requiresReview: true };
+      }
+    })
+  );
+
+  const approved    = checkedClaims.filter(c => !c.requiresReview);
+  const needsReview = checkedClaims.filter(c =>  c.requiresReview);
+
+  if (needsReview.length > 0) {
+    console.warn(`[Research] ${needsReview.length} claims flagged for review:`, needsReview.map(c => c.claim.slice(0, 60)));
+  }
+
+  const outputHash = crypto.createHash('sha256').update(researchRaw).digest('hex').slice(0, 16);
+  await sm.completeStage(pid, 'Research', { outputHash });
+  await telemetry.track({
+    productionId: pid,
+    stage: 'Research',
+    provider: process.env.PROVIDER_LLM || 'groq',
+    operation: 'research_generation',
+    units: Math.ceil(researchRaw.length / 4),
+  });
+
+  return {
+    productionId:    pid,
+    topic,
+    claims:          approved,
+    claimsForReview: needsReview,
+    myths:           research.common_myths || [],
+    angles:          research.story_angles || [],
+    hookIdeas:       research.hook_ideas   || [],
+    outputHash,
+  };
+}
+
+module.exports = { runResearch };
+
+// ── CLI entrypoint ─────────────────────────────────────────────────────────
+if (require.main === module) {
+  const args  = process.argv.slice(2);
+  const tIdx  = args.indexOf('--topic');
+  const topic = tIdx >= 0 ? args[tIdx + 1] : args[0];
+  if (!topic) { console.error('Usage: node src/workflows/research.js --topic "..."'); process.exit(1); }
+  runResearch(topic).then(r => {
+    console.log(JSON.stringify(r, null, 2));
+  }).catch(e => { console.error(e.message); process.exit(1); });
+}

package/src/workflows/script.js

@@ -0,0 +1,210 @@
+/**
+ * Workflow B — Script
+ *
+ * Generic scriptwriter. Works for any video format, topic, style, or language.
+ * The caller controls persona, style, format and scene count.
+ * No hardcoded domain, character types, or visual aesthetic.
+ *
+ * Returns: { productionId, scenes[], shorts[], title, description,
+ *            tags[], thumbnailPrompt, totalWords }
+ */
+'use strict';
+
+const crypto = require('crypto');
+const { LLMProvider }  = require('../pipeline/providers');
+const { StateMachine } = require('../pipeline/state-machine');
+const { RetryPolicy }  = require('../pipeline/retry-policy');
+const { Telemetry }    = require('../pipeline/telemetry');
+
+const os = require('os');
+const FILES_DIR = process.env.N8N_FILES_DIR || require('path').join(os.homedir(), '.frameforge-files');
+const STATE_DIR = `${FILES_DIR}/state`;
+
+const ALLOWED_CAMERAS  = ['zoom_in','zoom_out','pan_left','pan_right','static','auto'];
+const ALLOWED_MOODS    = ['tense','calm','energetic','mysterious','neutral','dramatic','humorous'];
+
+/**
+ * Normalise a single scene from LLM output.
+ * Accepts both v2.0.0 (visual_description) and legacy (visual_action) fields.
+ * Character IDs are now free-form strings (no enforced enum).
+ */
+function normaliseScene(raw, index) {
+  const sceneId = raw.scene_id || raw.n || (index + 1);
+  const visDesc = String(raw.visual_description || raw.visual_action || 'scene visual').trim();
+  const char    = raw.character || {};
+  const pos     = char.position || {};
+  const fp      = raw.focal_point || {};
+  const meta    = raw.metadata || {};
+
+  return {
+    scene_id:       sceneId,
+    schema_version: '2.0.0',
+    narration:      String(raw.narration || '').trim(),
+    caption:        String(raw.caption   || '').toUpperCase().trim().slice(0, 40),
+    visual_description: visDesc,
+    // character is now fully open — character_id is any string the caller provides
+    character: {
+      character_id: String(char.character_id || 'none'),
+      pose:         String(char.pose         || 'none'),
+      emotion:      String(char.emotion      || 'neutral'),
+      position: {
+        x:     typeof pos.x     === 'number' ? Math.max(0, Math.min(1, pos.x))       : 0.5,
+        y:     typeof pos.y     === 'number' ? Math.max(0, Math.min(1, pos.y))       : 0.8,
+        scale: typeof pos.scale === 'number' ? Math.max(0.5, Math.min(2, pos.scale)) : 1.0,
+      },
+    },
+    focal_point: {
+      x:      typeof fp.x      === 'number' ? Math.max(0, Math.min(1, fp.x))      : 0.5,
+      y:      typeof fp.y      === 'number' ? Math.max(0, Math.min(1, fp.y))      : 0.35,
+      weight: typeof fp.weight === 'number' ? Math.max(0, Math.min(1, fp.weight)) : 0.8,
+    },
+    overlay:       raw.overlay       || { type: 'none' },
+    sound_effects: Array.isArray(raw.sound_effects) ? raw.sound_effects : [],
+    music_mood:    ALLOWED_MOODS.includes(raw.music_mood)    ? raw.music_mood    : 'neutral',
+    camera_hint:   ALLOWED_CAMERAS.includes(raw.camera_hint) ? raw.camera_hint  :
+                   ALLOWED_CAMERAS.includes(raw.camera)      ? raw.camera       : 'auto',
+    // Caller-supplied media paths — set these to skip AI generation for a scene
+    image_path:    raw.image_path  || null,
+    video_path:    raw.video_path  || null,
+    audio_path:    raw.audio_path  || null,
+    metadata: {
+      importance:     meta.importance    || 'medium',
+      hook_potential: typeof meta.hook_potential === 'number' ? meta.hook_potential : 0.5,
+      standalone:     typeof meta.standalone === 'boolean'    ? meta.standalone     : false,
+    },
+  };
+}
+
+/**
+ * Run the script generation workflow.
+ *
+ * @param {{
+ *   productionId: string,
+ *   claims:       object[],
+ *   topic:        string,
+ *   style?:       string,   // e.g. "educational", "comedic", "documentary", "tutorial", "vlog"
+ *   persona?:     string,   // who the narrator is, e.g. "travel blogger", "tech reviewer"
+ *   format?:      string,   // e.g. "YouTube short", "Instagram reel", "long-form tutorial", "explainer"
+ *   language?:    string,   // BCP-47 code, default "en"
+ *   sceneCount?:  number,   // target number of scenes (default 55 for long-form, fewer for shorts)
+ *   targetDuration?: number, // target video duration in seconds (used as guidance for scene count)
+ *   imageStyle?:  string,   // visual aesthetic for AI image prompts, e.g. "flat design", "photorealistic"
+ * }} opts
+ */
+async function runScript({
+  productionId,
+  claims,
+  topic,
+  style        = 'informative',
+  persona      = 'video host',
+  format       = 'YouTube video',
+  language     = 'en',
+  sceneCount   = 55,
+  targetDuration = null,
+  imageStyle   = 'clean flat illustration, white background, bold lines',
+}) {
+  const llm       = new LLMProvider();
+  const sm        = new StateMachine({ mode: 'file', stateDir: STATE_DIR });
+  const retryPol  = new RetryPolicy({ maxAttempts: 3, baseDelayMs: 10000 });
+  const telemetry = new Telemetry({ mode: 'file', logPath: `${FILES_DIR}/usage.ndjson` });
+
+  await sm.init();
+  await telemetry.init();
+  await sm.startStage(productionId, 'Script');
+
+  const facts = claims.slice(0, 8).map(c => c.safe_wording || c.claim).join('; ');
+
+  // If targetDuration is given, adjust scene count guidance (≈ 5s/scene).
+  // No ceiling — long-form documentaries, lectures, and podcasts may need hundreds of scenes.
+  const targetScenes = targetDuration ? Math.max(5, Math.round(targetDuration / 5)) : sceneCount;
+
+  const raw = await retryPol.executeStage('Script', async () => {
+    const system = [
+      `You are a ${persona} writing a ${format} script.`,
+      `Style: ${style}. Language: ${language}.`,
+      `Visual aesthetic for image prompts: ${imageStyle}.`,
+      'Output ONLY raw JSON. No markdown. Start with { end with }.',
+      'schema_version must be "2.0.0" on every scene.',
+    ].join(' ');
+
+    const user = [
+      `TOPIC: ${topic}`,
+      `FACTS: ${facts}`,
+      `FORMAT: ${format}`,
+      `STYLE: ${style}`,
+      `LANGUAGE: ${language}`,
+      '',
+      `Write exactly ${targetScenes} scenes (schema_version "2.0.0"). Each scene must have:`,
+      'scene_id (integer), schema_version "2.0.0",',
+      'narration (15-35 words in the specified language, spoken aloud),',
+      'caption (3-6 words UPPERCASE, text overlay),',
+      'visual_description (vivid description of what the scene looks like — used as image prompt),',
+      'character { character_id (free text or "none"), pose, emotion, position {x,y,scale} },',
+      'focal_point {x,y,weight},',
+      'overlay { type: "prop"|"effect"|"text"|"none" },',
+      'sound_effects [ { effect_id, timing: "start"|"middle"|"end", volume } ],',
+      'music_mood: "tense"|"calm"|"energetic"|"mysterious"|"neutral"|"dramatic"|"humorous",',
+      'camera_hint: "zoom_in"|"zoom_out"|"pan_left"|"pan_right"|"static"|"auto",',
+      'metadata { importance, hook_potential (0-1), standalone (bool) }',
+      '',
+      'RESPOND WITH EXACTLY:',
+      '{"topic":"...","title":"...","description":"...","tags":["..."],"thumbnail_prompt":"...",',
+      `"scenes":[...${targetScenes} scenes...],"shorts":[{"short_id":1,"title":"...","scene_range":[1,5],"hook_scene":1}]}`,
+    ].join('\n');
+
+    return llm.chat({ system, user, temperature: 1, maxTokens: 32000 });
+  });
+
+  let script;
+  try { script = LLMProvider.parseJson(raw); }
+  catch (e) { throw new Error(`Script parse failed: ${e.message}`); }
+  if (!Array.isArray(script.scenes) || script.scenes.length < 5) {
+    throw new Error(`Too few scenes: ${script.scenes?.length}`);
+  }
+
+  // No scene count ceiling — callers supply targetDuration / sceneCount and the
+  // pipeline renders however many scenes the script produces.
+  const scenes = script.scenes.map((s, i) => normaliseScene(s, i));
+
+  const totalWords = scenes.reduce((n, s) => n + (s.narration || '').split(/\s+/).filter(Boolean).length, 0);
+  if (totalWords < 50) throw new Error(`Script too short: ${totalWords} words`);
+
+  const outputHash = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 16);
+  await sm.completeStage(productionId, 'Script', { outputHash });
+  await telemetry.track({
+    productionId,
+    stage: 'Script',
+    provider: process.env.PROVIDER_LLM || 'groq',
+    operation: 'script_generation',
+    units: Math.ceil(raw.length / 4),
+  });
+
+  return {
+    productionId,
+    scenes,
+    shorts:      script.shorts      || [],
+    title:       script.title       || topic,
+    description: script.description || '',
+    tags:        script.tags        || [],
+    thumbnailPrompt: script.thumbnail_prompt || '',
+    totalWords,
+    sceneCount:  scenes.length,
+    outputHash,
+  };
+}
+
+module.exports = { runScript, normaliseScene };
+
+// ── CLI entrypoint ─────────────────────────────────────────────────────────
+if (require.main === module) {
+  const { runResearch } = require('./research');
+  const args   = process.argv.slice(2);
+  const tIdx   = args.indexOf('--topic');
+  const topic  = tIdx >= 0 ? args[tIdx + 1] : args[0];
+  if (!topic) { console.error('Usage: node src/workflows/script.js --topic "..."'); process.exit(1); }
+  (async () => {
+    const res = await runResearch(topic);
+    const scr = await runScript({ productionId: res.productionId, claims: res.claims, topic });
+    console.log(JSON.stringify({ sceneCount: scr.scenes.length, totalWords: scr.totalWords, title: scr.title }, null, 2));
+  })().catch(e => { console.error(e.message); process.exit(1); });
+}

package/src/workflows/shorts.js

@@ -0,0 +1,113 @@
+/**
+ * Workflow D2 — Shorts
+ * Task #32: master → segment scoring → vertical render with saliency/focal-point → QC
+ *
+ * Returns: { productionId, shorts[{ shortPath, score, qcReport }] }
+ */
+'use strict';
+
+const path   = require('path');
+const crypto = require('crypto');
+const { StateMachine }      = require('../pipeline/state-machine');
+const { RetryPolicy }       = require('../pipeline/retry-policy');
+const { Telemetry }         = require('../pipeline/telemetry');
+const { ShortsExtractor }   = require('../shorts-extractor/extractor');
+const { QualityGate }       = require('../quality-gate/gate');
+
+const os = require('os');
+const FILES_DIR = process.env.N8N_FILES_DIR || require('path').join(os.homedir(), '.frameforge-files');
+const STATE_DIR = `${FILES_DIR}/state`;
+
+/**
+ * Extract and render shorts from a master video.
+ * @param {{ productionId: string, masterPath: string, scenes: object[], maxShorts?: number }} opts
+ */
+async function runShorts({ productionId, masterPath, scenes = [], maxShorts = 3 }) {
+  const sm        = new StateMachine({ mode: 'file', stateDir: STATE_DIR });
+  const retryPol  = new RetryPolicy({ maxAttempts: 2, baseDelayMs: 10000 });
+  const telemetry = new Telemetry({ mode: 'file', logPath: `${FILES_DIR}/usage.ndjson` });
+  const extractor = new ShortsExtractor({ filesDir: FILES_DIR });
+  const qc        = new QualityGate();
+
+  await sm.init();
+  await telemetry.init();
+  await sm.startStage(productionId, 'Shorts_Extraction');
+
+  // Build scene metadata map for focal-point-aware cropping
+  const sceneMeta = Object.fromEntries(
+    scenes.map(s => [s.scene_id, {
+      focalPoint:   s.focal_point,
+      hookPotential: s.metadata?.hook_potential || 0.5,
+      standalone:   s.metadata?.standalone || false,
+    }])
+  );
+
+  // Discover candidate segments from master
+  let segments;
+  try {
+    segments = await retryPol.executeStage('Shorts_Extraction', async () =>
+      extractor.extractCandidates(masterPath, { sceneMeta, maxCandidates: maxShorts * 3 })
+    );
+  } catch (err) {
+    await sm.failStage(productionId, 'Shorts_Extraction', err.message);
+    throw err;
+  }
+
+  if (!segments || segments.length === 0) {
+    await sm.skipStage(productionId, 'Shorts_Extraction', 'No suitable short segments found');
+    return { productionId, shorts: [], skipped: true };
+  }
+
+  // Render top-N shorts as 9:16 vertical videos
+  const shorts = [];
+  const topSegments = segments.slice(0, maxShorts);
+
+  for (let i = 0; i < topSegments.length; i++) {
+    const seg = topSegments[i];
+    const shortPath = path.join(FILES_DIR, `final_short_${productionId}_${i + 1}.mp4`);
+
+    try {
+      await retryPol.executeStage('Shorts_Extraction', async () =>
+        extractor.renderShort(masterPath, seg, shortPath)
+      );
+
+      const qcReport = await qc.validateShort(shortPath);
+      const stat = require('fs').statSync(shortPath);
+
+      shorts.push({
+        index:    i + 1,
+        shortPath,
+        score:    seg.score,
+        startSec: seg.startSec,
+        endSec:   seg.endSec,
+        sizeBytes: stat.size,
+        passed:   qcReport.passed,
+        qcReport,
+      });
+
+      await telemetry.track({
+        productionId,
+        stage: 'Shorts_Extraction',
+        provider: 'ffmpeg',
+        operation: 'short_render',
+        units: 1,
+      });
+    } catch (err) {
+      console.error(`[Shorts] Short ${i + 1} render failed: ${err.message}`);
+    }
+  }
+
+  const passedShorts = shorts.filter(s => s.passed);
+  const outputHash   = crypto.createHash('sha256')
+    .update(passedShorts.map(s => s.shortPath).join(','))
+    .digest('hex').slice(0, 16);
+
+  await sm.completeStage(productionId, 'Shorts_Extraction', {
+    outputHash,
+    metrics: { total: shorts.length, passed: passedShorts.length },
+  });
+
+  return { productionId, shorts: passedShorts, allShorts: shorts, outputHash };
+}
+
+module.exports = { runShorts };