inngest-brownfield-audit

Официальный skill Inngest предназначен для аудита уже существующего TypeScript- или JavaScript-репозитория перед внедрением Inngest. Он подходит, когда нужно понять, где фоновые операции теряются при деплое или падении процесса, какие webhook-обработчики, cron-задачи, polling-циклы, очереди, долгие операции и AI-workflows требуют более надёжного выполнения, а также где Inngest вообще не нужен. Это не универсальная миграция и не обещание автоматически исправить найденные места: инструкция требует опираться на факты конкретного репозитория и менять его небольшими проверяемыми шагами. Работа начинается с карты проекта. Нужно прочитать package.json, workspace-файлы, структуру app или router, серверные точки входа, deployment-конфигурацию и тестовые команды. Затем определяется фреймворк и его вариант: среди примеров указаны Next.js App Router и Pages Router, Express, Hono, Fastify, Remix, SvelteKit, Astro, NestJS и worker-only сервисы. Одновременно проверяется package manager и локальные соглашения TypeScript, чтобы предлагаемая интеграция соответствовала уже работающему проекту. Такой порядок не позволяет подменить анализ репозитория общим рецептом для другого runtime. Следующий шаг — проверить, не используется ли Inngest частично или уже корректно. Источник предлагает искать createFunction, serve, endpoint /api/inngest, переменные INNGEST_, step.run, step.sleep, step.waitForEvent, step.sendEvent, step.invoke, step.ai, inngest.send и realtime API. Если интеграция уже есть, проверяются версия, общий client, serve endpoint, список зарегистрированных functions, имена событий, переменные окружения и форма API. Для существующего setup отдельно сверяются стабильный app id, локальный INNGEST_DEV=1, production INNGEST_SIGNING_KEY, устойчивые идентификаторы шагов и единый endpoint, а не создаётся второй client или дублирующий маршрут. Поиск durability gaps охватывает несколько классов риска. Для fire-and-forget работы проверяются void-вызовы, неожидаемые promises, цепочки .then, setTimeout, setInterval и фоновые действия после HTTP-ответа. Для расписаний и очередей ищутся cron, node-cron, bull, bullmq, agenda, qstash и SQS. Для webhook-потоков проверяются Stripe, Clerk, GitHub, Slack, Shopify, HubSpot, Linear, Svix и общие webhook-обработчики. Отдельно рассматриваются PDF и export, обработка видео или изображений, embeddings, рассылки, imports, ETL, внешние API, retries, polling, tool loops, LLM-вызовы, streaming, human approval, vector search и evaluation loops. Само совпадение по поиску не является основанием для миграции — нужен конкретный файл, call site и описанный failure mode. Каждый найденный кандидат классифицируется как P0, P1 или P2. P0 — пользовательская потеря, дублирующий платёж, письмо или действие, пропущенный webhook, timeout либо crash-prone workflow. P1 — хрупкая, но восстанавливаемая фоновая работа, ручные retries или шумные 429. P2 — cleanup, удобство и будущая возможность миграции. Для записи нужны файл, текущий trigger, side effects, idempotency key, причина сбоя, подходящий Inngest primitive, размер изменения и уровень уверенности. Это помогает отделить реальную потребность в durable execution от гипотетической перестройки. Рекомендуемый путь — один небольшой vertical slice. Существующие domain-функции и модели данных сохраняются, Inngest client и serve endpoint добавляются только один раз, а side effects постепенно переносятся внутрь step.run. До retries нужно сделать event IDs и записи в БД идемпотентными. Для HTTP-обработчика типовой вариант — быстро принять запрос, сохранить намерение и отправить событие с устойчивым id; для webhook — проверить подпись и отправить идемпотентное событие; для cron — durable function с постраничными step.run; для fan-out — оркестратор и отдельная работа на элемент. Внешние лимиты обслуживаются через concurrency, throttle или rateLimit, а не через самодельный in-process throttler. Для AI-workflow skill предлагает сохранять пользовательское намерение и выполнять каждый model call, tool call, vector search и внешний side effect в отдельном step.ai или step.run. Ожидание human review и внешнего события должно использовать step.waitForEvent или step.waitForSignal с timeout, а прогресс — realtime publish между шагами. Не следует держать состояние агента только в памяти, повторять весь цикл после одной ошибки инструмента, повторно оплачивать успешный model call без memoization или строить follow-up через setTimeout. Эти рекомендации относятся к durable progress и retry-safe границам, а не к выбору конкретного LLM-провайдера. У интеграции есть обязательные guardrails. Нельзя слепо заменять работающие queues, crons или webhooks; сначала сохраняется поведение тонким Inngest-слоем. Database writes, API calls, random IDs, timestamps и LLM calls новой функции должны находиться внутри steps. Retries не скрывают отсутствие idempotency. Имена событий следуют форме domain/noun.verb, step IDs должны быть стабильными и описательными, а replayable events — иметь детерминированные IDs. Для realtime используется актуальный Inngest API, без добавления второго клиента или устаревшей библиотеки в уже рабочий проект. Итог аудита — конкретный план, а не копия документации: состояние существующего Inngest, framework с доказательствами, лучший первый slice, причина риска, primitives, idempotency key, затрагиваемые файлы и проверки. После изменения проверяются typecheck, build, lint и тесты вокруг мигрируемого workflow; если доступен локальный runtime, дополнительно подтверждаются sync функции и тестовое событие. Если runtime-проверка невозможна, это фиксируется явно. Skill не является security-аудитом и не гарантирует успешность произвольного deployment: он направляет к доказательному анализу конкретного репозитория, малому изменению и проверяемому результату.