videoclaw 3.0.0-alpha.1

package/src/video/execution-plan.ts

@@ -0,0 +1,178 @@
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { artifactPathFor } from './artifact-store.js';
+import { buildExecutionProfile } from './execution-profile.js';
+import { buildProviderStatusReport } from './provider-status.js';
+import { buildPromptGuidance } from './prompt-guidance.js';
+import { buildProjectReadiness } from './readiness.js';
+import { sceneCandidatesPathFor } from './scene-candidate-store.js';
+import { readSceneSelectionArtifact } from './scene-selection-store.js';
+import { resolveProjectWorkspace, readProjectManifest } from './workspace.js';
+import {
+  isProviderRouteId,
+  type ProviderRouteId,
+  type VideoOperationKind,
+} from './provider-platform/types.js';
+import type {
+  VideoExecutionPlan,
+  VideoProductionMode,
+} from './types.js';
+
+function defaultRoutesForMode(mode: VideoProductionMode): ProviderRouteId[] {
+  if (mode === 'director') {
+    return ['seedance-direct', 'veo-useapi'];
+  }
+  return ['veo-useapi', 'seedance-direct'];
+}
+
+/**
+ * Resolve the ordered route-preference list for a project. When the manifest
+ * declares a `routePreference`, those routes are tried first (in the given
+ * order), followed by any built-in default routes not already listed — so a
+ * partial preference still falls back safely. An empty/absent preference is
+ * byte-identical to the built-in defaults. Unknown route ids throw here, at
+ * plan time, before any provider submission.
+ */
+function preferredRoutesForMode(
+  mode: VideoProductionMode,
+  routePreference?: ProviderRouteId[] | null,
+): ProviderRouteId[] {
+  const defaults = defaultRoutesForMode(mode);
+  if (!routePreference || routePreference.length === 0) {
+    return defaults;
+  }
+  const invalid = routePreference.filter((routeId) => !isProviderRouteId(routeId));
+  if (invalid.length > 0) {
+    throw new Error(
+      `project.json routePreference contains unknown provider route id(s): ${invalid
+        .map((id) => JSON.stringify(id))
+        .join(', ')}. Valid routes: veo-useapi, runway-useapi, dreamina-useapi, seedance-direct.`,
+    );
+  }
+  const seen = new Set<ProviderRouteId>();
+  const ordered: ProviderRouteId[] = [];
+  for (const routeId of [...routePreference, ...defaults]) {
+    if (seen.has(routeId)) continue;
+    seen.add(routeId);
+    ordered.push(routeId);
+  }
+  return ordered;
+}
+
+async function hasUnselectedStoryboardScenesInCandidateMode(
+  projectSlug: string,
+  root: string,
+): Promise<boolean> {
+  if (!existsSync(sceneCandidatesPathFor(root, projectSlug))) return false;
+  const selection = await readSceneSelectionArtifact(root, projectSlug);
+  const selectedSceneIndexes = new Set(
+    selection.scenes
+      .filter((scene) => typeof scene.selectedCandidateId === 'string' && scene.selectedCandidateId.length > 0)
+      .map((scene) => scene.sceneIndex),
+  );
+  const workspace = resolveProjectWorkspace(projectSlug, root);
+  const storyboardPath = artifactPathFor(workspace, 'storyboard');
+  if (!existsSync(storyboardPath)) return false;
+  const storyboard = JSON.parse(await readFile(storyboardPath, 'utf-8')) as {
+    scenes?: Array<{ sceneIndex?: number }>;
+  };
+  const sceneIndexes = (storyboard.scenes ?? [])
+    .map((scene, index) => (typeof scene.sceneIndex === 'number' ? scene.sceneIndex : index));
+  if (sceneIndexes.length === 0) return false;
+  return sceneIndexes.some((sceneIndex) => !selectedSceneIndexes.has(sceneIndex));
+}
+
+async function inferOperationKind(
+  projectSlug: string,
+  root: string,
+  mode: VideoProductionMode,
+): Promise<VideoOperationKind> {
+  const workspace = resolveProjectWorkspace(projectSlug, root);
+  const assetManifestPath = artifactPathFor(workspace, 'asset-manifest');
+  if (!existsSync(assetManifestPath)) {
+    return mode === 'director' ? 'image-to-video' : 'image-to-video';
+  }
+  const manifest = JSON.parse(await readFile(assetManifestPath, 'utf-8')) as {
+    assets?: Array<{ kind?: string }>;
+  };
+  const hasVideo = manifest.assets?.some((asset) => asset.kind === 'video') ?? false;
+  const hasImage = manifest.assets?.some((asset) => asset.kind === 'image') ?? false;
+  if (hasVideo && !hasImage) {
+    // Candidate-mode reruns can temporarily produce a video-only manifest from
+    // selected winners while later storyboard scenes still need generation.
+    if (await hasUnselectedStoryboardScenesInCandidateMode(projectSlug, root)) {
+      return 'image-to-video';
+    }
+    return 'edit';
+  }
+  if (hasImage) return 'image-to-video';
+  return mode === 'director' ? 'image-to-video' : 'text-to-video';
+}
+
+export async function buildExecutionPlan(
+  projectSlug: string,
+  root = process.cwd(),
+  fallbackMode: VideoProductionMode = 'storyboard',
+  options: { env?: NodeJS.ProcessEnv } = {},
+): Promise<VideoExecutionPlan> {
+  const workspace = resolveProjectWorkspace(projectSlug, root);
+  const manifest = await readProjectManifest(workspace);
+  const productionMode = manifest?.productionMode ?? fallbackMode;
+  const readiness = await buildProjectReadiness(projectSlug, root, productionMode);
+  const operationKind = await inferOperationKind(projectSlug, root, productionMode);
+  const providerStatus = buildProviderStatusReport({
+    workspaceRoot: root,
+    env: options.env,
+    ignoreRuntimeDependencyIssues: true,
+  });
+  const preferredRoutes = preferredRoutesForMode(productionMode, manifest?.routePreference);
+
+  const blockers = [...readiness.blockers];
+  const rationale: string[] = [];
+  let recommendedRouteId: ProviderRouteId | null = null;
+
+  for (const routeId of preferredRoutes) {
+    const route = providerStatus.routes.find((candidate) => candidate.routeId === routeId);
+    if (!route) continue;
+    if (!route.supportedOperations.includes(operationKind)) {
+      rationale.push(`${routeId} skipped: does not support ${operationKind}.`);
+      continue;
+    }
+    if (route.availability !== 'available') {
+      rationale.push(`${routeId} skipped: route is ${route.availability}.`);
+      continue;
+    }
+    recommendedRouteId = routeId;
+    rationale.push(`${routeId} selected: supports ${operationKind} and is available.`);
+    break;
+  }
+
+  if (!recommendedRouteId) {
+    blockers.push(`No available provider route supports ${operationKind}.`);
+  }
+  const executionProfile = await buildExecutionProfile({
+    projectSlug,
+    root,
+    productionMode,
+    routeId: recommendedRouteId,
+    operationKind,
+  });
+  const promptGuidance = buildPromptGuidance({
+    routeId: recommendedRouteId,
+    operationKind,
+    productionMode,
+  });
+
+  return {
+    projectSlug,
+    productionMode,
+    operationKind,
+    recommendedRouteId,
+    executionProfile,
+    ready: blockers.length === 0,
+    blockers,
+    rationale,
+    promptGuidance,
+    generatedAt: new Date().toISOString(),
+  };
+}

