@officexapp/vidfarm-devcli 0.21.10

package/dist/src/services/composition-lint.js

@@ -0,0 +1,199 @@
+// Static composition validation shared by the /editor chat copilot
+// (replace_composition_html preflight, both the in-process and Lambda copies),
+// the devcli (`vidfarm lint`), and publish preflights. Mirrors the checks the
+// HyperFrames CLI's `lint` runs against raw projects, adapted to vidfarm's
+// composition vocabulary (data-vf-* proxies, transition holds, caption spans).
+import { parseHTML } from "linkedom";
+import { CAPTION_ANIMATIONS, KEN_BURNS_PRESETS, TRANSITION_OUT_PRESETS, TRANSITION_PRESETS } from "../hyperframes/composition.js";
+const OVERLAP_EPSILON = 0.011;
+function parseNumberAttr(value) {
+    if (typeof value !== "string" || !value.trim()) {
+        return null;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function layerKeyFor(element) {
+    return (element.getAttribute("data-hf-id") ||
+        element.getAttribute("id") ||
+        element.getAttribute("data-hf-slug") ||
+        `<${element.tagName.toLowerCase()}>`);
+}
+export function lintCompositionHtml(html) {
+    const issues = [];
+    const push = (level, code, message, layer) => {
+        issues.push({ level, code, message, ...(layer ? { layer } : {}) });
+    };
+    const trimmed = typeof html === "string" ? html.trim() : "";
+    if (!trimmed) {
+        push("error", "empty_document", "Composition HTML is empty.");
+        return finalize(issues);
+    }
+    let document;
+    try {
+        ({ document } = parseHTML(trimmed));
+    }
+    catch (error) {
+        push("error", "unparseable_document", `Composition HTML could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
+        return finalize(issues);
+    }
+    const root = document.querySelector("[data-composition-id]");
+    if (!root) {
+        push("error", "missing_composition_root", "No element carries data-composition-id — the composition root is required.");
+        return finalize(issues);
+    }
+    const width = parseNumberAttr(root.getAttribute("data-width"));
+    const height = parseNumberAttr(root.getAttribute("data-height"));
+    if (width === null || height === null) {
+        push("warning", "missing_canvas_size", "Composition root should declare numeric data-width and data-height (px).");
+    }
+    else if (width <= 0 || height <= 0) {
+        push("error", "invalid_canvas", `Composition root data-width/data-height must be positive (got ${width}x${height}).`);
+    }
+    const fpsRaw = root.getAttribute("data-fps");
+    if (fpsRaw !== null && (parseNumberAttr(fpsRaw) === null || parseNumberAttr(fpsRaw) <= 0)) {
+        push("warning", "invalid_fps", `Composition root data-fps is not a positive number (got "${fpsRaw}").`);
+    }
+    const clips = Array.from(document.querySelectorAll("[data-start]")).filter((el) => el !== root);
+    const rootDuration = parseNumberAttr(root.getAttribute("data-duration"));
+    if (rootDuration === null) {
+        if (clips.length === 0) {
+            push("error", "missing_root_duration", "Composition root has no data-duration and no timed clips to infer one from.");
+        }
+        else {
+            push("warning", "missing_root_duration", "Composition root has no data-duration; the runtime will infer it from the latest clip end. Declare it explicitly for deterministic renders.");
+        }
+    }
+    else if (rootDuration <= 0) {
+        push("error", "invalid_root_duration", `Composition root data-duration must be positive (got ${rootDuration}).`);
+    }
+    if (clips.length === 0) {
+        push("warning", "no_clips", "Composition has no timed clips ([data-start] elements).");
+    }
+    const timings = [];
+    const seenKeys = new Map();
+    for (const clip of clips) {
+        const key = layerKeyFor(clip);
+        const tag = clip.tagName.toLowerCase();
+        const isMedia = tag === "video" || tag === "audio";
+        const isProxy = clip.hasAttribute("data-vf-timeline-proxy");
+        const explicitKey = clip.getAttribute("data-hf-id") || clip.getAttribute("id");
+        if (explicitKey) {
+            seenKeys.set(explicitKey, (seenKeys.get(explicitKey) ?? 0) + 1);
+        }
+        const start = parseNumberAttr(clip.getAttribute("data-start"));
+        if (start === null || start < 0) {
+            push("error", "invalid_clip_timing", `Clip has a non-numeric or negative data-start ("${clip.getAttribute("data-start")}").`, key);
+            continue;
+        }
+        const duration = parseNumberAttr(clip.getAttribute("data-duration"));
+        if (duration === null) {
+            if (isMedia) {
+                push("warning", "media_missing_duration", "Media clip has no data-duration; it will fall back to the source's intrinsic length. Declare it for predictable trims.", key);
+            }
+            else {
+                push("error", "missing_clip_duration", "Non-media clip requires a positive data-duration.", key);
+            }
+        }
+        else if (duration <= 0) {
+            push("error", "invalid_clip_duration", `Clip data-duration must be positive (got ${duration}).`, key);
+        }
+        const trackRaw = clip.getAttribute("data-track-index");
+        const track = parseNumberAttr(trackRaw);
+        if (trackRaw === null || track === null || !Number.isInteger(track) || track < 0) {
+            push("warning", "missing_track_index", `Clip should declare an integer data-track-index >= 0 (got "${trackRaw ?? "<absent>"}").`, key);
+        }
+        // Nested clips fight parent visibility toggling and are unregistered in
+        // the upstream HyperFrames runtime (clips must be direct children).
+        let ancestor = clip.parentElement;
+        while (ancestor && ancestor !== root) {
+            if (ancestor.hasAttribute("data-start")) {
+                push("warning", "nested_clip", "Clip is nested inside another timed clip; move clips to the composition root.", key);
+                break;
+            }
+            ancestor = ancestor.parentElement;
+        }
+        if (isMedia && clip.parentElement && clip.parentElement !== root) {
+            push("warning", "nested_media", "video/audio elements should be direct children of the composition root — nested media renders blank/black under the HyperFrames runtime.", key);
+        }
+        if ((tag === "video" || tag === "img" || tag === "audio") && !isProxy) {
+            const src = clip.getAttribute("src") || clip.getAttribute("data-src");
+            const hasSourceChild = Boolean(clip.querySelector("source[src]"));
+            if (!src && !hasSourceChild) {
+                push("error", "media_missing_src", `<${tag}> clip has no src / data-src.`, key);
+            }
+        }
+        const kenBurns = clip.getAttribute("data-kenburns") ?? clip.querySelector("img[data-kenburns]")?.getAttribute("data-kenburns");
+        if (kenBurns && kenBurns !== "none" && !KEN_BURNS_PRESETS.includes(kenBurns)) {
+            push("error", "unknown_ken_burns", `Unknown data-kenburns preset "${kenBurns}".`, key);
+        }
+        const transition = clip.getAttribute("data-transition");
+        if (transition && transition !== "none" && !TRANSITION_PRESETS.includes(transition)) {
+            push("error", "unknown_transition", `Unknown data-transition preset "${transition}".`, key);
+        }
+        const transitionOut = clip.getAttribute("data-transition-out");
+        if (transitionOut && transitionOut !== "none" && !TRANSITION_OUT_PRESETS.includes(transitionOut)) {
+            push("error", "unknown_transition_out", `Unknown data-transition-out preset "${transitionOut}".`, key);
+        }
+        const captionAnimation = clip.getAttribute("data-caption-animation");
+        if (captionAnimation && captionAnimation !== "none" && !CAPTION_ANIMATIONS.includes(captionAnimation)) {
+            push("error", "unknown_caption_animation", `Unknown data-caption-animation preset "${captionAnimation}".`, key);
+        }
+        const effectiveDuration = duration !== null && duration > 0 ? duration : 0;
+        timings.push({
+            element: clip,
+            key,
+            start,
+            end: start + effectiveDuration,
+            track: track !== null && Number.isInteger(track) && track >= 0 ? track : null,
+            hasTransitionHold: clip.hasAttribute("data-transition-hold")
+        });
+    }
+    for (const [key, count] of seenKeys) {
+        if (count > 1) {
+            push("warning", "duplicate_layer_id", `Layer id "${key}" appears ${count} times; layer keys must be unique for editor/chat targeting.`);
+        }
+    }
+    // Same-track temporal overlap. Materialized transition holds
+    // (data-transition-hold) legitimately overlap their successor.
+    const byTrack = new Map();
+    for (const timing of timings) {
+        if (timing.track === null || timing.end <= timing.start) {
+            continue;
+        }
+        const bucket = byTrack.get(timing.track) ?? [];
+        bucket.push(timing);
+        byTrack.set(timing.track, bucket);
+    }
+    for (const [track, bucket] of byTrack) {
+        bucket.sort((a, b) => a.start - b.start || a.end - b.end);
+        for (let i = 1; i < bucket.length; i += 1) {
+            const prev = bucket[i - 1];
+            const current = bucket[i];
+            if (current.start < prev.end - OVERLAP_EPSILON && !prev.hasTransitionHold && !current.hasTransitionHold) {
+                push("error", "track_overlap", `Clips "${prev.key}" and "${current.key}" overlap on track ${track} (${prev.start}-${prev.end}s vs ${current.start}s start). Same-track clips must not overlap.`, current.key);
+            }
+        }
+    }
+    const scripts = document.querySelectorAll("script");
+    if (scripts.length > 0) {
+        push("warning", "scripts_stripped_on_save", `Composition contains ${scripts.length} <script> tag(s). Scripts survive local serve/disk renders, but every cloud/web editor save strips them (stored-XSS defense) — script-driven animation will be lost there. Prefer the declarative preset vocabulary (data-kenburns, data-transition, data-caption-animation) for compositions that round-trip through the web editor.`);
+    }
+    return finalize(issues);
+}
+function finalize(issues) {
+    const errors = issues.filter((issue) => issue.level === "error");
+    const warnings = issues.filter((issue) => issue.level === "warning");
+    return { ok: errors.length === 0, errors, warnings };
+}
+export function formatCompositionLintIssues(result) {
+    const lines = [];
+    for (const issue of result.errors) {
+        lines.push(`error  ${issue.code}${issue.layer ? ` [${issue.layer}]` : ""}: ${issue.message}`);
+    }
+    for (const issue of result.warnings) {
+        lines.push(`warn   ${issue.code}${issue.layer ? ` [${issue.layer}]` : ""}: ${issue.message}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=composition-lint.js.map

package/dist/src/services/provider-errors.js

@@ -0,0 +1,128 @@
+// Provider error taxonomy + HTTP-response classification, shared by every
+// surface that talks to an AI provider directly: ProviderService (cloud, leased
+// BYOK keys) and the speech module (also driven key-less from the devcli with a
+// local env key). Lives outside providers.ts so speech.ts can import it without
+// a circular dependency.
+export class ProviderKeyUnavailableError extends Error {
+}
+export class ProviderAuthError extends Error {
+}
+/** A TTS voice preset that belongs to a different provider family — user input error, never retryable. */
+export class SpeechVoiceMismatchError extends Error {
+}
+export class ProviderQuotaExceededError extends Error {
+}
+/** The provider refused the request or output because of its content/safety policy. */
+export class ProviderSafetyError extends Error {
+}
+export class ProviderWaitExceededError extends Error {
+}
+export class ProviderLeaseTimeoutError extends Error {
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds = 5) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export class ProviderRateLimitError extends Error {
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds = 60) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export class ProviderTransientError extends Error {
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds = 5) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+export function parseRetryAfterSeconds(value) {
+    if (!value) {
+        return 60;
+    }
+    const numeric = Number(value);
+    if (Number.isFinite(numeric) && numeric > 0) {
+        return Math.max(1, Math.min(Math.ceil(numeric), 60 * 60));
+    }
+    const parsedDate = Date.parse(value);
+    if (Number.isFinite(parsedDate)) {
+        return Math.max(1, Math.min(Math.ceil((parsedDate - Date.now()) / 1000), 60 * 60));
+    }
+    return 60;
+}
+export function isHardQuotaError(details) {
+    const normalized = details.toLowerCase();
+    return [
+        "insufficient_quota",
+        "quota_exceeded",
+        "exceeded your current quota",
+        "billing",
+        "insufficient credits",
+        "not enough credits",
+        "credit balance",
+        "prepaid credits",
+        "resource_exhausted"
+    ].some((pattern) => normalized.includes(pattern));
+}
+export function isSafetyOrRefusalError(details) {
+    const normalized = details.toLowerCase();
+    return [
+        "content_policy_violation",
+        "content policy",
+        "safety policy",
+        "safety filter",
+        "safety_reason",
+        "finishreason\":\"safety",
+        "moderation_blocked",
+        "blocked_reason",
+        "blockedreason",
+        "prompt was blocked",
+        "moderation",
+        "moderated",
+        "responsible ai",
+        "refused",
+        "refusal",
+        "prohibited content",
+        "policy violation"
+    ].some((pattern) => normalized.includes(pattern));
+}
+export function providerFailureFromDetails(provider, operation, status, details) {
+    if (isSafetyOrRefusalError(details)) {
+        return new ProviderSafetyError(`${provider} refused this ${operation} because its safety or content policy was triggered${conciseProviderDetails(details)}. ` +
+            "Try revising the prompt or choose another provider/model.");
+    }
+    return new Error(`${provider} ${operation} returned ${status}${conciseProviderDetails(details)}`);
+}
+export function serializeProviderFailure(error) {
+    const message = error instanceof Error ? error.message : "AI provider request failed";
+    if (error instanceof ProviderSafetyError) {
+        return { message, type: "provider_safety_refusal", retryable: false, user_action: "Revise the prompt or choose another provider/model." };
+    }
+    if (error instanceof ProviderRateLimitError) {
+        return { message, type: "provider_rate_limited", retryable: true, retry_after_seconds: error.retryAfterSeconds, user_action: "Wait, then retry or choose another provider." };
+    }
+    if (error instanceof ProviderQuotaExceededError) {
+        return { message, type: "provider_quota_exceeded", retryable: false, user_action: "Check provider billing/quota or choose another provider." };
+    }
+    if (error instanceof ProviderAuthError) {
+        return { message, type: "provider_auth_error", retryable: false, user_action: "Check the saved provider API key." };
+    }
+    if (error instanceof ProviderTransientError) {
+        return { message, type: "provider_temporarily_unavailable", retryable: true, retry_after_seconds: error.retryAfterSeconds, user_action: "Retry shortly or choose another provider." };
+    }
+    return { message, type: "provider_request_failed", retryable: false };
+}
+export function conciseProviderDetails(details) {
+    const compact = details.replace(/\s+/g, " ").trim();
+    return compact ? `: ${compact.slice(0, 500)}` : "";
+}
+export async function rateLimitOrQuotaError(provider, response) {
+    const details = await response.text();
+    if (isHardQuotaError(details)) {
+        return new ProviderQuotaExceededError(`${provider} quota or billing limit was reached${conciseProviderDetails(details)}`);
+    }
+    return new ProviderRateLimitError(`${provider} rate limited${conciseProviderDetails(details)}`, parseRetryAfterSeconds(response.headers.get("retry-after")));
+}
+//# sourceMappingURL=provider-errors.js.map