@amg555/frameforge-mcp 0.0.0-stage → 2.3.1

package/src/mcp-server/stdio.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * FrameForge MCP Server — Local Stdio Transport
+ *
+ * Implements standard stdio JSON-RPC transport for MCP 2024-11-05.
+ * Used for zero-config integration with Claude Code, Cursor, Windsurf, Codex, opencode.
+ *
+ * When run via `npx frameforge-mcp`, keys are loaded from ~/.frameforge/config.json
+ * (written once by `npx frameforge-setup`). Falls back to .env in cwd.
+ *
+ * IDE config (npx — no clone required):
+ * {
+ *   "mcpServers": {
+ *     "frameforge": {
+ *       "command": "npx",
+ *       "args": ["-y", "frameforge-mcp"]
+ *     }
+ *   }
+ * }
+ *
+ * IDE config (local clone):
+ * {
+ *   "mcpServers": {
+ *     "frameforge": {
+ *       "command": "node",
+ *       "args": ["/absolute/path/to/frameforge/src/mcp-server/stdio.js"]
+ *     }
+ *   }
+ * }
+ */
+
+'use strict';
+
+// Load config BEFORE requiring server.js so env vars are set when providers initialise
+require('../config/load-config').loadConfig();
+
+const readline = require('readline');
+const { handleMCPRequest } = require('./server');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout,
+  terminal: false,
+});
+
+process.stderr.write('[FrameForge Stdio MCP] Server initialized. Listening on stdin...\n');
+
+rl.on('line', async line => {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+
+  let request;
+  try {
+    request = JSON.parse(trimmed);
+  } catch (err) {
+    const errorResponse = {
+      jsonrpc: '2.0',
+      id: null,
+      error: { code: -32700, message: `Parse error: ${err.message}` },
+    };
+    process.stdout.write(JSON.stringify(errorResponse) + '\n');
+    return;
+  }
+
+  try {
+    if (Array.isArray(request)) {
+      const responses = await Promise.all(request.map(r => handleMCPRequest(r)));
+      const filtered = responses.filter(r => r !== null);
+      if (filtered.length > 0) {
+        process.stdout.write(JSON.stringify(filtered) + '\n');
+      }
+    } else {
+      const response = await handleMCPRequest(request);
+      if (response !== null) {
+        process.stdout.write(JSON.stringify(response) + '\n');
+      }
+    }
+  } catch (err) {
+    process.stderr.write(`[FrameForge Stdio MCP] Request error: ${err.message}\n`);
+    const errorResponse = {
+      jsonrpc: '2.0',
+      id: request.id || null,
+      error: { code: -32603, message: `Internal server error: ${err.message}` },
+    };
+    process.stdout.write(JSON.stringify(errorResponse) + '\n');
+  }
+});

package/src/pipeline/artifact-manifest.js

