@amg555/frameforge-mcp 0.0.0-stage → 2.3.0

package/src/workflows/ingest.js

@@ -0,0 +1,299 @@
+/**
+ * Workflow: Media Ingest
+ *
+ * Builds a production-ready scenes.json from user-supplied media files
+ * WITHOUT any LLM, research, or AI image generation.
+ *
+ * This is the "editor" mode entry point — the user provides:
+ *   - Video clips  (B-roll, screen recordings, gameplay, talking-head, stock)
+ *   - Images       (graphics, slides, photos, AI-generated images)
+ *   - Audio files  (pre-recorded voiceovers, podcasts, ElevenLabs output)
+ *   - Captions     (per-scene text overlays)
+ *   - A manifest   (JSON or array — see below)
+ *
+ * Output: scenes.json compatible with runAssets() → runRender() pipeline.
+ *
+ * CLI usage:
+ *   # Build scenes from a directory of clips
+ *   node src/cli/make.js --mode edit-only --media-dir ./my-clips
+ *
+ *   # Build from an explicit manifest JSON
+ *   node src/cli/make.js --mode edit-only --scenes-file ./my-scenes.json
+ *
+ *   # Supply a ready-made script JSON (skip research/script, keep AI images + TTS)
+ *   node src/cli/make.js --script-file ./approved-script.json
+ *
+ * Manifest format (scenes-file or media-dir auto-discovered):
+ * [
+ *   {
+ *     "narration": "The voice-over text for this scene.",  // used for TTS if no audio_path
+ *     "caption":   "CAPTION TEXT",                         // on-screen overlay
+ *     "video_path":  "./clips/scene1.mp4",                 // OR
+ *     "image_path":  "./images/scene1.png",                // OR generate (omit both)
+ *     "audio_path":  "./audio/scene1.mp3",                 // pre-recorded voiceover
+ *     "camera_hint": "zoom_in",                            // zoom_in|zoom_out|pan_left|pan_right|static|auto
+ *     "duration":    5.0,                                  // seconds (optional — auto-detected)
+ *     "music_mood":  "energetic"                           // tense|calm|energetic|mysterious|neutral|dramatic|humorous
+ *   }
+ * ]
+ *
+ * Auto-discovery (--media-dir):
+ *   Scans the directory for video/image/audio files and builds scenes automatically.
+ *   Pairs files with matching names: scene01.mp4 + scene01.mp3 + scene01.txt (caption).
+ *   Sorts numerically by filename. One scene per matched group.
+ */
+
+'use strict';
+
+const fs      = require('fs');
+const fsp     = require('fs').promises;
+const path    = require('path');
+const crypto  = require('crypto');
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const VIDEO_EXTS = new Set(['.mp4','.mov','.avi','.mkv','.webm','.m4v','.flv','.ts']);
+const IMAGE_EXTS = new Set(['.png','.jpg','.jpeg','.webp','.gif','.bmp','.tiff']);
+const AUDIO_EXTS = new Set(['.mp3','.m4a','.aac','.wav','.ogg','.flac','.opus']);
+const TEXT_EXTS  = new Set(['.txt','.caption','.srt']);
+
+const ALLOWED_CAMERAS = ['zoom_in','zoom_out','pan_left','pan_right','static','auto'];
+const ALLOWED_MOODS   = ['tense','calm','energetic','mysterious','neutral','dramatic','humorous'];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function extOf(filePath) {
+  return path.extname(filePath).toLowerCase();
+}
+
+function isVideo(f) { return VIDEO_EXTS.has(extOf(f)); }
+function isImage(f) { return IMAGE_EXTS.has(extOf(f)); }
+function isAudio(f) { return AUDIO_EXTS.has(extOf(f)); }
+function isText(f)  { return TEXT_EXTS.has(extOf(f));  }
+
+/** Strip extension and sort index from a filename, e.g. "scene_03_voice" → "scene_03" */
+function baseStem(filePath) {
+  return path.basename(filePath).replace(/\.[^.]+$/, '').replace(/_(voice|audio|image|clip|video)$/i, '');
+}
+
+/** Natural-sort comparator for filenames */
+function naturalSort(a, b) {
+  return a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+}
+
+// ── Auto-discovery ────────────────────────────────────────────────────────────
+
+/**
+ * Scan a directory and group media files into scenes by shared base name.
+ * e.g. scene01.mp4 + scene01.mp3 + scene01.txt → one scene
+ */
+function discoverScenesFromDir(mediaDir) {
+  const absDir = path.resolve(mediaDir);
+  if (!fs.existsSync(absDir)) {
+    throw new Error(`Media directory not found: ${absDir}`);
+  }
+
+  const files = fs.readdirSync(absDir)
+    .filter(f => {
+      const ext = path.extname(f).toLowerCase();
+      return VIDEO_EXTS.has(ext) || IMAGE_EXTS.has(ext) || AUDIO_EXTS.has(ext) || TEXT_EXTS.has(ext);
+    })
+    .sort(naturalSort);
+
+  // Group by stem
+  const groups = {};
+  for (const file of files) {
+    const stem = baseStem(path.join(absDir, file));
+    if (!groups[stem]) groups[stem] = {};
+    const full = path.join(absDir, file);
+    const ext  = extOf(full);
+    if (VIDEO_EXTS.has(ext))     groups[stem].video = full;
+    else if (IMAGE_EXTS.has(ext)) groups[stem].image = full;
+    else if (AUDIO_EXTS.has(ext)) groups[stem].audio = full;
+    else if (TEXT_EXTS.has(ext)) {
+      try { groups[stem].caption = fs.readFileSync(full, 'utf8').trim(); } catch {}
+    }
+  }
+
+  const sorted = Object.entries(groups).sort(([a], [b]) => naturalSort(a, b));
+  if (sorted.length === 0) {
+    throw new Error(`No media files found in: ${absDir}`);
+  }
+
+  return sorted.map(([stem, g], i) => ({
+    scene_id:    i + 1,
+    narration:   g.caption || '',
+    caption:     (g.caption || '').toUpperCase().slice(0, 40),
+    video_path:  g.video  || null,
+    image_path:  g.image  || null,
+    audio_path:  g.audio  || null,
+    camera_hint: 'auto',
+    music_mood:  'neutral',
+  }));
+}
+
+// ── Manifest normalizer ───────────────────────────────────────────────────────
+
+/**
+ * Normalise a raw scene from any input format to the FrameForge scene schema.
+ * Validates media file paths exist. Resolves relative paths against baseDir.
+ *
+ * @param {object} raw    Raw scene from user manifest
+ * @param {number} index  0-based index
+ * @param {string} baseDir  Base directory for relative path resolution
+ * @returns {object} Normalised scene
+ */
+function normaliseIngestScene(raw, index, baseDir = process.cwd()) {
+  const sceneId = raw.scene_id ?? raw.n ?? (index + 1);
+
+  function resolveMedia(p) {
+    if (!p) return null;
+    const resolved = path.isAbsolute(p) ? p : path.resolve(baseDir, p);
+    if (!fs.existsSync(resolved)) {
+      console.warn(`  ⚠️  Scene ${sceneId}: media file not found: ${resolved}`);
+      return null;
+    }
+    return resolved;
+  }
+
+  const videoPath = resolveMedia(raw.video_path || raw.videoPath || raw.clip);
+  const imagePath = resolveMedia(raw.image_path || raw.imagePath || raw.image);
+  const audioPath = resolveMedia(raw.audio_path || raw.audioPath || raw.audio || raw.voiceover);
+
+  const narration = String(raw.narration || raw.text || raw.script || '').trim();
+  const caption   = String(raw.caption   || raw.overlay || narration.slice(0, 40) || '').toUpperCase().trim().slice(0, 40);
+
+  return {
+    scene_id:       sceneId,
+    schema_version: '1.0.0',
+    narration,
+    caption,
+    // visual_description used by AI image generation — blank means no AI image needed
+    visual_description: String(raw.visual_description || raw.description || narration || '').trim(),
+    video_path:   videoPath,
+    image_path:   imagePath,
+    audio_path:   audioPath,
+    camera_hint:  ALLOWED_CAMERAS.includes(raw.camera_hint || raw.camera) ? (raw.camera_hint || raw.camera) : 'auto',
+    music_mood:   ALLOWED_MOODS.includes(raw.music_mood)   ? raw.music_mood   : 'neutral',
+    // Pass through any extra fields the user provided
+    character:    raw.character    || { character_id: 'none', pose: 'none', emotion: 'none' },
+    focal_point:  raw.focal_point  || { x: 0.5, y: 0.5, weight: 0.8 },
+    overlay:      raw.overlay      || { type: 'none' },
+    sound_effects: Array.isArray(raw.sound_effects) ? raw.sound_effects : [],
+    metadata:     raw.metadata     || { importance: 'medium', hook_potential: 0.5, standalone: false },
+    // Duration hint — used by renderer if provided (otherwise audio-driven)
+    duration:     typeof raw.duration === 'number' ? raw.duration : null,
+  };
+}
+
+// ── Main ingest function ──────────────────────────────────────────────────────
+
+/**
+ * Ingest user media into a production-ready scenes manifest.
+ *
+ * @param {{
+ *   productionId?:  string   — reuse existing production ID or auto-generate
+ *   scenesFile?:    string   — path to scenes.json / manifest JSON
+ *   mediaDir?:      string   — directory to auto-discover clips from
+ *   rawScenes?:     object[] — inline scene array (programmatic use)
+ *   outDir?:        string   — where to write the scenes manifest
+ * }} opts
+ * @returns {{ productionId: string, scenesFile: string, scenes: object[], sceneCount: number }}
+ */
+async function runIngest({ productionId, scenesFile, mediaDir, rawScenes, outDir } = {}) {
+  const filesDir = outDir || process.env.N8N_FILES_DIR || './output';
+  await fsp.mkdir(filesDir, { recursive: true });
+
+  // ── Step 1: Load/discover scenes ─────────────────────────────────────────
+  let rawList;
+  let baseDir = process.cwd();
+
+  if (rawScenes && Array.isArray(rawScenes) && rawScenes.length > 0) {
+    rawList = rawScenes;
+    console.log(`[Ingest] Using ${rawList.length} inline scenes`);
+  } else if (scenesFile) {
+    const absPath = path.resolve(process.cwd(), scenesFile);
+    if (!fs.existsSync(absPath)) throw new Error(`Scenes file not found: ${absPath}`);
+    const content = fs.readFileSync(absPath, 'utf8');
+    const parsed  = JSON.parse(content);
+    rawList = Array.isArray(parsed) ? parsed : (parsed.scenes || parsed.data || []);
+    baseDir = path.dirname(absPath);
+    console.log(`[Ingest] Loaded ${rawList.length} scene(s) from: ${absPath}`);
+  } else if (mediaDir) {
+    rawList = discoverScenesFromDir(mediaDir);
+    baseDir = path.resolve(mediaDir);
+    console.log(`[Ingest] Auto-discovered ${rawList.length} scene(s) from: ${mediaDir}`);
+  } else {
+    throw new Error('runIngest requires one of: scenesFile, mediaDir, or rawScenes');
+  }
+
+  if (rawList.length === 0) {
+    throw new Error('No scenes found in the provided input');
+  }
+
+  // ── Step 2: Normalise ─────────────────────────────────────────────────────
+  const scenes = rawList.map((raw, i) => normaliseIngestScene(raw, i, baseDir));
+  const validScenes = scenes.filter(s => s.narration || s.video_path || s.image_path || s.audio_path);
+
+  if (validScenes.length === 0) {
+    throw new Error('All scenes are empty — each scene needs at least narration, a video, an image, or an audio file');
+  }
+
+  // ── Step 3: Assign productionId and register with state machine ──────────
+  const pid = productionId || `ingest_${crypto.randomBytes(4).toString('hex')}_${Date.now()}`;
+
+  // Register with the state machine so downstream stages (Assets, Render) can
+  // call startStage() without hitting "Production not found".
+  const stateDir = path.join(filesDir, 'state');
+  await fsp.mkdir(stateDir, { recursive: true });
+  const stateFile = path.join(stateDir, `${pid}.json`);
+  if (!fs.existsSync(stateFile)) {
+    const record = {
+      productionId: pid,
+      status: 'QUEUED',
+      pipelineVersion: '2.0.0',
+      schemaVersion:   '1.0.0',
+      topic:      scenesFile || mediaDir || 'ingest',
+      createdAt:  new Date().toISOString(),
+      startedAt:  null,
+      completedAt: null,
+      configHash: crypto.createHash('sha256').update(pid).digest('hex').slice(0, 16),
+      stages: {},
+      metadata: {},
+    };
+    fs.writeFileSync(stateFile, JSON.stringify(record, null, 2), 'utf8');
+  }
+
+  // ── Step 4: Write scenes manifest ────────────────────────────────────────
+  const outPath = path.join(filesDir, `${pid}-scenes.json`);
+  const manifest = {
+    productionId: pid,
+    createdAt:    new Date().toISOString(),
+    sceneCount:   validScenes.length,
+    mode:         'ingest',
+    scenes:       validScenes,
+  };
+  fs.writeFileSync(outPath, JSON.stringify(manifest, null, 2), 'utf8');
+  console.log(`[Ingest] ✅  Scenes manifest saved: ${outPath}`);
+
+  // Print summary
+  const withVideo  = validScenes.filter(s => s.video_path).length;
+  const withImage  = validScenes.filter(s => s.image_path && !s.video_path).length;
+  const withAI     = validScenes.filter(s => !s.video_path && !s.image_path).length;
+  const withAudio  = validScenes.filter(s => s.audio_path).length;
+  const withTTS    = validScenes.filter(s => !s.audio_path && s.narration).length;
+  console.log(`[Ingest]    Scenes: ${validScenes.length} total`);
+  console.log(`[Ingest]    Video clips: ${withVideo}  |  User images: ${withImage}  |  AI-generate: ${withAI}`);
+  console.log(`[Ingest]    Pre-recorded audio: ${withAudio}  |  TTS needed: ${withTTS}`);
+  if (withAI > 0)   console.log(`[Ingest]    ℹ️   ${withAI} scene(s) will use AI image generation (remove --no-images to skip)`);
+  if (withTTS > 0)  console.log(`[Ingest]    ℹ️   ${withTTS} scene(s) will use TTS synthesis (remove --no-tts to skip)`);
+
+  return {
+    productionId:  pid,
+    scenesFile:    outPath,
+    scenes:        validScenes,
+    sceneCount:    validScenes.length,
+    stats: { withVideo, withImage, withAI, withAudio, withTTS },
+  };
+}
+
+module.exports = { runIngest, normaliseIngestScene, discoverScenesFromDir };

