@okostream/mcp 0.12.2 → 0.12.3

package/dist/tools/imagePipeline.js

@@ -1,597 +0,0 @@
-// Конвейер изображений события: приём источника, загрузка оригинала,
-// ожидание вариантов, удаление.
-//
-// Чтение картинки по ссылке — единственное место, где MCP ходит в чужую сеть,
-// поэтому здесь же живёт вся защита: разрешённые типы, потолок байтов,
-// ограничение редиректов и запрет частных адресов (SSRF). Локальные файлы
-// читаются только из явного списка каталогов организатора.
-//
-// Варианты 320/800/1600 делает CF4 после появления master.webp. Клиент их не
-// пишет и не может: он лишь ждёт, пока сервер допишет метаданные в документ.
-import { randomUUID } from "node:crypto";
-import { lookup } from "node:dns/promises";
-import { stat, readFile, realpath } from "node:fs/promises";
-import { homedir } from "node:os";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
-import { Agent, fetch as undiciFetch } from "undici";
-import { doc, runTransaction as runFirestoreTransaction } from "firebase/firestore";
-import { httpsCallable } from "firebase/functions";
-import { z } from "zod";
-import { env } from "../env.js";
-import { firestore, functions } from "../firebase.js";
-import { ipLiteralFamily, isPublicUnicastAddress, normalizeIpLiteralHostname } from "../networkPolicy.js";
-import { safeString } from "../utils.js";
-import { readEvent } from "./eventAccess.js";
-export const IMAGE_KINDS = ["promoBanner", "videoPlaceholder", "card"];
-export const IMAGE_VARIANT_NAMES = ["thumb_320.webp", "card_800.webp", "hero_1600.webp"];
-export const CARD_IMAGE_RATIOS = ["auto", "1:1", "4:3", "3:2", "16:9", "2:3", "3:4"];
-export const CARD_ID_PATTERN = /^[A-Za-z0-9_-]{1,80}$/;
-export const MAX_CARD_ITEMS = 6;
-export const MAX_CARD_TITLE_LENGTH = 160;
-export const MAX_CARD_TEXT_LENGTH = 500;
-export const MAX_CARD_BUTTON_LABEL_LENGTH = 80;
-export const MAX_CARD_BUTTON_URL_LENGTH = 1000;
-export const MAX_SOURCE_IMAGE_BYTES = 15 * 1024 * 1024;
-export const REMOTE_IMAGE_TIMEOUT_MS = 15_000;
-export const REMOTE_IMAGE_MAX_REDIRECTS = 3;
-export const ALLOWED_REMOTE_IMAGE_TYPES = new Set(["image/jpeg", "image/jpg", "image/png", "image/webp", "image/gif", "image/avif"]);
-export function imageStoragePath(eventId, uid, kind, imageId) {
-    return `events/${eventId}/${uid}/images/${kind}/${imageId}/master.webp`;
-}
-export function storagePathFromDownloadUrl(downloadUrl) {
-    if (!downloadUrl)
-        return null;
-    const match = downloadUrl.match(/\/o\/([^?]+)/);
-    if (!match)
-        return null;
-    const encodedPath = match[1];
-    if (!encodedPath)
-        return null;
-    try {
-        return decodeURIComponent(encodedPath);
-    }
-    catch {
-        return null;
-    }
-}
-export function variantPathsFromMasterPath(masterPath) {
-    if (!masterPath.endsWith("/master.webp"))
-        return [];
-    return IMAGE_VARIANT_NAMES.map((name) => masterPath.replace(/master\.webp$/, name));
-}
-export function resolveLocalImagePath(inputPath) {
-    const expanded = inputPath === "~" || inputPath.startsWith("~/")
-        ? join(homedir(), inputPath.slice(2))
-        : inputPath;
-    return isAbsolute(expanded) ? resolve(expanded) : resolve(process.cwd(), expanded);
-}
-export function isBlockedHostname(hostname) {
-    const host = hostname.toLowerCase();
-    return host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local");
-}
-export async function resolveRemoteImageAddress(url) {
-    if (url.protocol !== "https:") {
-        throw new Error("Image URL must use https://.");
-    }
-    if (url.username || url.password) {
-        throw new Error("Image URL must not include embedded credentials.");
-    }
-    if (isBlockedHostname(url.hostname)) {
-        throw new Error("Image URL host is not allowed. Use a public HTTPS image URL.");
-    }
-    const literalAddress = normalizeIpLiteralHostname(url.hostname);
-    const literalFamily = ipLiteralFamily(literalAddress);
-    if (literalFamily !== 0) {
-        if (!isPublicUnicastAddress(literalAddress)) {
-            throw new Error("Image URL points to a private/local IP address, which is not allowed.");
-        }
-        return { address: literalAddress, family: literalFamily };
-    }
-    const addresses = await lookup(url.hostname, { all: true });
-    if (addresses.length === 0 || addresses.some((item) => !isPublicUnicastAddress(item.address))) {
-        throw new Error("Image URL resolves to a non-public IP address, which is not allowed.");
-    }
-    const selected = addresses[0];
-    if (!selected || (selected.family !== 4 && selected.family !== 6)) {
-        throw new Error("Image URL host could not be resolved safely.");
-    }
-    return { address: selected.address, family: selected.family };
-}
-export async function responseBufferWithLimit(response, maxBytes) {
-    const body = response.body;
-    if (!body) {
-        const bytes = Buffer.from(await response.arrayBuffer());
-        if (bytes.byteLength > maxBytes)
-            throw new Error(`Image exceeds ${Math.floor(maxBytes / 1024 / 1024)}MB limit.`);
-        return bytes;
-    }
-    const reader = body.getReader();
-    const chunks = [];
-    let total = 0;
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            const chunk = Buffer.from(value);
-            total += chunk.byteLength;
-            if (total > maxBytes) {
-                throw new Error(`Image exceeds ${Math.floor(maxBytes / 1024 / 1024)}MB limit.`);
-            }
-            chunks.push(chunk);
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-    return Buffer.concat(chunks, total);
-}
-export async function readRemoteImage(rawUrl, redirects = 0) {
-    if (redirects > REMOTE_IMAGE_MAX_REDIRECTS) {
-        throw new Error("Image URL has too many redirects.");
-    }
-    const url = new URL(rawUrl);
-    const pinned = await resolveRemoteImageAddress(url);
-    const dispatcher = new Agent({
-        connect: {
-            lookup: (_hostname, _options, callback) => callback(null, pinned.address, pinned.family),
-        },
-    });
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), REMOTE_IMAGE_TIMEOUT_MS);
-    try {
-        const response = await undiciFetch(url, {
-            redirect: "manual",
-            signal: controller.signal,
-            headers: { accept: "image/avif,image/webp,image/png,image/jpeg,image/gif" },
-            dispatcher,
-        });
-        if (response.status >= 300 && response.status < 400) {
-            const location = response.headers.get("location");
-            if (!location)
-                throw new Error(`Image URL redirected with HTTP ${response.status} but no Location header.`);
-            return readRemoteImage(new URL(location, url).toString(), redirects + 1);
-        }
-        if (!response.ok) {
-            throw new Error(`Image URL fetch failed with HTTP ${response.status}.`);
-        }
-        const contentType = (response.headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase();
-        if (!contentType || !contentType.startsWith("image/")) {
-            throw new Error("Image URL must return Content-Type image/*.");
-        }
-        if (!ALLOWED_REMOTE_IMAGE_TYPES.has(contentType)) {
-            throw new Error(`Image URL Content-Type ${contentType} is not supported. Use JPEG, PNG, WEBP, GIF, or AVIF.`);
-        }
-        const contentLength = Number(response.headers.get("content-length") ?? 0);
-        if (Number.isFinite(contentLength) && contentLength > MAX_SOURCE_IMAGE_BYTES) {
-            throw new Error("Image URL is larger than 15MB.");
-        }
-        return responseBufferWithLimit(response, MAX_SOURCE_IMAGE_BYTES);
-    }
-    catch (err) {
-        if (err instanceof Error && err.name === "AbortError") {
-            throw new Error("Image URL fetch timed out.");
-        }
-        throw err;
-    }
-    finally {
-        clearTimeout(timeout);
-        // 🔴 `destroy()`, а не `close()`. `close()` в undici ЖДЁТ завершения
-        // незавершённых запросов — а когда защита по размеру бросает из
-        // `responseBufferWithLimit`, тело ответа остаётся непрочитанным. Публичный
-        // сервер с открытым chunked-ответом подвешивал инструмент бесконечно
-        // именно здесь: ограничение уже сработало, а выйти из функции было
-        // нельзя. `destroy()` отменяет то, что не дочитано.
-        await dispatcher.destroy();
-    }
-}
-export async function readLocalImage(inputPath) {
-    if (env.imageRoots.length === 0) {
-        throw new Error("Local image reads are disabled. Set OKO_IMAGE_ROOTS to an explicit trusted directory and restart the MCP client.");
-    }
-    const filePath = await realpath(resolveLocalImagePath(inputPath));
-    const roots = await Promise.all(env.imageRoots.map(async (root) => {
-        try {
-            return await realpath(root);
-        }
-        catch {
-            return resolve(root);
-        }
-    }));
-    const allowed = roots.some((root) => {
-        const child = relative(root, filePath);
-        return child === "" || (!child.startsWith(`..${sep}`) && child !== ".." && !isAbsolute(child));
-    });
-    if (!allowed) {
-        throw new Error("Image path is outside OKO_IMAGE_ROOTS. Add a trusted root to the MCP client environment.");
-    }
-    const info = await stat(filePath);
-    if (!info.isFile())
-        throw new Error("Image path must point to a regular file.");
-    if (info.size > MAX_SOURCE_IMAGE_BYTES)
-        throw new Error("Image file is larger than 15MB.");
-    return readFile(filePath);
-}
-export async function readImageSource(source) {
-    if (source.path)
-        return readLocalImage(source.path);
-    if (source.url)
-        return readRemoteImage(source.url);
-    throw new Error("Provide image source path or url.");
-}
-export function readImageRef(eventData, kind, cardId) {
-    const blocks = (eventData.blocks && typeof eventData.blocks === "object" ? eventData.blocks : {});
-    if (kind === "promoBanner") {
-        const banner = (blocks.promoBanner && typeof blocks.promoBanner === "object" ? blocks.promoBanner : {});
-        return {
-            imageId: storagePathFromDownloadUrl(safeString(banner.imageMasterUrl))?.split("/").at(-2) ?? null,
-            imageUrl: safeString(banner.imageUrl) || null,
-            imageMasterUrl: safeString(banner.imageMasterUrl) || null,
-            imageVariants: readImageVariants(banner.imageVariants),
-        };
-    }
-    if (kind === "videoPlaceholder") {
-        const video = (blocks.video && typeof blocks.video === "object" ? blocks.video : {});
-        const placeholder = (video.placeholder && typeof video.placeholder === "object" ? video.placeholder : {});
-        return {
-            imageId: storagePathFromDownloadUrl(safeString(placeholder.imageMasterUrl))?.split("/").at(-2) ?? null,
-            imageUrl: safeString(placeholder.imageUrl) || null,
-            imageMasterUrl: safeString(placeholder.imageMasterUrl) || null,
-            imageVariants: readImageVariants(placeholder.imageVariants),
-        };
-    }
-    if (!cardId)
-        throw new Error("cardId is required when kind is card.");
-    const cards = (blocks.cards && typeof blocks.cards === "object" ? blocks.cards : {});
-    const items = Array.isArray(cards.items) ? cards.items : [];
-    const item = items.find((raw) => Boolean(raw) && typeof raw === "object" && raw.id === cardId);
-    if (!item)
-        throw new Error(`Card ${cardId} not found in blocks.cards.items. Create/configure the card before uploading its image.`);
-    return {
-        imageId: cardId,
-        imageUrl: safeString(item.imageUrl) || null,
-        imageMasterUrl: safeString(item.imageMasterUrl) || null,
-        imageVariants: readImageVariants(item.imageVariants),
-    };
-}
-export function cardItemsWithImage(eventData, cardId, patch) {
-    const blocks = (eventData.blocks && typeof eventData.blocks === "object" ? eventData.blocks : {});
-    const cards = (blocks.cards && typeof blocks.cards === "object" ? blocks.cards : {});
-    const items = Array.isArray(cards.items) ? cards.items : [];
-    let found = false;
-    const next = items.map((raw) => {
-        const item = (raw && typeof raw === "object" ? raw : {});
-        if (item.id !== cardId)
-            return item;
-        found = true;
-        return { ...item, ...patch };
-    });
-    if (!found)
-        throw new Error(`Card ${cardId} not found in blocks.cards.items.`);
-    return next;
-}
-export function readImageVariants(value) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        return null;
-    const data = value;
-    if (typeof data.thumbUrl !== "string" || typeof data.cardUrl !== "string" || typeof data.heroUrl !== "string") {
-        return null;
-    }
-    return {
-        thumbUrl: data.thumbUrl,
-        cardUrl: data.cardUrl,
-        heroUrl: data.heroUrl,
-    };
-}
-export function readCardsConfig(eventData) {
-    const blocks = (eventData.blocks && typeof eventData.blocks === "object" ? eventData.blocks : {});
-    const raw = (blocks.cards && typeof blocks.cards === "object" ? blocks.cards : {});
-    const rawItems = Array.isArray(raw.items) ? raw.items : [];
-    const repairedIdPositions = [];
-    // 🔴 Позиция считается по ИСХОДНОМУ массиву, а не по отфильтрованному:
-    // иначе путь `blocks.cards.items[N]` в ошибке валидации указывает не на ту
-    // карточку. Фича существует ровно для битых массивов, то есть для случая,
-    // где отсев и создаёт сдвиг (ревью 02.09, Б14).
-    const items = rawItems
-        .map((item, position) => ({ item, position }))
-        .filter((entry) => Boolean(entry.item) && typeof entry.item === "object" && !Array.isArray(entry.item))
-        .map(({ item, position }) => {
-        const hasUsableId = typeof item.id === "string" && CARD_ID_PATTERN.test(item.id);
-        if (!hasUsableId)
-            repairedIdPositions.push(position);
-        return {
-            // 🔴 UUID генерируется только когда он нужен: прежде crypto-RNG
-            // дёргался для каждой карточки при каждом чтении, а значение
-            // отбрасывалось (ревью 02.09, В14)
-            id: hasUsableId ? item.id : randomUUID(),
-            title: safeString(item.title).trim() || null,
-            text: safeString(item.text).trim() || null,
-            buttonLabel: safeString(item.buttonLabel).trim() || null,
-            buttonUrl: safeString(item.buttonUrl).trim() || null,
-            imageUrl: safeString(item.imageUrl).trim() || null,
-            imageMasterUrl: safeString(item.imageMasterUrl).trim() || null,
-            imageVariants: readImageVariants(item.imageVariants),
-            imageWidth: typeof item.imageWidth === "number" ? item.imageWidth : null,
-            imageHeight: typeof item.imageHeight === "number" ? item.imageHeight : null,
-            formId: safeString(item.formId).trim() || null,
-        };
-    });
-    const ratio = safeString(raw.cardImageRatio);
-    return {
-        enabled: raw.enabled === true,
-        visibility: raw.visibility === "hidden" ? "hidden" : "always",
-        cardImageRatio: CARD_IMAGE_RATIOS.includes(ratio) ? ratio : "16:9",
-        items,
-        repairedIdPositions,
-    };
-}
-export function normalizeNullableText(value) {
-    if (value == null)
-        return null;
-    return value.trim() || null;
-}
-export function normalizeCardButtonUrl(value) {
-    const trimmed = normalizeNullableText(value);
-    if (!trimmed)
-        return null;
-    let url;
-    try {
-        url = new URL(trimmed);
-    }
-    catch {
-        throw new Error(`Invalid card buttonUrl "${trimmed}". Use http(s), mailto, tel, or set formId instead.`);
-    }
-    if (!["http:", "https:", "mailto:", "tel:"].includes(url.protocol)) {
-        throw new Error(`Unsupported card buttonUrl protocol "${url.protocol}". Use http(s), mailto, tel, or set formId instead.`);
-    }
-    return trimmed;
-}
-export function eventFormIds(eventData) {
-    const rawForms = Array.isArray(eventData.forms) ? eventData.forms : [];
-    return new Set(rawForms
-        .map((form) => form && typeof form === "object" && !Array.isArray(form) ? safeString(form.id).trim() : "")
-        .filter(Boolean));
-}
-export function cardHasImage(item) {
-    return Boolean(item.imageMasterUrl || item.imageUrl || item.imageVariants);
-}
-export const cardIdSchema = z.string()
-    .regex(CARD_ID_PATTERN, "Use 1-80 characters: letters, numbers, underscore, or hyphen.")
-    .describe("Stable card id. Omit to generate one; keep it to preserve images and analytics continuity.");
-export const cardItemInputSchema = z.object({
-    id: cardIdSchema.optional(),
-    title: z.string().max(MAX_CARD_TITLE_LENGTH).nullable().optional(),
-    text: z.string().max(MAX_CARD_TEXT_LENGTH).nullable().optional(),
-    buttonLabel: z.string().max(MAX_CARD_BUTTON_LABEL_LENGTH).nullable().optional(),
-    buttonUrl: z.string().max(MAX_CARD_BUTTON_URL_LENGTH).nullable().optional(),
-    formId: cardIdSchema.nullable().optional(),
-}).strict();
-export const imageSourceSchema = z.object({
-    path: z.string().min(1).optional().describe("Local image path on the MCP client machine."),
-    url: z.string().url().optional().describe("HTTPS image URL to fetch from the MCP client machine."),
-}).strict().refine((source) => Boolean(source.path) !== Boolean(source.url), {
-    message: "Provide exactly one image source: path or url.",
-});
-export function buildCardsItems({ inputs, existing, formIds, }) {
-    const existingById = new Map(existing.map((item) => [item.id, item]));
-    const seen = new Set();
-    const generatedCardIds = [];
-    const preservedImageCardIds = [];
-    const items = inputs.map((input) => {
-        const id = input.id ?? randomUUID();
-        if (seen.has(id))
-            throw new Error(`Duplicate card id "${id}". Each card id must be unique.`);
-        seen.add(id);
-        if (!CARD_ID_PATTERN.test(id))
-            throw new Error(`Invalid card id "${id}". Use 1-80 characters: letters, numbers, underscore, or hyphen.`);
-        if (!input.id)
-            generatedCardIds.push(id);
-        const formId = normalizeNullableText(input.formId);
-        if (formId && !formIds.has(formId)) {
-            throw new Error(`Form ${formId} not found in event.forms. Create it with oko_configure_blocks forms first, or set formId:null.`);
-        }
-        const previous = existingById.get(id);
-        if (previous && cardHasImage(previous))
-            preservedImageCardIds.push(id);
-        return {
-            id,
-            title: normalizeNullableText(input.title),
-            text: normalizeNullableText(input.text),
-            buttonLabel: normalizeNullableText(input.buttonLabel),
-            buttonUrl: normalizeCardButtonUrl(input.buttonUrl),
-            imageUrl: previous?.imageUrl ?? null,
-            imageMasterUrl: previous?.imageMasterUrl ?? null,
-            imageVariants: previous?.imageVariants ?? null,
-            imageWidth: previous?.imageWidth ?? null,
-            imageHeight: previous?.imageHeight ?? null,
-            formId,
-        };
-    });
-    return { items, generatedCardIds, preservedImageCardIds };
-}
-export async function deleteStoragePaths(eventId, paths) {
-    const uniquePaths = [...new Set(paths.filter(Boolean))];
-    if (uniquePaths.length === 0)
-        return [];
-    const removeImages = httpsCallable(functions, "deleteMcpImages");
-    // 🔴 Уборка объектов — best-effort и НЕ имеет права уронить уже
-    // совершившуюся операцию. Отказ CF27 (например, путь чужого префикса у
-    // непроусыновлённого дубликата) прежде вылетал наружу: организатору
-    // сообщалось, что удаление не удалось, хотя ссылки уже сняты, — а после
-    // загрузки это провоцировало повторную закачку той же картинки. Соседний
-    // `oko_delete_image` прямо обещает обратное (ревью 02.09, В4).
-    try {
-        const result = await removeImages({ eventId, paths: uniquePaths });
-        return Array.isArray(result.data.warnings) ? result.data.warnings : [];
-    }
-    catch (error) {
-        return [`storage cleanup failed: ${error instanceof Error ? error.message : String(error)}`];
-    }
-}
-export async function deleteStorageUrls(eventId, masterUrl, fallbackUrl) {
-    const paths = [];
-    const masterPath = storagePathFromDownloadUrl(masterUrl);
-    if (masterPath) {
-        paths.push(masterPath, ...variantPathsFromMasterPath(masterPath));
-    }
-    else {
-        const fallbackPath = storagePathFromDownloadUrl(fallbackUrl);
-        if (fallbackPath)
-            paths.push(fallbackPath);
-    }
-    const warnings = await deleteStoragePaths(eventId, paths);
-    return { attempted: [...new Set(paths)].length, warnings };
-}
-export async function uploadMasterImage(eventId, kind, cardId, image) {
-    const uploadImage = httpsCallable(functions, "uploadMcpImage");
-    const result = await uploadImage({
-        eventId,
-        kind,
-        ...(cardId ? { cardId } : {}),
-        imageBase64: image.toString("base64"),
-    });
-    return result.data;
-}
-export async function updateCardImageInTransaction(eventId, cardId, patch) {
-    const eventRef = doc(firestore, "events", eventId);
-    await runFirestoreTransaction(firestore, async (transaction) => {
-        const snap = await transaction.get(eventRef);
-        if (!snap.exists())
-            throw new Error("Event not found.");
-        const data = snap.data();
-        transaction.update(eventRef, {
-            "blocks.cards.items": cardItemsWithImage(data, cardId, patch),
-        });
-    });
-}
-/**
- * Записывает патч события, пересобирая массив карточек из СВЕЖЕГО документа.
- *
- * 🔴 Зачем транзакция. `blocks.cards.items` — массив, и запись его целиком
- * затирает всё, чего не было в прочитанном снимке. Между чтением события и
- * записью успевает отработать CF4: она дописывает `imageVariants`, `imageUrl`
- * и размеры по стабильному id карточки. Реконструкция из устаревшего снимка
- * стирала эти поля — картинка у зрителя откатывалась к мастеру или пропадала.
- *
- * Это Pattern 23, разобранный на веб-стороне (там Setup уже сливает
- * метаданные транзакционно) и вернувшийся через MCP: то же место, тот же
- * массив, только другой клиент.
- *
- * `buildItems` получает свежие данные документа и обязан строить итоговый
- * массив из них, а не из снимка, снятого до транзакции.
- */
-export async function writeEventPatchWithCards(eventId, basePatch, buildItems) {
-    const eventRef = doc(firestore, "events", eventId);
-    await runFirestoreTransaction(firestore, async (transaction) => {
-        const snap = await transaction.get(eventRef);
-        if (!snap.exists())
-            throw new Error("Event not found.");
-        const patch = { ...basePatch };
-        if (buildItems) {
-            patch["blocks.cards.items"] = buildItems(snap.data());
-        }
-        if (Object.keys(patch).length === 0)
-            return;
-        transaction.update(eventRef, patch);
-    });
-}
-export function imageVariantReason(ref) {
-    if (!ref.imageMasterUrl && !ref.imageUrl)
-        return "image_missing";
-    if (!ref.imageMasterUrl)
-        return "master_missing";
-    if (!ref.imageVariants)
-        return "variants_pending";
-    if (!ref.imageUrl)
-        return "image_url_pending";
-    return null;
-}
-export function imageVariantStatus(eventId, eventData, kind, cardId, elapsedMs) {
-    const ref = readImageRef(eventData, kind, cardId ?? undefined);
-    const reason = imageVariantReason(ref);
-    return {
-        eventId,
-        kind,
-        cardId,
-        imageId: ref.imageId,
-        imageUrl: ref.imageUrl,
-        imageMasterUrl: ref.imageMasterUrl,
-        imageVariants: ref.imageVariants,
-        ready: reason === null,
-        reason,
-        elapsedMs,
-    };
-}
-export function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-export async function waitForImageVariantTargets(uid, eventId, targets, timeoutSec) {
-    const startedAt = Date.now();
-    const deadline = startedAt + timeoutSec * 1000;
-    // Мёртвая заготовка снята: цикл ниже выполняется хотя бы раз и
-    // перезаписывает `latest` до любого чтения, так что наблюдать её было
-    // нечем — а `imageId: target.cardId` в ней ещё и вводил в заблуждение
-    // (ревью 02.09, В15).
-    let latest;
-    while (true) {
-        const elapsedMs = Date.now() - startedAt;
-        const event = await readEvent(eventId, uid, "read");
-        latest = targets.map((target) => imageVariantStatus(eventId, event, target.kind, target.cardId, elapsedMs));
-        if (latest.every((item) => item.ready) || Date.now() >= deadline)
-            return latest;
-        await sleep(Math.min(2000, Math.max(250, deadline - Date.now())));
-    }
-}
-export async function uploadEventImageForUser(uid, eventId, kind, cardId, source) {
-    if (kind === "card" && !cardId)
-        throw new Error("cardId is required when kind is card.");
-    if (kind !== "card" && cardId)
-        throw new Error("cardId is only valid when kind is card.");
-    const event = await readEvent(eventId, uid, "edit");
-    const previous = readImageRef(event, kind, cardId);
-    const sourceBuffer = await readImageSource(source);
-    const previousMasterPath = storagePathFromDownloadUrl(previous.imageMasterUrl);
-    const deleteWarnings = [];
-    let deletesAttempted = 0;
-    // 🔴 Сначала загрузка, потом удаление старого. Прежде варианты карточки
-    // стирались ДО `uploadMasterImage`, и упавшая загрузка оставляла документ
-    // Firestore со ссылками на удалённые объекты — зритель получал 404, а
-    // повтор восстановить их уже не мог. Соседняя ветка для не-карточек (ниже)
-    // всегда делала правильно; расходились только они.
-    //
-    // Порядок безопасен: новый master пишется по тому же пути, и CF4
-    // перезаписывает все три варианта заново. Худшее, что даёт отказ CF4, —
-    // варианты от прежней картинки рядом с новым мастером, и это заметно
-    // меньшая беда, чем битые ссылки.
-    const uploaded = await uploadMasterImage(eventId, kind, cardId, sourceBuffer);
-    if (!uploaded)
-        throw new Error("Image upload did not return a result.");
-    // 🔴 Старые варианты по ТОМУ ЖЕ пути не удаляются — и не нужны.
-    //
-    // Новый master пишется по тому же адресу и запускает CF4, которая
-    // перезаписывает все три варианта. Удаление рядом с этим было гонкой: если
-    // CF4 успевала первой, мы сносили объекты, на которые Firestore уже
-    // ссылается, а повторно она не запустится — нового мастера не будет. Зритель
-    // получал 404 навсегда. Прежний комментарий рассуждал только о случае
-    // «CF4 упала» и не рассматривал «CF4 успела» (ревью 02.09, В5).
-    if (kind !== "card" || (previousMasterPath && previousMasterPath !== uploaded.storagePath) || (!previous.imageMasterUrl && previous.imageUrl)) {
-        const cleanup = await deleteStorageUrls(eventId, previous.imageMasterUrl, previous.imageUrl);
-        deletesAttempted += cleanup.attempted;
-        deleteWarnings.push(...cleanup.warnings);
-    }
-    return {
-        eventId,
-        kind,
-        imageId: uploaded.imageId,
-        storagePath: uploaded.storagePath,
-        masterUrl: uploaded.masterUrl,
-        variantsPending: true,
-        sourceBytes: sourceBuffer.byteLength,
-        masterBytes: uploaded.masterBytes,
-        imageWidth: uploaded.imageWidth,
-        imageHeight: uploaded.imageHeight,
-        note: "Image master uploaded. CF generateImageVariants should publish thumb/card/hero variants and update imageUrl/imageVariants in about 10-30 seconds.",
-        storageDeletesAttempted: deletesAttempted,
-        storageDeleteWarnings: deleteWarnings,
-    };
-}