@@ -0,0 +1,323 @@
+/**
+ * Artifact Manifest — Task #24
+ *
+ * Every production run creates a deterministic, content-addressed manifest
+ * so the pipeline can:
+ *   1. Skip re-rendering unchanged scenes (idempotency)
+ *   2. Verify artifact integrity on resume
+ *   3. Build Artifact Retention Rules (#27)
+ *   4. Feed cost tracking (telemetry.js)
+ *
+ * Manifest structure (written to artifacts/<production_id>/manifest.json):
+ * {
+ *   "schema_version": "1.0.0",
+ *   "production_id": "prod_...",
+ *   "pipeline_version": "1.0.0",
+ *   "narration_hash": "<sha256 of full script text>",
+ *   "config_hash": "<sha256 of env+provider config>",
+ *   "created_at": "<ISO 8601>",
+ *   "scenes": [
+ *     {
+ *       "index": 0,
+ *       "scene_hash": "<sha256 of scene JSON>",
+ *       "image_path": "...",
+ *       "image_hash": "<sha256 of image file>",
+ *       "voice_path": "...",
+ *       "voice_hash": "<sha256 of voice file>",
+ *       "rendered_path": "...",
+ *       "rendered_hash": "<sha256 of rendered scene>",
+ *       "status": "pending|complete|failed"
+ *     }
+ *   ],
+ *   "master": {
+ *     "path": "...",
+ *     "hash": "...",
+ *     "duration_sec": 0,
+ *     "size_bytes": 0,
+ *     "quality_passed": false
+ *   },
+ *   "shorts": [],
+ *   "thumbnail": { "path": "...", "hash": "..." },
+ *   "audio_config": {
+ *     "provider": "edge-tts",
+ *     "voice": "en-US-GuyNeural",
+ *     "music_path": null,
+ *     "lufs_target": -14,
+ *     "true_peak_max": -1
+ *   },
+ *   "telemetry": {
+ *     "total_cost_usd": 0,
+ *     "stage_durations_ms": {}
+ *   }
+ * }
+ *
+ * Hashes are computed lazily (file hash only when file exists).
+ * The manifest file itself is re-written on every stage completion.
+ */
+
+'use strict';
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+
+const MANIFEST_SCHEMA_VERSION = '1.0.0';
+const PIPELINE_VERSION        = process.env.PIPELINE_VERSION || '1.0.0';
+
+class ArtifactManifest {
+  /**
+   * @param {{ productionId: string, artifactsDir?: string }} opts
+   */
+  constructor({ productionId, artifactsDir = require('path').join(process.env.N8N_FILES_DIR || require('path').join(require('os').homedir(), '.frameforge-files'), 'artifacts') } = {}) {
+    if (!productionId) throw new Error('productionId is required');
+    this.productionId  = productionId;
+    this.dir           = path.join(artifactsDir, productionId);
+    this.manifestPath  = path.join(this.dir, 'manifest.json');
+    this._data         = null;
+  }
+
+  // ── Lifecycle ──────────────────────────────────────────────────────────────
+
+  /**
+   * Create a new manifest for a fresh production run.
+   * Returns the manifest data object.
+   */
+  create({ narrationText, configSnapshot, scenes = [], audioConfig = {} } = {}) {
+    fs.mkdirSync(this.dir, { recursive: true });
+    this._data = {
+      schema_version:  MANIFEST_SCHEMA_VERSION,
+      production_id:   this.productionId,
+      pipeline_version: PIPELINE_VERSION,
+      narration_hash:  narrationText ? _sha256(narrationText) : null,
+      config_hash:     configSnapshot ? _sha256(JSON.stringify(configSnapshot)) : null,
+      created_at:      new Date().toISOString(),
+      updated_at:      new Date().toISOString(),
+      scenes:          scenes.map((s, i) => this._sceneEntry(s, i)),
+      master:          { path: null, hash: null, duration_sec: 0, size_bytes: 0, quality_passed: false },
+      shorts:          [],
+      thumbnail:       { path: null, hash: null },
+      audio_config:    {
+        provider:      process.env.PROVIDER_TTS || 'edge-tts',
+        voice:         process.env.TTS_VOICE || 'en-US-GuyNeural',
+        music_path:    null,
+        lufs_target:   -14,
+        true_peak_max: -1,
+        ...audioConfig,
+      },
+      telemetry: {
+        total_cost_usd:     0,
+        stage_durations_ms: {},
+      },
+    };
+    this._write();
+    return this._data;
+  }
+
+  /**
+   * Load an existing manifest from disk (for resume / idempotency checks).
+   * Returns null if no manifest exists.
+   */
+  load() {
+    if (!fs.existsSync(this.manifestPath)) return null;
+    try {
+      this._data = JSON.parse(fs.readFileSync(this.manifestPath, 'utf8'));
+      return this._data;
+    } catch (err) {
+      throw new Error(`Corrupt manifest at ${this.manifestPath}: ${err.message}`);
+    }
+  }
+
+  /**
+   * Load or create — the canonical entry point for a production run.
+   * If an existing manifest exists AND its narration_hash matches → resume.
+   * Otherwise → create new (or overwrite stale).
+   */
+  loadOrCreate({ narrationText, configSnapshot, scenes = [], audioConfig = {} } = {}) {
+    const existing = this.load();
+    if (existing) {
+      const incomingHash = narrationText ? _sha256(narrationText) : null;
+      if (incomingHash && existing.narration_hash === incomingHash) {
+        // Same narration — resume
+        return { manifest: this._data, resumed: true };
+      }
+      // Different narration — overwrite
+    }
+    return { manifest: this.create({ narrationText, configSnapshot, scenes, audioConfig }), resumed: false };
+  }
+
+  // ── Scene artifact updates ─────────────────────────────────────────────────
+
+  /**
+   * Mark a scene's image as generated.
+   */
+  setSceneImage(sceneIndex, imagePath) {
+    const scene = this._getScene(sceneIndex);
+    scene.image_path = imagePath;
+    scene.image_hash = fs.existsSync(imagePath) ? _fileHash(imagePath) : null;
+    this._touch();
+    return this;
+  }
+
+  /**
+   * Mark a scene's voice track as generated.
+   */
+  setSceneVoice(sceneIndex, voicePath) {
+    const scene = this._getScene(sceneIndex);
+    scene.voice_path = voicePath;
+    scene.voice_hash = fs.existsSync(voicePath) ? _fileHash(voicePath) : null;
+    this._touch();
+    return this;
+  }
+
+  /**
+   * Mark a scene's rendered MP4 as complete.
+   */
+  setSceneRendered(sceneIndex, renderedPath) {
+    const scene = this._getScene(sceneIndex);
+    scene.rendered_path = renderedPath;
+    scene.rendered_hash = fs.existsSync(renderedPath) ? _fileHash(renderedPath) : null;
+    scene.status = 'complete';
+    this._touch();
+    return this;
+  }
+
+  setSceneFailed(sceneIndex, reason) {
+    const scene = this._getScene(sceneIndex);
+    scene.status = 'failed';
+    scene.fail_reason = reason;
+    this._touch();
+    return this;
+  }
+
+  // ── Master + shorts ────────────────────────────────────────────────────────
+
+  setMaster(masterPath, { durationSec = 0, qualityPassed = false } = {}) {
+    const stat = fs.existsSync(masterPath) ? fs.statSync(masterPath) : null;
+    this._data.master = {
+      path:           masterPath,
+      hash:           stat ? _fileHash(masterPath) : null,
+      duration_sec:   durationSec,
+      size_bytes:     stat ? stat.size : 0,
+      quality_passed: qualityPassed,
+    };
+    this._touch();
+    return this;
+  }
+
+  addShort({ path: shortPath, durationSec = 0, qualityPassed = false } = {}) {
+    const stat = fs.existsSync(shortPath) ? fs.statSync(shortPath) : null;
+    this._data.shorts.push({
+      path:           shortPath,
+      hash:           stat ? _fileHash(shortPath) : null,
+      duration_sec:   durationSec,
+      size_bytes:     stat ? stat.size : 0,
+      quality_passed: qualityPassed,
+    });
+    this._touch();
+    return this;
+  }
+
+  setThumbnail(thumbnailPath) {
+    this._data.thumbnail = {
+      path: thumbnailPath,
+      hash: fs.existsSync(thumbnailPath) ? _fileHash(thumbnailPath) : null,
+    };
+    this._touch();
+    return this;
+  }
+
+  // ── Telemetry ─────────────────────────────────────────────────────────────
+
+  recordStageDuration(stage, durationMs) {
+    this._data.telemetry.stage_durations_ms[stage] = durationMs;
+    this._touch();
+    return this;
+  }
+
+  addCost(costUsd) {
+    this._data.telemetry.total_cost_usd =
+      parseFloat((this._data.telemetry.total_cost_usd + costUsd).toFixed(6));
+    this._touch();
+    return this;
+  }
+
+  // ── Idempotency checks ────────────────────────────────────────────────────
+
+  /**
+   * Returns true if the scene at sceneIndex has a valid rendered MP4 on disk.
+   * Used to skip re-rendering on resume.
+   */
+  isSceneComplete(sceneIndex) {
+    const scene = this._data?.scenes?.[sceneIndex];
+    if (!scene || scene.status !== 'complete') return false;
+    return !!scene.rendered_path && fs.existsSync(scene.rendered_path)
+      && fs.statSync(scene.rendered_path).size > 50000;
+  }
+
+  /**
+   * Returns true if master exists, has correct hash, and passed quality gate.
+   */
+  isMasterComplete() {
+    const m = this._data?.master;
+    if (!m?.path || !m.quality_passed) return false;
+    if (!fs.existsSync(m.path)) return false;
+    return _fileHash(m.path) === m.hash;
+  }
+
+  // ── Getters ───────────────────────────────────────────────────────────────
+
+  get data() { return this._data; }
+  get scenes() { return this._data?.scenes || []; }
+  get master() { return this._data?.master || null; }
+  get shorts() { return this._data?.shorts || []; }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  _sceneEntry(sceneData, index) {
+    return {
+      index,
+      scene_hash:    _sha256(JSON.stringify(sceneData)),
+      image_path:    null,
+      image_hash:    null,
+      voice_path:    null,
+      voice_hash:    null,
+      rendered_path: null,
+      rendered_hash: null,
+      status:        'pending',
+      fail_reason:   null,
+    };
+  }
+
+  _getScene(index) {
+    if (!this._data) throw new Error('Manifest not loaded — call create() or load() first');
+    const scene = this._data.scenes[index];
+    if (!scene) throw new Error(`Scene index ${index} not in manifest (${this._data.scenes.length} scenes)`);
+    return scene;
+  }
+
+  _touch() {
+    if (this._data) {
+      this._data.updated_at = new Date().toISOString();
+      this._write();
+    }
+  }
+
+  _write() {
+    fs.mkdirSync(this.dir, { recursive: true });
+    fs.writeFileSync(this.manifestPath, JSON.stringify(this._data, null, 2), 'utf8');
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function _sha256(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function _fileHash(filePath) {
+  try {
+    return crypto.createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+  } catch { return null; }
+}
+
+module.exports = { ArtifactManifest };

package/src/pipeline/artifact-retention.js

@@ -0,0 +1,189 @@
+/**
+ * Artifact Retention Rules — Task #27
+ *
+ * Defines which artifacts to keep permanently, for 30 days, or delete immediately.
+ * Runs as part of post-publish cleanup and the nightly cron sweep.
+ *
+ * Policy:
+ *   PERMANENT   — master MP4, shorts, thumbnails, manifests, character assets
+ *   30_DAY      — intermediate scene renders (scene_N_out.mp4), concat files, TTS audio
+ *   DELETE_NOW  — temp files from failed runs, raw_concat before mixing
+ *
+ * Usage (called after successful publish):
+ *   const { applyRetentionRules } = require('./artifact-retention');
+ *   applyRetentionRules({ productionId, filesDir, manifestData });
+ *
+ * Usage (nightly sweep):
+ *   const { sweepExpiredIntermediates } = require('./artifact-retention');
+ *   sweepExpiredIntermediates({ filesDir, dryRun: false });
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const RETENTION_DAYS  = parseInt(process.env.RETENTION_DAYS_INTERMEDIATES || '30', 10);
+const MS_PER_DAY      = 24 * 60 * 60 * 1000;
+
+// ── Permanent file patterns ───────────────────────────────────────────────────
+// These are never deleted by the sweep.
+const PERMANENT_PATTERNS = [
+  /final_video_.*\.mp4$/,   // master video
+  /short_.*\.mp4$/,         // shorts
+  /thumbnail_.*\.(jpg|png|webp)$/,
+  /manifest\.json$/,        // production manifests
+  /assets\//,               // character/prop assets
+];
+
+// ── 30-day intermediate patterns ─────────────────────────────────────────────
+// Deleted after RETENTION_DAYS days.
+const INTERMEDIATE_PATTERNS = [
+  /scene_\d+_out\.mp4$/,
+  /scene_\d+_voice\.(m4a|mp3|aac)$/,
+  /scene_\d+_image\.(png|jpg|webp)$/,
+  /concat_main\.txt$/,
+  /raw_concat_.*\.mp4$/,
+];
+
+// ── Delete-immediately patterns ───────────────────────────────────────────────
+// Cleaned up right after stage completion.
+const TEMP_PATTERNS = [
+  /_raw\.mp3$/,
+  /\.tmp$/,
+  /\.part$/,
+];
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Apply retention rules after a successful production run.
+ * Deletes temp files immediately; schedules intermediates for 30-day sweep
+ * by writing a .retention file alongside each intermediate.
+ *
+ * @param {{ productionId: string, filesDir: string, dryRun?: boolean }} opts
+ * @returns {{ deleted: string[], tagged: string[] }}
+ */
+function applyRetentionRules({ productionId, filesDir, dryRun = false }) {
+  const vdir     = path.join(filesDir, 'video_tmp');
+  const deleted  = [];
+  const tagged   = [];
+
+  // 1. Delete temp files immediately
+  for (const dir of [filesDir, vdir]) {
+    if (!fs.existsSync(dir)) continue;
+    for (const file of _listFiles(dir)) {
+      if (TEMP_PATTERNS.some(p => p.test(file))) {
+        if (!dryRun) _safeUnlink(file);
+        deleted.push(file);
+      }
+    }
+  }
+
+  // 2. Tag intermediates with a .retention file (mtime-based expiry)
+  if (fs.existsSync(vdir)) {
+    for (const file of _listFiles(vdir)) {
+      if (INTERMEDIATE_PATTERNS.some(p => p.test(file))) {
+        const tagPath = file + '.retention';
+        if (!dryRun && !fs.existsSync(tagPath)) {
+          const tag = {
+            production_id:  productionId,
+            created_at:     new Date().toISOString(),
+            expires_at:     new Date(Date.now() + RETENTION_DAYS * MS_PER_DAY).toISOString(),
+            policy:         '30_day',
+          };
+          fs.writeFileSync(tagPath, JSON.stringify(tag), 'utf8');
+        }
+        tagged.push(file);
+      }
+    }
+  }
+
+  return { deleted, tagged };
+}
+
+/**
+ * Sweep all intermediates whose .retention expiry has passed.
+ * Safe to run as a nightly cron.
+ *
+ * @param {{ filesDir: string, dryRun?: boolean }} opts
+ * @returns {{ swept: string[], skipped: number }}
+ */
+function sweepExpiredIntermediates({ filesDir, dryRun = false }) {
+  const swept   = [];
+  let   skipped = 0;
+  const now     = Date.now();
+
+  // Scan all subdirectories under filesDir (recursive — productions nest several levels deep)
+  const dirs = [];
+  const _walkDirs = (dir) => {
+    dirs.push(dir);
+    try {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isDirectory()) _walkDirs(path.join(dir, entry.name));
+      }
+    } catch { /* permission error or disappeared — skip */ }
+  };
+  _walkDirs(filesDir);
+
+  for (const dir of dirs) {
+    if (!fs.existsSync(dir)) continue;
+    let entries;
+    try { entries = fs.readdirSync(dir); } catch { continue; }
+
+    for (const f of entries) {
+      if (!f.endsWith('.retention')) continue;
+      const tagPath  = path.join(dir, f);
+      const filePath = tagPath.replace(/\.retention$/, '');
+      try {
+        const tag     = JSON.parse(fs.readFileSync(tagPath, 'utf8'));
+        const expires = new Date(tag.expires_at).getTime();
+        if (now >= expires) {
+          if (!dryRun) {
+            _safeUnlink(filePath);
+            _safeUnlink(tagPath);
+          }
+          swept.push(filePath);
+        } else {
+          skipped++;
+        }
+      } catch {
+        // Corrupt tag — delete both to be safe
+        if (!dryRun) { _safeUnlink(tagPath); _safeUnlink(filePath); }
+        swept.push(filePath);
+      }
+    }
+  }
+
+  return { swept, skipped };
+}
+
+/**
+ * Classify a file path by its retention policy.
+ * @param {string} filePath
+ * @returns {'permanent'|'30_day'|'temp'|'unknown'}
+ */
+function classifyRetention(filePath) {
+  if (PERMANENT_PATTERNS.some(p => p.test(filePath)))    return 'permanent';
+  if (TEMP_PATTERNS.some(p => p.test(filePath)))         return 'temp';
+  if (INTERMEDIATE_PATTERNS.some(p => p.test(filePath))) return '30_day';
+  return 'unknown';
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function _listFiles(dir) {
+  try {
+    return fs.readdirSync(dir)
+      .map(f => path.join(dir, f))
+      .filter(f => {
+        try { return fs.statSync(f).isFile(); } catch { return false; }
+      });
+  } catch { return []; }
+}
+
+function _safeUnlink(filePath) {
+  try { fs.unlinkSync(filePath); } catch { /* best-effort */ }
+}
+
+module.exports = { applyRetentionRules, sweepExpiredIntermediates, classifyRetention };