package/src/workflows/packaging.js

@@ -0,0 +1,156 @@
+/**
+ * Workflow E — Packaging
+ * Task #33: collect master + shorts + thumbnail + metadata + manifest + QC report
+ *           into one complete production package ready for human review or publish.
+ *
+ * Returns: { productionId, packageDir, manifest }
+ */
+'use strict';
+
+const path   = require('path');
+const crypto = require('crypto');
+const fsSync = require('fs');
+const fs     = require('fs').promises;
+const { StateMachine } = require('../pipeline/state-machine');
+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`;
+
+/**
+ * Assemble a production package from all rendered artefacts.
+ *
+ * @param {{
+ *   productionId: string,
+ *   masterPath: string,
+ *   shorts?: object[],
+ *   scenes: object[],
+ *   title: string,
+ *   description: string,
+ *   tags?: string[],
+ *   thumbnailPrompt?: string,
+ *   qcReport: object,
+ *   totalWords?: number,
+ * }} opts
+ */
+async function runPackaging({
+  productionId,
+  masterPath,
+  shorts          = [],
+  scenes          = [],
+  title           = '',
+  description     = '',
+  tags            = [],
+  thumbnailPrompt = '',
+  qcReport,
+  totalWords      = 0,
+}) {
+  const sm        = new StateMachine({ mode: 'file', stateDir: STATE_DIR });
+  const telemetry = new Telemetry({ mode: 'file', logPath: `${FILES_DIR}/usage.ndjson` });
+
+  await sm.init();
+  await telemetry.init();
+  await sm.startStage(productionId, 'Packaging');
+
+  // Create package directory
+  const pkgDir = path.join(FILES_DIR, 'packages', productionId);
+  await fs.mkdir(pkgDir, { recursive: true });
+
+  // ── Copy master video ───────────────────────────────────────────────────
+  const masterDest = path.join(pkgDir, 'master.mp4');
+  await fs.copyFile(masterPath, masterDest).catch(() => {});
+
+  // ── Copy shorts ────────────────────────────────────────────────────────
+  const shortsMeta = [];
+  for (let i = 0; i < shorts.length; i++) {
+    const s = shorts[i];
+    if (!s.shortPath || !fsSync.existsSync(s.shortPath)) continue;
+    const shortDest = path.join(pkgDir, `short_${i + 1}.mp4`);
+    await fs.copyFile(s.shortPath, shortDest).catch(() => {});
+    shortsMeta.push({
+      index:    i + 1,
+      path:     shortDest,
+      score:    s.score,
+      startSec: s.startSec,
+      endSec:   s.endSec,
+      sizeBytes: s.sizeBytes,
+      qcPassed:  s.passed,
+    });
+  }
+
+  // ── Compute content hash ────────────────────────────────────────────────
+  const masterStat   = fsSync.existsSync(masterDest) ? fsSync.statSync(masterDest) : { size: 0 };
+  const contentHash  = crypto.createHash('sha256')
+    .update(`${productionId}:${masterStat.size}:${scenes.length}`)
+    .digest('hex').slice(0, 16);
+
+  // ── Build manifest ───────────────────────────────────────────────────────
+  const manifest = {
+    schemaVersion:   '1.0.0',
+    productionId,
+    contentHash,
+    createdAt:       new Date().toISOString(),
+    master: {
+      path:      masterDest,
+      sizeBytes: masterStat.size,
+      qcPassed:  qcReport?.passed ?? false,
+    },
+    shorts:           shortsMeta,
+    sceneCount:       scenes.length,
+    totalWords,
+    metadata: {
+      title,
+      description,
+      tags,
+      thumbnailPrompt,
+    },
+    qcSummary: {
+      passed:   qcReport?.passed,
+      checks:   (qcReport?.checks || []).map(c => ({ name: c.name, passed: c.passed, actual: c.actual })),
+    },
+    // Risk-based publish decision
+    publishDecision: _publishDecision(qcReport, scenes),
+  };
+
+  // ── Write manifest JSON ──────────────────────────────────────────────────
+  const manifestPath = path.join(pkgDir, 'manifest.json');
+  await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2), 'utf8');
+
+  // ── Write video description file ────────────────────────────────────────
+  const descLines = [
+    title,
+    '',
+    description,
+    '',
+    tags.length ? `Tags: ${tags.slice(0, 10).join(', ')}` : '',
+    '',
+    '---',
+    'Produced with autonomous AI video pipeline.',
+  ];
+  await fs.writeFile(path.join(pkgDir, 'description.md'), descLines.join('\n'), 'utf8');
+
+  await sm.completeStage(productionId, 'Packaging', {
+    outputHash: contentHash,
+    metrics:    { sizeBytes: masterStat.size, shortCount: shortsMeta.length },
+  });
+  await telemetry.track({ productionId, stage: 'Packaging', provider: 'local', operation: 'package_assembly', units: 1 });
+
+  return { productionId, packageDir: pkgDir, manifestPath, manifest };
+}
+
+/**
+ * Determine publish decision based on QC report and scene risk levels.
+ * LOW risk + all gates pass → AUTO_PUBLISH
+ * MEDIUM risk → SAMPLE_REVIEW
+ * HIGH risk or failed gates → MANDATORY_REVIEW
+ */
+function _publishDecision(qcReport, scenes) {
+  if (!qcReport?.passed) return 'MANDATORY_REVIEW';
+  const highRisk = scenes.filter(s => s.metadata?.importance === 'critical').length;
+  if (highRisk === 0) return 'AUTO_PUBLISH';
+  if (highRisk <= 3)  return 'SAMPLE_REVIEW';
+  return 'MANDATORY_REVIEW';
+}
+
+module.exports = { runPackaging };

package/src/workflows/publishing.js

@@ -0,0 +1,206 @@
+/**
+ * Workflow F — Publishing
+ *
+ * Delivers a finished production package to one or more output channels.
+ *
+ * Built-in channels:
+ *   file    — copy the master + shorts to an output directory (default)
+ *   webhook — POST a JSON summary to a configurable HTTP endpoint
+ *
+ * All platform-specific delivery (Telegram, YouTube, S3, etc.) is handled
+ * externally via the `webhook` channel or the `external_platform_call` MCP tool.
+ * This keeps the core pipeline free of platform SDK dependencies.
+ *
+ * Returns: { productionId, results, publishDecision }
+ */
+'use strict';
+
+const path   = require('path');
+const fsSync = require('fs');
+const https  = require('https');
+const http   = require('http');
+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`;
+
+/**
+ * @param {{
+ *   productionId: string,
+ *   manifest:     object,
+ *   channels?:    string[],    // 'file' | 'webhook' — default ['file']
+ *   outputDir?:   string,      // destination for 'file' channel (default: FILES_DIR/published)
+ *   webhookUrl?:  string,      // override PUBLISH_WEBHOOK_URL env var
+ *   force?:       boolean,
+ * }} opts
+ */
+async function runPublishing({ productionId, manifest, channels = ['file'], outputDir, webhookUrl, force = false }) {
+  const sm        = new StateMachine({ mode: 'file', stateDir: STATE_DIR });
+  const retryPol  = new RetryPolicy({ maxAttempts: 3, baseDelayMs: 15000 });
+  const telemetry = new Telemetry({ mode: 'file', logPath: `${FILES_DIR}/usage.ndjson` });
+
+  await sm.init();
+  await telemetry.init();
+
+  const decision = manifest?.publishDecision || 'AUTO_PUBLISH';
+
+  // Honour the publish decision gate
+  if (decision === 'MANDATORY_REVIEW' && !force) {
+    console.warn(`[Publishing] ${productionId} requires MANDATORY_REVIEW — skipping publish. Set force=true to override.`);
+    return { productionId, results: {}, publishDecision: decision, skipped: true, reason: 'mandatory_review_pending' };
+  }
+  if (decision === 'SAMPLE_REVIEW' && !force) {
+    console.warn(`[Publishing] ${productionId} flagged for SAMPLE_REVIEW — logging for human check.`);
+    await _logForReview(productionId, manifest);
+  }
+
+  await sm.startStage(productionId, 'Publishing');
+
+  const masterPath = manifest?.master?.path;
+  if (!masterPath || !fsSync.existsSync(masterPath)) {
+    throw new Error(`Master video not found at: ${masterPath}`);
+  }
+
+  const title       = manifest?.metadata?.title       || '';
+  const description = manifest?.metadata?.description || '';
+  const results = {};
+
+  // ── File channel ────────────────────────────────────────────────────────────
+  if (channels.includes('file')) {
+    results.file = await retryPol.executeStage('Publishing', async () => {
+      const dest = outputDir || path.join(FILES_DIR, 'published');
+      fsSync.mkdirSync(dest, { recursive: true });
+
+      const ext      = path.extname(masterPath) || '.mp4';
+      const safeName = (productionId || 'video').replace(/[^a-zA-Z0-9_-]/g, '_');
+      const destPath = path.join(dest, `${safeName}${ext}`);
+
+      fsSync.copyFileSync(masterPath, destPath);
+
+      // Copy shorts if present
+      const copiedShorts = [];
+      for (const short of (manifest?.shorts || [])) {
+        if (!short.path || !fsSync.existsSync(short.path)) continue;
+        const shortDest = path.join(dest, `${safeName}_short_${short.index || copiedShorts.length + 1}${path.extname(short.path) || '.mp4'}`);
+        fsSync.copyFileSync(short.path, shortDest);
+        copiedShorts.push(shortDest);
+      }
+
+      return {
+        ok:       true,
+        destPath,
+        shorts:   copiedShorts,
+        sizeBytes: fsSync.statSync(destPath).size,
+      };
+    });
+  }
+
+  // ── Webhook channel ─────────────────────────────────────────────────────────
+  if (channels.includes('webhook')) {
+    const url = webhookUrl || process.env.PUBLISH_WEBHOOK_URL;
+    if (!url) {
+      results.webhook = { ok: false, reason: 'PUBLISH_WEBHOOK_URL not set — configure it in .env or pass webhookUrl' };
+    } else {
+      results.webhook = await retryPol.executeStage('Publishing', async () => {
+        const payload = JSON.stringify({
+          productionId,
+          title,
+          description,
+          masterPath,
+          sizeBytes:  fsSync.statSync(masterPath).size,
+          shorts:     (manifest?.shorts || []).map(s => ({ index: s.index, path: s.path })),
+          publishedAt: new Date().toISOString(),
+        });
+
+        const response = await _httpPost(url, payload, {
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(payload),
+        });
+
+        return { ok: true, status: response.status, body: response.body.slice(0, 500) };
+      }).catch(err => ({ ok: false, error: err.message }));
+    }
+  }
+
+  await sm.completeStage(productionId, 'Publishing', {});
+  await sm.transitionProduction(productionId, 'SUCCEEDED').catch(() => {});
+  await telemetry.track({ productionId, stage: 'Publishing', provider: 'local', operation: 'video_delivery', units: 1 });
+
+  return { productionId, results, publishDecision: decision };
+}
+
+async function _logForReview(productionId, manifest) {
+  const reviewLog = path.join(FILES_DIR, 'review_queue.ndjson');
+  const entry = JSON.stringify({ productionId, manifest, queuedAt: new Date().toISOString() }) + '\n';
+  fsSync.appendFileSync(reviewLog, entry, 'utf8');
+}
+
+/**
+ * Guard against SSRF: reject webhook URLs that resolve to RFC-1918 / link-local /
+ * loopback ranges. These are unroutable from the public internet but reachable
+ * from the server process, so a confused-deputy attack could exfiltrate cloud
+ * metadata or probe internal services.
+ *
+ * Only the hostname portion of the URL is checked — we don't perform a DNS
+ * resolution (that would be async and incomplete). Literal IP addresses in the
+ * URL cover the common metadata-endpoint pattern (169.254.169.254, 127.x, 10.x,
+ * 192.168.x, 172.16-31.x).
+ */
+function _assertSafeWebhookUrl(rawUrl) {
+  let parsed;
+  try { parsed = new URL(rawUrl); }
+  catch { throw new Error(`Invalid webhook URL: ${rawUrl}`); }
+
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`Webhook URL must use http: or https: — got: ${parsed.protocol}`);
+  }
+
+  const host = parsed.hostname.toLowerCase();
+
+  // Reject literal private / loopback / link-local IP addresses:
+  // 127.x (loopback), 10.x / 172.16-31.x / 192.168.x (RFC-1918),
+  // 169.254.x (link-local / AWS metadata), ::1 / fc / fe80 (IPv6 private).
+  const PRIVATE_RE = /^(127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|192\.168\.\d+\.\d+|169\.254\.\d+\.\d+|::1|fc[\da-f]{2}:|fe80:)/i;
+
+  if (PRIVATE_RE.test(host)) {
+    throw new Error(`Webhook URL resolves to a private/loopback address — SSRF blocked: ${host}`);
+  }
+
+  // Reject bare "localhost" and common localhost aliases
+  if (host === 'localhost' || host.endsWith('.localhost') || host === '0.0.0.0' || host === '[::1]') {
+    throw new Error(`Webhook URL must not target localhost — SSRF blocked: ${host}`);
+  }
+}
+
+/** Minimal HTTP/HTTPS POST helper — no external dependencies */
+function _httpPost(url, body, headers = {}) {
+  _assertSafeWebhookUrl(url);
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const lib    = parsed.protocol === 'https:' ? https : http;
+    const req    = lib.request({
+      hostname: parsed.hostname,
+      port:     parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+      path:     parsed.pathname + parsed.search,
+      method:   'POST',
+      headers,
+    }, (res) => {
+      const chunks = [];
+      res.on('data', d => chunks.push(d));
+      res.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        if (res.statusCode >= 400) return reject(new Error(`Webhook HTTP ${res.statusCode}: ${body.slice(0, 200)}`));
+        resolve({ status: res.statusCode, body });
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(30000, () => { req.destroy(); reject(new Error('Webhook timeout')); });
+    req.write(body);
+    req.end();
+  });
+}
+
+module.exports = { runPublishing, _assertSafeWebhookUrl };