@vgai/sdk 0.4.0-canary.20260715.0

package/src/render/capabilities/ffmpeg.ts

@@ -0,0 +1,141 @@
+/**
+ * FFmpeg/ffprobe capability check (spec A1 AC: "FFmpeg absence produces a
+ * named capability error with installation guidance"; §17 Artifact
+ * Verification requires `ffprobe` alongside `ffmpeg`).
+ *
+ * The cinematic render pipeline (Workstream I) shells out to the system
+ * `ffmpeg`/`ffprobe` binaries directly — the same approach the e2e suite
+ * already uses (`packages/editor/e2e/helpers/record.ts`'s `spawnSync('ffmpeg',
+ * ...)`) — rather than depending on an npm "ffmpeg discovery/wrapper"
+ * package. This module is the single place that probes for both binaries and
+ * turns their absence into a structured, named error instead of a raw
+ * ENOENT bubbling out of a later `spawnSync` call deep in the render
+ * pipeline.
+ *
+ * Deliberately dependency-free (only `node:child_process`) so it can be
+ * called early — before any browser/render machinery spins up — from the
+ * CLI, the SDK's `cinematic.render` operation, or a `doctor`-style
+ * preflight check.
+ */
+import { type SpawnSyncReturns, spawnSync } from 'node:child_process';
+
+/** The two binaries this module checks. */
+export type FfmpegBinaryName = 'ffmpeg' | 'ffprobe';
+
+/** Structured, named error codes — never a bare "not found" string an agent has to pattern-match. */
+export type FfmpegCapabilityErrorCode = 'FFMPEG_NOT_FOUND' | 'FFPROBE_NOT_FOUND';
+
+export interface FfmpegCapabilityError {
+  readonly code: FfmpegCapabilityErrorCode;
+  readonly binary: FfmpegBinaryName;
+  /** The command that was probed (honors the `ffmpegBin`/`ffprobeBin` overrides passed to `checkFfmpegCapability`). */
+  readonly command: string;
+  readonly message: string;
+  /** Platform-appropriate install guidance, ready to print as-is. */
+  readonly installGuidance: string;
+}
+
+export interface FfmpegCapabilityOk {
+  readonly ok: true;
+  readonly ffmpeg: { readonly command: string; readonly version: string };
+  readonly ffprobe: { readonly command: string; readonly version: string };
+}
+
+export interface FfmpegCapabilityFailure {
+  readonly ok: false;
+  /** One entry per missing binary — both `ffmpeg` and `ffprobe` are always probed, so this can hold 1 or 2 entries. */
+  readonly errors: readonly FfmpegCapabilityError[];
+}
+
+export type FfmpegCapabilityResult = FfmpegCapabilityOk | FfmpegCapabilityFailure;
+
+export interface CheckFfmpegCapabilityOptions {
+  /** Override the `ffmpeg` command/path probed (default: `"ffmpeg"`, resolved via PATH). Test-only escape hatch to simulate absence deterministically. */
+  ffmpegBin?: string;
+  /** Override the `ffprobe` command/path probed (default: `"ffprobe"`, resolved via PATH). Test-only escape hatch to simulate absence deterministically. */
+  ffprobeBin?: string;
+}
+
+const INSTALL_GUIDANCE = [
+  'Install FFmpeg (which bundles both `ffmpeg` and `ffprobe`) and ensure it is on PATH:',
+  '  macOS:          brew install ffmpeg',
+  '  Debian/Ubuntu:  sudo apt-get update && sudo apt-get install -y ffmpeg',
+  '  Windows:        choco install ffmpeg   (or winget install Gyan.FFmpeg)',
+  '  Other/manual:   https://ffmpeg.org/download.html',
+  'Then verify with: ffmpeg -version && ffprobe -version',
+].join('\n');
+
+function probe(
+  binary: FfmpegBinaryName,
+  command: string,
+): { command: string; version: string } | FfmpegCapabilityError {
+  let result: SpawnSyncReturns<string>;
+  try {
+    result = spawnSync(command, ['-version'], { encoding: 'utf-8' });
+  } catch (err) {
+    return notFoundError(binary, command, err);
+  }
+
+  // `spawnSync` reports a missing executable via `result.error` (ENOENT),
+  // not a thrown exception — check both that and a non-zero/`null` status
+  // (a `null` status means the process couldn't even start, e.g. denied
+  // permission on the resolved path).
+  if (result.error || result.status !== 0) {
+    return notFoundError(binary, command, result.error);
+  }
+
+  const firstLine = (result.stdout ?? '').split('\n')[0]?.trim() || `${command} (version unknown)`;
+  return { command, version: firstLine };
+}
+
+function notFoundError(
+  binary: FfmpegBinaryName,
+  command: string,
+  cause: unknown,
+): FfmpegCapabilityError {
+  const causeDetail = cause instanceof Error ? ` (${cause.message})` : '';
+  return {
+    code: binary === 'ffmpeg' ? 'FFMPEG_NOT_FOUND' : 'FFPROBE_NOT_FOUND',
+    binary,
+    command,
+    message:
+      `${binary} was not found on PATH${causeDetail}. Both ffmpeg and ffprobe are required ` +
+      'system binaries for cinematic export (encode/mux) and §17 artifact verification ' +
+      '(duration/frame-count/A-V-sync checks via ffprobe).',
+    installGuidance: INSTALL_GUIDANCE,
+  };
+}
+
+/**
+ * Probe for both `ffmpeg` and `ffprobe` on PATH (or at the overridden
+ * command/path in `options`). Never throws — absence of either binary is
+ * reported as a structured `FfmpegCapabilityError`, not an exception.
+ *
+ * Both binaries are always probed (even if the first is missing) so a
+ * caller gets the complete picture in one call rather than discovering the
+ * second failure only after fixing the first.
+ */
+export function checkFfmpegCapability(
+  options: CheckFfmpegCapabilityOptions = {},
+): FfmpegCapabilityResult {
+  const ffmpegCommand = options.ffmpegBin ?? 'ffmpeg';
+  const ffprobeCommand = options.ffprobeBin ?? 'ffprobe';
+
+  const ffmpeg = probe('ffmpeg', ffmpegCommand);
+  const ffprobe = probe('ffprobe', ffprobeCommand);
+
+  const errors: FfmpegCapabilityError[] = [];
+  if ('code' in ffmpeg) errors.push(ffmpeg);
+  if ('code' in ffprobe) errors.push(ffprobe);
+
+  if (errors.length > 0) return { ok: false, errors };
+
+  // TypeScript can't narrow `ffmpeg`/`ffprobe` from the `errors.length`
+  // check above, but the two pushes above guarantee both are the success
+  // shape here.
+  return {
+    ok: true,
+    ffmpeg: ffmpeg as { command: string; version: string },
+    ffprobe: ffprobe as { command: string; version: string },
+  };
+}

package/src/render/index.ts

@@ -0,0 +1,15 @@
+/**
+ * The render pipeline core (I0/I2-I8, A1) — relocated INTO `@vgai/sdk` so the
+ * dependency direction is CLI -> SDK -> engine, never SDK -> CLI (per
+ * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §3.4: the SDK is the
+ * authoritative operation core; CLI/HTTP/MCP are projections on top of it).
+ * Formerly `packages/vgai-cli/src/render-cinematic.ts` +
+ * `packages/vgai-cli/src/capabilities/ffmpeg.ts`, imported by the SDK's own
+ * `cinematic.*` operations (`../cinematic/`) via a deep-src `@vgai/cli`
+ * tsconfig path alias — a package-layering inversion once B6 makes the CLI
+ * invoke SDK operations. This barrel is what lets `@vgai/cli` import the
+ * pipeline back FROM `@vgai/sdk`'s public entry point instead.
+ */
+
+export * from './capabilities/ffmpeg.js';
+export * from './render-cinematic.js';