visual-ai-assertions 0.9.0 → 0.10.0

package/dist/index.js

@@ -1241,10 +1241,65 @@ async function normalizeImage(input) {
   };
 }
 
+// src/core/debug-frames.ts
+import { randomBytes } from "crypto";
+import { mkdir, writeFile } from "fs/promises";
+import { join, resolve } from "path";
+var DEBUG_FRAMES_ENV = "VISUAL_AI_DEBUG_FRAMES";
+var DEBUG_FRAMES_DIR_ENV = "VISUAL_AI_DEBUG_FRAMES_DIR";
+var DEFAULT_DIR_NAME = "visual-ai-debug-frames";
+function isEnabled(env) {
+  const raw = env[DEBUG_FRAMES_ENV];
+  if (raw === void 0 || raw === "") return false;
+  const lower = raw.toLowerCase();
+  return lower === "true" || lower === "1";
+}
+function timestampSlug(date) {
+  return date.toISOString().replace(/[:.]/g, "-");
+}
+function paddedIndex(value, total) {
+  const width = Math.max(2, String(total - 1).length);
+  return String(value).padStart(width, "0");
+}
+function extensionFromMimeType(mimeType) {
+  if (mimeType === "image/png") return ".png";
+  if (mimeType === "image/webp") return ".webp";
+  return ".jpg";
+}
+async function saveDebugFrames(frames, env = process.env) {
+  if (!isEnabled(env)) return void 0;
+  if (frames.length === 0) return void 0;
+  const baseDir = env[DEBUG_FRAMES_DIR_ENV]?.trim() || DEFAULT_DIR_NAME;
+  const runDir = resolve(baseDir, `${timestampSlug(/* @__PURE__ */ new Date())}-${randomBytes(3).toString("hex")}`);
+  try {
+    await mkdir(runDir, { recursive: true });
+    await Promise.all(
+      frames.map((frame) => {
+        const idx = paddedIndex(frame.index, frames.length);
+        const ts = frame.timestampSeconds.toFixed(2);
+        const ext = extensionFromMimeType(frame.mimeType);
+        const filename = `frame-${idx}-t${ts}s${ext}`;
+        return writeFile(join(runDir, filename), frame.data);
+      })
+    );
+  } catch (err) {
+    process.stderr.write(
+      `[visual-ai-assertions] warning: failed to save debug frames to ${runDir}: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    return void 0;
+  }
+  process.stderr.write(
+    `[visual-ai-assertions] Saved ${frames.length} debug frame(s) to ${runDir}
+`
+  );
+  return runDir;
+}
+
 // src/core/video.ts
-import { mkdtemp, readFile as readFile2, readdir, rm, writeFile } from "fs/promises";
+import { mkdtemp, readFile as readFile2, readdir, rm, writeFile as writeFile2 } from "fs/promises";
 import { tmpdir } from "os";
-import { extname as extname2, join } from "path";
+import { extname as extname2, join as join2 } from "path";
 var FRAME_MAX_DIMENSION = 1568;
 var DEFAULT_FPS = 1;
 var DEFAULT_MAX_FRAMES = 10;
@@ -1343,11 +1398,11 @@ async function resolveVideoToPath(input) {
   return writeBufferToTemp(buf, mimeType);
 }
 async function writeBufferToTemp(data, mimeType) {
-  const dir = await mkdtemp(join(tmpdir(), "visual-ai-video-"));
+  const dir = await mkdtemp(join2(tmpdir(), "visual-ai-video-"));
   try {
     const ext = extensionFor(mimeType);
-    const path = join(dir, `input${ext}`);
-    await writeFile(path, data);
+    const path = join2(dir, `input${ext}`);
+    await writeFile2(path, data);
     return {
       path,
       mimeType,
@@ -1389,7 +1444,7 @@ async function loadFfmpegFactory() {
       const code = err?.code;
       if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND") {
         throw new VisualAIVideoError(
-          "Video support requires fluent-ffmpeg. Install it with: pnpm add -D fluent-ffmpeg @ffmpeg-installer/ffmpeg @ffprobe-installer/ffprobe @types/fluent-ffmpeg"
+          "Could not load fluent-ffmpeg. It ships as a dependency of visual-ai-assertions, so this usually means the install was pruned or the platform-specific binary is unavailable. Reinstall the package or run: pnpm add fluent-ffmpeg @ffmpeg-installer/ffmpeg @ffprobe-installer/ffprobe"
         );
       }
       throw new VisualAIVideoError(
@@ -1434,7 +1489,7 @@ async function loadFfmpegFactory() {
 }
 async function probeDurationSeconds(videoPath) {
   const ffmpeg = await loadFfmpegFactory();
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     let settled = false;
     const finish = (fn) => {
       if (settled) return;
@@ -1471,7 +1526,7 @@ async function probeDurationSeconds(videoPath) {
         return;
       }
       finish(() => {
-        resolve(duration);
+        resolve2(duration);
       });
     });
   });
@@ -1503,10 +1558,10 @@ async function extractFrames(videoPath, options = {}) {
       `Video duration ${durationSeconds.toFixed(2)}s exceeds limit of ${maxDurationSeconds}s. Pass { maxDurationSeconds: N } to override, or trim the source video.`
     );
   }
-  const outputDir = await mkdtemp(join(tmpdir(), "visual-ai-frames-"));
+  const outputDir = await mkdtemp(join2(tmpdir(), "visual-ai-frames-"));
   try {
     const filter = `fps=${fps},scale='if(gt(iw,ih),min(${FRAME_MAX_DIMENSION},iw),-2)':'if(gt(iw,ih),-2,min(${FRAME_MAX_DIMENSION},ih))':flags=area`;
-    await new Promise((resolve, reject) => {
+    await new Promise((resolve2, reject) => {
       let settled = false;
       const cmd = ffmpeg(videoPath);
       const finish = (fn) => {
@@ -1528,9 +1583,9 @@ async function extractFrames(videoPath, options = {}) {
           );
         });
       }, FFMPEG_RUN_TIMEOUT_MS);
-      cmd.outputOptions(["-vf", filter, "-vframes", String(maxFrames), "-q:v", "3"]).output(join(outputDir, "frame-%04d.jpg")).on("end", () => {
+      cmd.outputOptions(["-vf", filter, "-vframes", String(maxFrames), "-q:v", "3"]).output(join2(outputDir, "frame-%04d.jpg")).on("end", () => {
         finish(() => {
-          resolve();
+          resolve2();
         });
       }).on("error", (err) => {
         finish(() => {
@@ -1546,7 +1601,7 @@ async function extractFrames(videoPath, options = {}) {
     }
     const frames = await Promise.all(
       files.map(async (name, index) => {
-        const data = await readFile2(join(outputDir, name));
+        const data = await readFile2(join2(outputDir, name));
         const timestampSeconds = Math.min(durationSeconds, (index + 0.5) / fps);
         let cachedBase64;
         return {
@@ -1602,6 +1657,7 @@ async function normalizeMedia(input, videoOptions) {
     const { path, cleanup } = await resolveVideoToPath(input);
     try {
       const { frames, durationSeconds } = await extractFrames(path, videoOptions);
+      await saveDebugFrames(frames);
       return { kind: "video", frames, durationSeconds };
     } finally {
       try {