package/src/video/execution-profile.ts

@@ -0,0 +1,162 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { artifactPathFor, writeArtifact } from './artifact-store.js';
+import { appendProjectEvent } from './events.js';
+import { resolveProjectWorkspace } from './workspace.js';
+import type { ProviderRouteId, VideoOperationKind } from './provider-platform/types.js';
+import type { VideoExecutionPlan, VideoProductionMode } from './types.js';
+import type { BriefArtifact } from './artifacts.js';
+
+type ExecutionProfile = VideoExecutionPlan['executionProfile'];
+
+function normalizeAspectRatio(value: unknown): ExecutionProfile['aspectRatio'] | null {
+  return value === '16:9' || value === '9:16' || value === '1:1' ? value : null;
+}
+
+function normalizeQuality(value: unknown): ExecutionProfile['quality'] | null {
+  return value === 'fast' || value === 'quality' ? value : null;
+}
+
+function normalizeResolution(value: unknown): ExecutionProfile['resolution'] | null {
+  return value === '720p' || value === '1080p' ? value : null;
+}
+
+function normalizeOutputCount(value: unknown): number | null {
+  return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 4 ? Number(value) : null;
+}
+
+function normalizeGenerateAudio(value: unknown): boolean | null {
+  return typeof value === 'boolean' ? value : null;
+}
+
+function normalizeVeoModel(value: unknown): NonNullable<ExecutionProfile['veoModel']> | null {
+  // fast/quality/omni-flash + the cheaper Veo tiers: `lite` (veo-3.1-lite) and
+  // `free` (veo-3.1-lite-low-priority — the relaxed/explore lane, Ultra-gated at
+  // the provider). flow.ts mapModelToUseApi resolves these short names.
+  return value === 'fast' ||
+    value === 'quality' ||
+    value === 'lite' ||
+    value === 'free' ||
+    value === 'omni-flash'
+    ? value
+    : null;
+}
+
+async function readExecutionProfileOverrides(
+  projectSlug: string,
+  root: string,
+): Promise<Partial<ExecutionProfile>> {
+  const workspace = resolveProjectWorkspace(projectSlug, root);
+  const briefPath = artifactPathFor(workspace, 'brief');
+  if (!existsSync(briefPath)) return {};
+  const brief = JSON.parse(await readFile(briefPath, 'utf-8')) as {
+    metadata?: {
+      platform?: string;
+      executionProfile?: Record<string, unknown>;
+    };
+  };
+
+  const executionProfile = brief.metadata?.executionProfile ?? {};
+  const platform = String(brief.metadata?.platform ?? '').toLowerCase();
+  return {
+    ...(normalizeAspectRatio(executionProfile.aspectRatio) ? { aspectRatio: normalizeAspectRatio(executionProfile.aspectRatio)! } : {}),
+    ...(normalizeQuality(executionProfile.quality) ? { quality: normalizeQuality(executionProfile.quality)! } : {}),
+    ...(normalizeResolution(executionProfile.resolution) ? { resolution: normalizeResolution(executionProfile.resolution)! } : {}),
+    ...(typeof executionProfile.generateAudio === 'boolean' ? { generateAudio: executionProfile.generateAudio } : {}),
+    ...(normalizeOutputCount(executionProfile.outputCount) ? { outputCount: normalizeOutputCount(executionProfile.outputCount)! } : {}),
+    ...(normalizeVeoModel(executionProfile.veoModel) ? { veoModel: normalizeVeoModel(executionProfile.veoModel)! } : {}),
+    ...(!normalizeAspectRatio(executionProfile.aspectRatio) && ['tiktok', 'reels', 'shorts'].includes(platform)
+      ? { aspectRatio: '9:16' as const }
+      : {}),
+  };
+}
+
+export async function setExecutionProfileOverrides(
+  projectSlug: string,
+  input: Partial<ExecutionProfile>,
+  root = process.cwd(),
+): Promise<{
+  artifactPath: string;
+  brief: BriefArtifact;
+}> {
+  const workspace = resolveProjectWorkspace(projectSlug, root);
+  const briefPath = artifactPathFor(workspace, 'brief');
+  if (!existsSync(briefPath)) {
+    throw new Error(`Execution profile cannot be updated for "${projectSlug}" because the brief artifact is missing.`);
+  }
+
+  const brief = JSON.parse(await readFile(briefPath, 'utf-8')) as BriefArtifact;
+  const existingProfile = ((brief.metadata ?? {}).executionProfile ?? {}) as Record<string, unknown>;
+  const nextProfile = {
+    ...existingProfile,
+    ...(input.aspectRatio ? { aspectRatio: input.aspectRatio } : {}),
+    ...(input.quality ? { quality: input.quality } : {}),
+    ...(input.resolution ? { resolution: input.resolution } : {}),
+    ...(typeof input.generateAudio === 'boolean' ? { generateAudio: input.generateAudio } : {}),
+    ...(typeof input.outputCount === 'number' ? { outputCount: input.outputCount } : {}),
+    ...(input.veoModel ? { veoModel: input.veoModel } : {}),
+  };
+
+  const nextBrief: BriefArtifact = {
+    ...brief,
+    metadata: {
+      ...(brief.metadata ?? {}),
+      executionProfile: nextProfile,
+    },
+  };
+  const artifactPath = await writeArtifact(workspace, 'brief', nextBrief);
+  await appendProjectEvent(workspace, {
+    type: 'artifact.brief.execution-profile.updated',
+    payload: {
+      artifactPath,
+      executionProfile: nextProfile,
+    },
+  });
+  return { artifactPath, brief: nextBrief };
+}
+
+export function parseExecutionProfileInput(input: {
+  aspectRatio?: unknown;
+  quality?: unknown;
+  resolution?: unknown;
+  generateAudio?: unknown;
+  outputCount?: unknown;
+  veoModel?: unknown;
+}): Partial<ExecutionProfile> {
+  const profile: Partial<ExecutionProfile> = {};
+  const aspectRatio = normalizeAspectRatio(input.aspectRatio);
+  const quality = normalizeQuality(input.quality);
+  const resolution = normalizeResolution(input.resolution);
+  const generateAudio = normalizeGenerateAudio(input.generateAudio);
+  const outputCount = normalizeOutputCount(input.outputCount);
+  const veoModel = normalizeVeoModel(input.veoModel);
+  if (aspectRatio) profile.aspectRatio = aspectRatio;
+  if (quality) profile.quality = quality;
+  if (resolution) profile.resolution = resolution;
+  if (generateAudio !== null) profile.generateAudio = generateAudio;
+  if (outputCount !== null) profile.outputCount = outputCount;
+  if (veoModel) profile.veoModel = veoModel;
+  return profile;
+}
+
+export async function buildExecutionProfile(input: {
+  projectSlug: string;
+  root?: string;
+  productionMode: VideoProductionMode;
+  routeId: ProviderRouteId | null;
+  operationKind: VideoOperationKind;
+}): Promise<ExecutionProfile> {
+  const root = input.root ?? process.cwd();
+  const overrides = await readExecutionProfileOverrides(input.projectSlug, root);
+  const defaults: ExecutionProfile = {
+    aspectRatio: '16:9',
+    quality: input.productionMode === 'director' ? 'quality' : 'fast',
+    resolution: '720p',
+    generateAudio: input.routeId === 'seedance-direct',
+    outputCount: 1,
+  };
+  return {
+    ...defaults,
+    ...overrides,
+  };
+}