@phuetz/code-buddy 1.6.1 → 2.0.0

package/dist/tools/video/google-flow-driver.js

@@ -0,0 +1,312 @@
+/** Operator-attached Google Flow browser driver. Never launches Chrome or handles login. */
+import { mkdir } from 'fs/promises';
+import path from 'path';
+import { isLoopbackHost } from '../../security/dev-origins.js';
+export const DEFAULT_FLOW_CDP_URL = 'http://127.0.0.1:9222';
+export const GOOGLE_FLOW_URL = 'https://labs.google/fx/tools/flow';
+/**
+ * Google changes Flow's UI regularly. Keep every DOM dependency here so an
+ * operator can update and re-run the selector-only dry run before spending.
+ */
+export const FLOW_SELECTORS = {
+    appRoot: '[data-testid="flow-app"], flow-app, main',
+    signIn: 'a[href*="accounts.google.com"], button:has-text("Sign in"), button:has-text("Se connecter")',
+    errorBanner: '[role="alert"], [data-testid*="error"], [class*="error-banner"]',
+    creditBalance: '[data-testid*="credit"], [aria-label*="credit" i], [class*="credit-balance"]',
+    modelMenu: 'button[aria-label*="model" i], [data-testid="model-selector"] button',
+    modelOption: {
+        'veo-3.1-fast': '[role="option"]:has-text("Veo 3.1"):has-text("Fast"), [role="menuitem"]:has-text("Veo 3.1"):has-text("Fast")',
+        'veo-3.1-quality': '[role="option"]:has-text("Veo 3.1"):has-text("Quality"), [role="menuitem"]:has-text("Veo 3.1"):has-text("Quality")',
+    },
+    aspectMenu: 'button[aria-label*="aspect" i], [data-testid="aspect-ratio-selector"] button',
+    aspectOption: {
+        '9:16': '[role="option"]:has-text("9:16"), [role="menuitem"]:has-text("9:16")',
+        '16:9': '[role="option"]:has-text("16:9"), [role="menuitem"]:has-text("16:9")',
+    },
+    ingredientsInput: 'input[type="file"][accept*="image"], [data-testid="ingredients-upload"] input[type="file"]',
+    ingredientsPreview: '[data-testid*="ingredient-preview"], [class*="ingredient-preview"]',
+    ingredientRemoveButton: '[data-testid*="ingredient-preview"] button[aria-label*="remove" i], [class*="ingredient-preview"] button[aria-label*="remove" i]',
+    promptInput: 'textarea[placeholder], [contenteditable="true"][role="textbox"], [data-testid="prompt-input"]',
+    submitButton: 'button[aria-label*="generate" i], button:has-text("Generate"), button:has-text("Générer")',
+    generationProgress: '[role="progressbar"], [data-testid*="generation-progress"], [class*="generating"]',
+    resultReady: '[data-testid*="generation-result"] video, [data-testid*="generation-result"] img, main video',
+    downloadButton: 'button[aria-label*="download" i], [data-testid*="download"] button',
+};
+const UI_ERROR = /(?:quota|not enough|insufficient|failed|failure|error|erreur|unable|impossible)/iu;
+export class FlowDriver {
+    page;
+    actionTimeoutMs;
+    generationTimeoutMs;
+    pollIntervalMs;
+    constructor(page, options = {}) {
+        this.page = page;
+        this.actionTimeoutMs = positiveTimeout(options.actionTimeoutMs, 15_000, 'action timeout');
+        this.generationTimeoutMs = positiveTimeout(options.generationTimeoutMs, 12 * 60_000, 'generation timeout');
+        this.pollIntervalMs = positiveTimeout(options.pollIntervalMs, 1_000, 'poll interval');
+    }
+    async verifyReady() {
+        await this.assertAuthenticated();
+        await this.visible(FLOW_SELECTORS.appRoot, 'Flow application');
+        await this.visible(FLOW_SELECTORS.promptInput, 'Flow prompt input');
+        await this.visible(FLOW_SELECTORS.modelMenu, 'Flow model selector');
+        await this.visible(FLOW_SELECTORS.aspectMenu, 'Flow aspect selector');
+        await this.visible(FLOW_SELECTORS.ingredientsInput, 'Flow ingredients input');
+        await this.visible(FLOW_SELECTORS.submitButton, 'Flow generate button');
+        await this.visible(FLOW_SELECTORS.creditBalance, 'Flow credit balance');
+        await this.throwIfUiError();
+    }
+    async assertAuthenticated() {
+        const currentUrl = this.page.url();
+        const loginVisible = await this.page.locator(FLOW_SELECTORS.signIn).first().isVisible({ timeout: 500 }).catch(() => false);
+        if (isGoogleLoginUrl(currentUrl) || loginVisible) {
+            throw new Error('Google Flow is not authenticated: connecte-toi d\'abord dans le navigateur, puis relance le driver');
+        }
+    }
+    async setModel(model) {
+        await this.throwIfUiError();
+        await this.safeClick(FLOW_SELECTORS.modelMenu, 'Flow model selector');
+        await this.safeClick(FLOW_SELECTORS.modelOption[model], `Flow model ${model}`);
+        await this.throwIfUiError();
+    }
+    async setAspect(aspect) {
+        await this.throwIfUiError();
+        await this.safeClick(FLOW_SELECTORS.aspectMenu, 'Flow aspect selector');
+        await this.safeClick(FLOW_SELECTORS.aspectOption[aspect], `Flow aspect ${aspect}`);
+        await this.throwIfUiError();
+    }
+    async setIngredients(imagePaths) {
+        if (imagePaths.length > 3)
+            throw new Error('Google Flow accepts at most 3 ingredient images');
+        if (!imagePaths.length)
+            throw new Error('Google Flow generation requires at least one ingredient image');
+        if (new Set(imagePaths).size !== imagePaths.length || imagePaths.some((filename) => !path.isAbsolute(filename))) {
+            throw new Error('Flow ingredient paths must be unique absolute paths');
+        }
+        await this.throwIfUiError();
+        const removeButtons = this.page.locator(FLOW_SELECTORS.ingredientRemoveButton);
+        let existing = await removeButtons.count();
+        while (existing > 0) {
+            if (existing > 3)
+                throw new Error('Flow displayed more than 3 existing ingredients; refusing ambiguous edits');
+            const remove = await this.clickable(FLOW_SELECTORS.ingredientRemoveButton, 'Flow ingredient remove button');
+            await remove.click({ timeout: this.actionTimeoutMs });
+            await this.waitUntil(async () => (await removeButtons.count()) < existing, this.actionTimeoutMs, 'Flow did not remove the previous ingredient');
+            existing = await removeButtons.count();
+        }
+        const input = await this.visible(FLOW_SELECTORS.ingredientsInput, 'Flow ingredients input');
+        await input.setInputFiles(imagePaths, { timeout: this.actionTimeoutMs });
+        const previews = this.page.locator(FLOW_SELECTORS.ingredientsPreview);
+        await this.waitUntil(async () => (await previews.count()) >= imagePaths.length, this.actionTimeoutMs, `Flow did not display ${imagePaths.length} ingredient preview(s)`);
+        await this.throwIfUiError();
+    }
+    async submitPrompt(text) {
+        const prompt = text.trim();
+        if (!prompt)
+            throw new Error('Flow prompt must not be empty');
+        await this.throwIfUiError();
+        const result = this.page.locator(FLOW_SELECTORS.resultReady);
+        const previousCount = await result.count();
+        const previousSource = previousCount > 0 ? await result.first().getAttribute('src').catch(() => null) : null;
+        const input = await this.visible(FLOW_SELECTORS.promptInput, 'Flow prompt input');
+        await input.fill(prompt, { timeout: this.actionTimeoutMs });
+        await this.safeClick(FLOW_SELECTORS.submitButton, 'Flow generate button');
+        let sawProgress = false;
+        await this.waitUntil(async () => {
+            await this.throwIfUiError();
+            const progress = this.page.locator(FLOW_SELECTORS.generationProgress).first();
+            sawProgress ||= await progress.isVisible({ timeout: 250 }).catch(() => false);
+            const currentCount = await result.count();
+            if (currentCount === 0)
+                return false;
+            const currentSource = await result.first().getAttribute('src').catch(() => null);
+            const progressVisible = await progress.isVisible({ timeout: 250 }).catch(() => false);
+            const resultChanged = previousCount === 0 || currentCount > previousCount || currentSource !== previousSource;
+            return !progressVisible && (sawProgress || resultChanged);
+        }, this.generationTimeoutMs, `Google Flow generation timed out after ${this.generationTimeoutMs} ms`);
+        await this.throwIfUiError();
+    }
+    async downloadResult(destPath) {
+        if (!path.isAbsolute(destPath) || path.extname(destPath).toLowerCase() !== '.mp4') {
+            throw new Error('Flow download destination must be an absolute .mp4 path');
+        }
+        await this.throwIfUiError();
+        await this.visible(FLOW_SELECTORS.resultReady, 'completed Flow result');
+        const button = await this.clickable(FLOW_SELECTORS.downloadButton, 'Flow download button');
+        await mkdir(path.dirname(destPath), { recursive: true, mode: 0o700 });
+        const [download] = await Promise.all([
+            this.page.waitForEvent('download', { timeout: this.actionTimeoutMs }),
+            button.click({ timeout: this.actionTimeoutMs }),
+        ]);
+        const failure = await download.failure();
+        if (failure)
+            throw new Error(`Google Flow download failed: ${failure}`);
+        await download.saveAs(destPath);
+    }
+    async readCreditBalance() {
+        await this.assertAuthenticated();
+        await this.throwIfUiError();
+        const balance = await this.visible(FLOW_SELECTORS.creditBalance, 'Flow credit balance');
+        const text = (await balance.textContent({ timeout: this.actionTimeoutMs }))?.trim() ?? '';
+        const match = /(\d[\d\s.,\u202f]*)\s*(?:AI\s+)?(?:credits?|crédits?)/iu.exec(text);
+        if (!match?.[1])
+            throw new Error(`Could not parse Google Flow credit balance from ${JSON.stringify(text)}`);
+        const digits = match[1].replace(/[^\d]/gu, '');
+        const value = Number.parseInt(digits, 10);
+        if (!Number.isSafeInteger(value) || value < 0)
+            throw new Error('Google Flow displayed an invalid credit balance');
+        return value;
+    }
+    async safeClick(selector, label) {
+        const locator = await this.clickable(selector, label);
+        await locator.click({ timeout: this.actionTimeoutMs });
+    }
+    async visible(selector, label) {
+        const locator = this.page.locator(selector).first();
+        try {
+            await locator.waitFor({ state: 'visible', timeout: this.actionTimeoutMs });
+            if (!await locator.isVisible({ timeout: 500 }))
+                throw new Error('not visible');
+            return locator;
+        }
+        catch (error) {
+            await this.assertAuthenticated();
+            throw new Error(`${label} is unavailable; update FLOW_SELECTORS if the Google UI changed: ${errorMessage(error)}`);
+        }
+    }
+    async clickable(selector, label) {
+        const locator = await this.visible(selector, label);
+        if (!await locator.isEnabled({ timeout: 500 }))
+            throw new Error(`${label} is disabled; refusing a blind click`);
+        return locator;
+    }
+    async throwIfUiError() {
+        const locator = this.page.locator(FLOW_SELECTORS.errorBanner).first();
+        if (!await locator.isVisible({ timeout: 250 }).catch(() => false))
+            return;
+        const text = (await locator.textContent({ timeout: 500 }).catch(() => null))?.trim() ?? '';
+        if (UI_ERROR.test(text))
+            throw new Error(`Google Flow UI error: ${text || 'unknown generation failure'}`);
+    }
+    async waitUntil(predicate, timeoutMs, timeoutMessage) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (await predicate())
+                return;
+            await this.page.waitForTimeout(Math.min(this.pollIntervalMs, Math.max(1, deadline - Date.now())));
+        }
+        throw new Error(timeoutMessage);
+    }
+}
+async function defaultConnectOverCdp(cdpUrl) {
+    const { chromium } = await import('playwright');
+    return chromium.connectOverCDP(cdpUrl);
+}
+export async function attachToBrowser(options = {}) {
+    const cdpUrl = assertLoopbackCdpUrl(options.cdpUrl ?? DEFAULT_FLOW_CDP_URL);
+    const timeoutMs = positiveTimeout(options.timeoutMs, 30_000, 'CDP timeout');
+    let attached;
+    try {
+        attached = await (options.connector ?? defaultConnectOverCdp)(cdpUrl);
+    }
+    catch (error) {
+        throw new Error(`Could not attach to operator Chrome at ${cdpUrl}: ${errorMessage(error)}`);
+    }
+    const context = attached.contexts()[0];
+    if (!context) {
+        throw new Error('The attached Chrome has no operator profile context; launch Chrome with the connected profile first');
+    }
+    const page = context.pages().find((candidate) => isFlowUrl(candidate.url())) ?? await openFlowTab(context, timeoutMs);
+    const driver = new FlowDriver(page, { actionTimeoutMs: timeoutMs });
+    await driver.assertAuthenticated();
+    await driver.verifyReady();
+    return {
+        browser: attached,
+        page,
+        driver,
+    };
+}
+export function assertLoopbackCdpUrl(rawUrl) {
+    let parsed;
+    try {
+        parsed = new URL(rawUrl);
+    }
+    catch {
+        throw new Error(`Invalid CDP URL: ${rawUrl}`);
+    }
+    if ((parsed.protocol !== 'http:' && parsed.protocol !== 'https:') || !isLoopbackHost(parsed.hostname)) {
+        throw new Error('Google Flow CDP attachment is restricted to an operator-controlled loopback browser');
+    }
+    if (parsed.username || parsed.password)
+        throw new Error('CDP URL must not contain credentials');
+    return parsed.toString().replace(/\/$/u, '');
+}
+async function openFlowTab(context, timeoutMs) {
+    const page = await context.newPage();
+    await page.goto(GOOGLE_FLOW_URL, { waitUntil: 'domcontentloaded', timeout: timeoutMs });
+    return page;
+}
+function isFlowUrl(rawUrl) {
+    try {
+        const url = new URL(rawUrl);
+        return url.hostname === 'labs.google' && /(?:^|\/)flow(?:\/|$)/u.test(url.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+function isGoogleLoginUrl(rawUrl) {
+    try {
+        const hostname = new URL(rawUrl).hostname;
+        return hostname === 'accounts.google.com' || hostname.endsWith('.accounts.google.com');
+    }
+    catch {
+        return false;
+    }
+}
+function positiveTimeout(value, fallback, label) {
+    const timeout = value ?? fallback;
+    if (!Number.isFinite(timeout) || timeout <= 0)
+        throw new Error(`${label} must be positive`);
+    return timeout;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export class FlowCreditBudgetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FlowCreditBudgetError';
+    }
+}
+function creditCostPerClip(model) {
+    if (model === 'fast')
+        return 10;
+    if (model === 'quality')
+        return 100;
+    throw new Error('Flow model must be fast or quality');
+}
+function assertNonNegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${label} must be a non-negative integer`);
+}
+export function estimateCreditCost(jobs, model) {
+    return jobs.length * creditCostPerClip(model);
+}
+export function assertSufficientCreditBalance(balance, estimatedCost) {
+    assertNonNegativeInteger(balance, 'Flow credit balance');
+    assertNonNegativeInteger(estimatedCost, 'estimated Flow credit cost');
+    if (balance < estimatedCost) {
+        throw new FlowCreditBudgetError(`Insufficient Google Flow credits: balance ${balance}, full-run estimate ${estimatedCost}; no generation submitted`);
+    }
+}
+export function assertCreditBudget(spent, nextCost, maxCredits) {
+    assertNonNegativeInteger(spent, 'spent Flow credits');
+    if (!Number.isSafeInteger(nextCost) || nextCost <= 0)
+        throw new Error('next Flow credit cost must be positive');
+    if (!Number.isSafeInteger(maxCredits) || maxCredits <= 0)
+        throw new Error('--max-credits must be a positive integer');
+    if (spent + nextCost > maxCredits) {
+        throw new FlowCreditBudgetError(`Flow max-credit guard stopped the run at ${spent}/${maxCredits}; next clip costs ${nextCost}`);
+    }
+}
+//# sourceMappingURL=google-flow-driver.js.map

package/dist/tools/video/google-flow-handoff.d.ts

@@ -0,0 +1,75 @@
+/** Browser-assisted Google Flow work packets. No unofficial API or hidden billing. */
+import { type HybridVideoCapacity, type HybridVideoEngine } from './hybrid-video-router.js';
+export type GoogleFlowModel = 'lite' | 'fast' | 'quality';
+export interface GoogleFlowSourceShot {
+    id: string;
+    characterName: string;
+    declaredAdultAge: number;
+    sourcePath: string;
+    sourceSha256: string;
+    motionPrompt: string;
+    role: 'hero' | 'b-roll' | 'transition';
+    consumerShortIds?: string[];
+    consumers?: Array<{
+        shortId: string;
+        shotIndex: number;
+    }>;
+}
+export interface GoogleFlowHandoffOptions {
+    sourcePlanSha256: string;
+    batchId: string;
+    model: GoogleFlowModel;
+    locale: string;
+    durationSeconds: 4 | 6 | 8;
+    aspectRatio: '9:16' | '16:9';
+    upscale4k: boolean;
+    capacity: HybridVideoCapacity;
+}
+export interface GoogleFlowHandoffJob {
+    id: string;
+    engine: HybridVideoEngine;
+    executionMode: 'browser-assisted';
+    estimatedCredits: number;
+    source: {
+        path: string;
+        sha256: string;
+    };
+    consumerShortIds: string[];
+    consumers: Array<{
+        shortId: string;
+        shotIndex: number;
+    }>;
+    prompt: string;
+    role: 'hero' | 'b-roll' | 'transition';
+    settings: {
+        durationSeconds: 4 | 6 | 8;
+        aspectRatio: '9:16' | '16:9';
+        upscale4k: boolean;
+        audio: 'ambient-only';
+        lipSync: false;
+    };
+    status: 'awaiting-flow-generation';
+}
+export interface GoogleFlowHandoff {
+    schemaVersion: 2;
+    sourcePlanSha256: string;
+    handoffSha256: string;
+    batchId: string;
+    provider: 'google-flow-web';
+    billingMode: 'google-ai-ultra-flow-credits';
+    apiBillingAllowed: false;
+    model: GoogleFlowModel;
+    locale: string;
+    estimatedCredits: number;
+    remainingCreditsBefore: number;
+    remainingCreditsAfterEstimate: number;
+    humanFlowSessionRequired: true;
+    autoPublish: false;
+    jobs: GoogleFlowHandoffJob[];
+}
+/** Stable JSON encoding used by local handoff and receipt digests. */
+export declare function canonicalJson(value: unknown): string;
+export declare function canonicalSha256(value: unknown): string;
+export declare function verifyGoogleFlowHandoffDigest(handoff: GoogleFlowHandoff): boolean;
+export declare function buildGoogleFlowPrompt(shot: GoogleFlowSourceShot, aspectRatio: '9:16' | '16:9'): string;
+export declare function createGoogleFlowHandoff(shots: readonly GoogleFlowSourceShot[], options: GoogleFlowHandoffOptions): GoogleFlowHandoff;

package/dist/tools/video/google-flow-handoff.js

@@ -0,0 +1,121 @@
+/** Browser-assisted Google Flow work packets. No unofficial API or hidden billing. */
+import { isAbsolute } from 'node:path';
+import { createHash } from 'crypto';
+import { routeHybridVideoBatch, } from './hybrid-video-router.js';
+/** Stable JSON encoding used by local handoff and receipt digests. */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map((item) => canonicalJson(item)).join(',')}]`;
+    const record = value;
+    return `{${Object.keys(record).sort().filter((key) => record[key] !== undefined).map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+}
+export function canonicalSha256(value) {
+    return createHash('sha256').update(canonicalJson(value)).digest('hex');
+}
+export function verifyGoogleFlowHandoffDigest(handoff) {
+    const { handoffSha256, ...unsigned } = handoff;
+    return /^[a-f0-9]{64}$/u.test(handoffSha256) && canonicalSha256(unsigned) === handoffSha256;
+}
+function routeSettings(model) {
+    if (model === 'quality')
+        return { useCase: 'hero-shot', premium: true };
+    if (model === 'lite')
+        return { useCase: 'bulk-variation', premium: false };
+    return { useCase: 'long-form-b-roll', premium: false };
+}
+export function buildGoogleFlowPrompt(shot, aspectRatio) {
+    if (!shot.characterName.trim() || shot.declaredAdultAge < 25 || !shot.motionPrompt.trim()) {
+        throw new Error(`Flow shot ${shot.id} lacks an approved adult identity or motion prompt`);
+    }
+    return [
+        `Fictional adult character ${shot.characterName}, clearly age ${shot.declaredAdultAge}.`,
+        'Use the supplied image as the identity reference; preserve face, hair, body proportions and wardrobe.',
+        shot.motionPrompt.trim(),
+        aspectRatio === '9:16' ? 'Vertical cinematic composition for YouTube Shorts.' : 'Cinematic widescreen composition.',
+        'Natural anatomy, coherent hands, stable background, physically plausible motion, no text, no logo.',
+        'Ambient sound only. No speech, no singing and no visible lip synchronization.',
+        'End on a visually clean frame suitable for editing into a larger original story.',
+    ].join(' ');
+}
+export function createGoogleFlowHandoff(shots, options) {
+    if (!/^[a-f0-9]{64}$/u.test(options.sourcePlanSha256)) {
+        throw new Error('Flow handoff requires the canonical SHA-256 of its V3 source plan');
+    }
+    if (new Set(shots.map((shot) => shot.id)).size !== shots.length) {
+        throw new Error('Flow handoff job IDs must be unique');
+    }
+    if (!/^[a-z0-9](?:[a-z0-9-]{0,125}[a-z0-9])?$/u.test(options.batchId) || !shots.length) {
+        throw new Error('Flow handoff requires a safe batch ID and shots');
+    }
+    for (const shot of shots) {
+        if (!/^[a-z0-9](?:[a-z0-9-]{0,125}[a-z0-9])?$/u.test(shot.id) ||
+            !/^[a-f0-9]{64}$/u.test(shot.sourceSha256) || !isAbsolute(shot.sourcePath) ||
+            !['hero', 'b-roll', 'transition'].includes(shot.role) ||
+            !(shot.consumers?.length || shot.consumerShortIds?.length) ||
+            (shot.consumerShortIds ?? []).some((shortId) => !/^[a-z0-9](?:[a-z0-9-]{0,125}[a-z0-9])?$/u.test(shortId)) ||
+            (shot.consumers ?? []).some((consumer) => !/^[a-z0-9](?:[a-z0-9-]{0,125}[a-z0-9])?$/u.test(consumer.shortId) ||
+                !Number.isInteger(consumer.shotIndex) || consumer.shotIndex < 1))
+            throw new Error(`Flow shot ${shot.id || '<unknown>'} has an unsafe source or consumer mapping`);
+    }
+    if (options.model === 'quality' && options.durationSeconds !== 8) {
+        throw new Error('Veo 3.1 Quality only supports 8-second generations in Google Flow');
+    }
+    const settings = routeSettings(options.model);
+    const routed = routeHybridVideoBatch(shots.map((shot) => ({
+        id: shot.id,
+        useCase: settings.useCase,
+        contentTier: 'safe',
+        quantity: 1,
+        requiresLipSync: false,
+        premium: settings.premium,
+        upscale4k: options.upscale4k,
+    })), options.capacity);
+    const jobs = shots.map((shot, index) => {
+        const route = routed.routes[index];
+        if (!route.primary.startsWith('google-flow-') || route.executionMode !== 'browser-assisted') {
+            throw new Error(`Flow credit guardrail routed ${shot.id} to ${route.primary}; reduce or split the batch`);
+        }
+        return {
+            id: shot.id,
+            engine: route.primary,
+            executionMode: 'browser-assisted',
+            estimatedCredits: route.estimatedFlowCredits,
+            source: { path: shot.sourcePath, sha256: shot.sourceSha256 },
+            consumerShortIds: [...new Set(shot.consumerShortIds ?? [])],
+            consumers: [...new Map((shot.consumers?.length ? shot.consumers : (shot.consumerShortIds ?? []).map((shortId) => ({
+                    shortId,
+                    shotIndex: index + 1,
+                }))).map((consumer) => [`${consumer.shortId}:${consumer.shotIndex}`, consumer])).values()],
+            prompt: buildGoogleFlowPrompt(shot, options.aspectRatio),
+            role: shot.role,
+            settings: {
+                durationSeconds: options.durationSeconds,
+                aspectRatio: options.aspectRatio,
+                upscale4k: options.upscale4k,
+                audio: 'ambient-only',
+                lipSync: false,
+            },
+            status: 'awaiting-flow-generation',
+        };
+    });
+    const unsigned = {
+        schemaVersion: 2,
+        sourcePlanSha256: options.sourcePlanSha256,
+        batchId: options.batchId,
+        provider: 'google-flow-web',
+        billingMode: 'google-ai-ultra-flow-credits',
+        apiBillingAllowed: false,
+        model: options.model,
+        locale: options.locale,
+        estimatedCredits: routed.estimatedFlowCredits,
+        remainingCreditsBefore: options.capacity.remainingFlowCredits,
+        remainingCreditsAfterEstimate: options.capacity.remainingFlowCredits - routed.estimatedFlowCredits,
+        humanFlowSessionRequired: true,
+        autoPublish: false,
+        jobs,
+    };
+    return { ...unsigned, handoffSha256: canonicalSha256(unsigned) };
+}
+//# sourceMappingURL=google-flow-handoff.js.map

package/dist/tools/video/google-flow-plan-export.d.ts

@@ -0,0 +1,21 @@
+/** Convert a QA-approved MySoulmate Short plan into a bounded Google Flow handoff. */
+import { type GoogleFlowHandoff, type GoogleFlowModel } from './google-flow-handoff.js';
+export interface GoogleFlowPlanExportOptions {
+    approvedAssetRoot: string;
+    batchId: string;
+    shortId?: string;
+    includeAllShorts?: boolean;
+    model: GoogleFlowModel;
+    durationSeconds: 4 | 6 | 8;
+    aspectRatio: '9:16' | '16:9';
+    upscale4k: boolean;
+    remainingFlowCredits: number;
+    maxFlowCreditsPerBatch: number;
+    gpuNodeAvailable: boolean;
+    localGpuAvailable: boolean;
+}
+/**
+ * Validate every source file before creating a handoff. Identical visual shots
+ * shared by localized masters are generated once and list every consumer.
+ */
+export declare function exportGoogleFlowHandoffFromPlan(value: unknown, options: GoogleFlowPlanExportOptions): Promise<GoogleFlowHandoff>;

package/dist/tools/video/google-flow-plan-export.js

@@ -0,0 +1,123 @@
+/** Convert a QA-approved MySoulmate Short plan into a bounded Google Flow handoff. */
+import path from 'path';
+import { loadApprovedImageSource } from './approved-media-source.js';
+import { createGoogleFlowHandoff, canonicalSha256, } from './google-flow-handoff.js';
+const REQUIRED_SOURCE_DIGEST_KEYS = [
+    'assetApprovalsSha256',
+    'factoryConfigSha256',
+    'imageCatalogSha256',
+    'imageManifestSha256',
+    'productionLedgerSha256',
+];
+function hasExactSourceDigests(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return keys.length === REQUIRED_SOURCE_DIGEST_KEYS.length &&
+        keys.every((key, index) => key === REQUIRED_SOURCE_DIGEST_KEYS[index]) &&
+        REQUIRED_SOURCE_DIGEST_KEYS.every((key) => typeof record[key] === 'string' && /^[a-f0-9]{64}$/u.test(record[key]));
+}
+function assertShortPlan(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Short plan must be an object');
+    const plan = value;
+    if (plan.schemaVersion !== 3 ||
+        !hasExactSourceDigests(plan.sourceDigests) ||
+        plan.policy?.contentTier !== 'safe' ||
+        plan.policy.qaStatus !== 'approved' ||
+        plan.policy.autoPublish !== false ||
+        plan.policy.initialVisibility !== 'private' ||
+        plan.policy.syntheticMediaDisclosureRequired !== true ||
+        !Array.isArray(plan.shorts) ||
+        !plan.shorts.length) {
+        throw new Error('Short plan is not safe, QA-approved, private and disclosed');
+    }
+}
+function selectShorts(plan, options) {
+    if (options.shortId && options.includeAllShorts) {
+        throw new Error('Select either one Short or all Shorts, not both');
+    }
+    if (options.shortId) {
+        const selected = plan.shorts.find((short) => short.shortId === options.shortId);
+        if (!selected)
+            throw new Error(`Unknown Short ID: ${options.shortId}`);
+        return [selected];
+    }
+    return options.includeAllShorts ? plan.shorts : [plan.shorts[0]];
+}
+function assertPlannedShort(short) {
+    if (!short.shortId?.trim() ||
+        !short.profile?.name?.trim() ||
+        !Number.isInteger(short.profile.declaredAdultAge) ||
+        short.profile.declaredAdultAge < 25 ||
+        short.publication?.visibility !== 'private' ||
+        short.publication.autoPublish !== false ||
+        short.publication.containsSyntheticMedia !== true ||
+        short.publication.reviewStatus !== 'pending-human-review' ||
+        !Array.isArray(short.render?.shots) ||
+        !short.render.shots.length) {
+        throw new Error(`Short ${short.shortId || '<unknown>'} is not approved for a Flow handoff`);
+    }
+}
+/**
+ * Validate every source file before creating a handoff. Identical visual shots
+ * shared by localized masters are generated once and list every consumer.
+ */
+export async function exportGoogleFlowHandoffFromPlan(value, options) {
+    assertShortPlan(value);
+    if (!path.isAbsolute(options.approvedAssetRoot))
+        throw new Error('Approved asset root must be absolute');
+    const selected = selectShorts(value, options);
+    const uniqueShots = new Map();
+    for (const short of selected) {
+        assertPlannedShort(short);
+        for (const shot of short.render.shots) {
+            if (shot.contentTier !== 'safe' ||
+                shot.qaStatus !== 'approved' ||
+                !path.isAbsolute(shot.referenceImagePath) ||
+                !/^[a-f0-9]{64}$/u.test(shot.sourceSha256) ||
+                !shot.motionPrompt?.trim()) {
+                throw new Error(`Short ${short.shortId} contains an incomplete or unsafe source shot`);
+            }
+            const source = await loadApprovedImageSource(shot.referenceImagePath, options.approvedAssetRoot, shot.sourceSha256);
+            const key = `${source.sha256}\u0000${shot.motionPrompt.trim()}`;
+            const existing = uniqueShots.get(key);
+            if (existing) {
+                existing.consumerShortIds = [...new Set([...(existing.consumerShortIds ?? []), short.shortId])];
+                existing.consumers = [...new Map([...(existing.consumers ?? []), { shortId: short.shortId, shotIndex: shot.index ?? short.render.shots.indexOf(shot) + 1 }]
+                        .map((consumer) => [`${consumer.shortId}:${consumer.shotIndex}`, consumer])).values()];
+                continue;
+            }
+            uniqueShots.set(key, {
+                id: `${short.shortId}-flow-${String(uniqueShots.size + 1).padStart(2, '0')}`,
+                characterName: short.profile.name,
+                declaredAdultAge: short.profile.declaredAdultAge,
+                sourcePath: source.realPath,
+                sourceSha256: source.sha256,
+                motionPrompt: shot.motionPrompt,
+                role: uniqueShots.size === 0 ? 'hero' : uniqueShots.size % 3 === 2 ? 'transition' : 'b-roll',
+                consumerShortIds: [short.shortId],
+                consumers: [{ shortId: short.shortId, shotIndex: shot.index ?? short.render.shots.indexOf(shot) + 1 }],
+            });
+        }
+    }
+    const locales = [...new Set(selected.map((short) => short.locale).filter((locale) => Boolean(locale)))];
+    return createGoogleFlowHandoff([...uniqueShots.values()], {
+        sourcePlanSha256: canonicalSha256(value),
+        batchId: options.batchId,
+        model: options.model,
+        locale: locales.length === 1 ? locales[0] : locales.length ? 'multilingual-shared-visuals' : 'und',
+        durationSeconds: options.durationSeconds,
+        aspectRatio: options.aspectRatio,
+        upscale4k: options.upscale4k,
+        capacity: {
+            gpuNode: options.gpuNodeAvailable,
+            localGpu: options.localGpuAvailable,
+            googleFlow: true,
+            remainingFlowCredits: options.remainingFlowCredits,
+            maxFlowCreditsPerBatch: options.maxFlowCreditsPerBatch,
+        },
+    });
+}
+//# sourceMappingURL=google-flow-plan-export.js.map