Cursor plugin for Hono v4 (TypeScript edge web framework). 59 LLM regressions with BAD/CORRECT pairs. Pinned to hono ^4.12.19 (>= 4.9.7 for CVE-2025-59139). Covers Express middleware leakage, v3-era removed APIs, RPC inference traps, Cloudflare Workers gotchas, security defaults, JSX SSR hardening.
roninforge/roninforge-hono
Плагин для Cursor для Hono v4 (фреймворк для edge-приложений на TypeScript) + TypeScript. Привязан к hono ^4.12.19, @hono/zod-validator ^0.8.0, @hono/zod-openapi ^1.4.0 (peer zod ^4.x), @hono/node-server ^2.0.3 (Node 20+). Обучает API v4, которые LLM, обученные на данных до 2024 года, не знают (c.json() всегда типизирован, валидатор выбрасывает HTTPException, getCookie/setCookie из hono/cookie, c.env как свойство, streamText из hono/streaming, showRoutes из hono/dev, getRuntimeKey из hono/adapter, fire(app) из hono/service-worker, привязка Workers Static Assets вместо устаревшего serveStatic, JSR @hono/hono для Deno). Выявляет 50+ регрессий LLM с парами ПЛОХО / ПРАВИЛЬНО TypeScript.
Hono v5 не существует. Последняя стабильная версия — v4.12.19. Любая "v5" в сгенерированном коде — галлюцинация.
Сами разработчики Hono создали Issue #3906 ("файл llm.txt") и Issue #4812 ("Официальный навык AI-агента для Hono") явно потому, что "LLM практически не имеют знаний о том, как работает последний Hono." Данные для обучения до 2025 года относятся к эпохе v3. LLM выдают:
c.jsonT() вместо c.json() (всегда типизирован начиная с v4.0.0)c.stream() / c.streamText() как методы Context (перенесены в hono/streaming в v4)c.env() в виде функции (теперь свойство; определение среды выполнения через getRuntimeKey() из hono/adapter)c.req.cookie() (удалено; используйте getCookie(c) из hono/cookie)app.showRoutes(), app.routerName (перенесено в )return в c.json() (возвращает undefined; v4 выдает "Context is not finalized")res.json() / res.send() вместо c.json() (в Hono нет res)(req, res, next) сигнатура middleware (используйте (c, next))(err, req, res, next) middleware для ошибок (используйте app.onError + HTTPException)app.use(express.json()) парсер тела (Hono парсит по требованию через c.req.json())new Hono() без обобщений Bindings / Variables (c.env — {})app.get(...) затем app.post(...)) — теряют типы RPCapp.route() как операторы — то же правилоContext (теряют вывод параметров пути, по Hono Best Practices)app.use('/path', zValidator(...)) вместо аргумента маршрута (ошибка TS: 'json' not assignable to 'never')c.notFound() в маршрутах, потребляемых RPC (нельзя типизировать на клиенте)process.env.X в коде Workers (undefined; используйте c.env.X с типизированными Bindings)fs / path в Workers (нет файловой системы)compatibility_flags: ["node_compat"] (используйте nodejs_compat)serveStatic из hono/cloudflare-workers (начиная с v4.3.0; используйте привязку assets)c.executionCtx.waitUntil() для fire-and-forgetif (c.executionCtx) (геттер выбрасывает исключение на Bun и Next.js App Router).run() / / (вставка отменяется при завершении worker)secureHeaders()csrf() на cookie-аутентифицированных мутацияхcors({ origin: '*', credentials: true }) (браузеры молча отбрасывают; AJAX падает)bodyLimit() на POST / PUT маршрутах и фиксация hono >= 4.9.7 для CVE-2025-59139httpOnly / secure / sameSite / pathsameSite: 'None' без secure: true (молча отбрасывается)etag() / на статических GETnotFound для подприложения (мёртвый код; срабатывает только верхнего уровня)/users и /users/ — разные маршруты по умолчанию)await next() более одного раза (удваивает работу нижестоящих)app.use(prefix, mw) + app.route(prefix, subApp) (middleware срабатывает дважды)app.basePath('/api') как оператор (префикс теряется из типа)serve(app) на @hono/node-server (используйте serve({ fetch: app.fetch }))export default app на Workers (используйте export default { fetch: app.fetch })Bun.serve({ fetch: app }) (используйте app.fetch)c.req.query() без аргумента, когда ожидается одно значениеc.req.param('id') в глобальном middleware (undefined, где :id нет в пути)@hono/zod-openapicors() подключён ПОСЛЕ маршрутов (никогда не совпадает)Несколько правил Hono уже существуют на cursor.directory и в awesome-cursorrules (PR #152): они покрывают возврат c.json(), zValidator + Zod, c.env для Workers, цепочки маршрутов для RPC и экспорт Workers app.fetch. У них есть три структурных проблемы, которые исправляет этот плагин:
c.jsonT, c.stream, c.env(), c.req.cookie, app.showRoutes, баррель hono/middleware и app.handleEvent — всё удалено в v4.0.0 (февраль 2024). Существующие правила молча их допускают.(req, res, next), (err, req, res, next), npm cors, app.use(express.json()), supertest, отсутствие return у c.json — всё постоянно встречается в коде Hono, сгенерированном LLM. Существующие правила считают это единичными случаями.Этот плагин поставляет:
globs, так что проверки маршрутов / RPC срабатывают на src/routes/**, проверки Workers — на wrangler.{toml,jsonc} + входной точке Worker, проверки безопасности — на файлах middleware и т.д./hono-new-route, /hono-rpc-setup, /hono-cloudflare-workers-setup, /hono-migrate-to-v4, /hono-validatecorrect-sample (эталонный Hono 4.12.19 + Workers + D1 + Drizzle + Zod) и anti-pattern-sample (наследие Hono v3 с 25+ отслеживаемыми нарушениями)Скопируйте правила, навыки и агента в конфигурацию Cursor вашего проекта. Предварительно сделайте резервную копию существующих файлов; cp -r перезапишет правила с теми же именами.
git clone https://github.com/RoninForge/roninforge-hono.git
# Используйте -n, чтобы не затереть существующее настроенное правило с тем же именем.
cp -rn roninforge-hono/rules/* your-project/.cursor/rules/
cp -rn roninforge-hono/skills/* your-project/.cursor/skills/
cp -rn roninforge-hono/agents/* your-project/.cursor/agents/
Или подключите весь репозиторий как git-подмодуль в your-project/.cursor/plugins/. Обратитесь к документации Cursor по плагинам для получения актуального пути глобальной установки в вашей версии Cursor.
tests/fixtures/correct-sample/ — минимальный проект Hono 4.12.19 + Cloudflare Workers + D1 + Drizzle + Zod, демонстрирующий эталонную форму: цепочечные маршруты, типизированный RPC, zValidator как аргумент маршрута, типизированные ответы c.json({ ... } as const, status), стек secureHeaders + cors + csrf + bodyLimit, app.onError + app.notFound на верхнем уровне, export default { fetch: app.fetch } satisfies ExportedHandler<Env>.
tests/fixtures/anti-pattern-sample/ — наоборот. Каждый файл нарушает пронумерованный антипаттерн. package.json намеренно фиксирует hono ^3.12.0 + cors ^2.8.5 + supertest ^6.3.0 + @hono/sentry ^1.0.0 + lucia ^3.2.0 — эпоха v3 является базой данных обучения LLM для большинства моделей до 2025 года, плюс устаревшие сопутствующие пакеты, которые LLM всё ещё рекомендуют. Отслеживаемые нарушения включают: отсутствие возврата у c.json (#1), форма обработчика Express (req, res) (#2), middleware (req, res, next) (#3), (err, req, res, next) (#4), npm cors (#6), supertest (#12), c.jsonT (#13), addEventListener('fetch') + app.handleEvent (#15), (#16), вызов функции (#17), баррель (#20), (#23), отсутствие Bindings/Variables (#24), в маршруте RPC (#29), в Workers (#34), флаг (#36), из (#37), невыполненные D1 (#40), cors + credentials (#43), cookie без (#45), без (#46), жёстко закодированный секрет JWT (#48), подприложения (#50), как оператор (#53), на Workers (#55), устаревшие ссылки + .
Правила ориентированы на hono ^4.12.19 с Node 20+ (при работе на Node), Bun последней версии, Deno последней версии, Wrangler ^4.0.0. Большинство паттернов работают вплоть до Hono 4.0.0 (февраль 2024) с указанными отличиями. Минимальные версии:
hono >= 4.9.7 обязательно — исправление обхода CVE-2025-59139 / GHSA-92vj-g62v-jqhh bodyLimithono >= 4.12.18 обязательно при рендеринге JSX SSR — защита имён тегов, имён атрибутов, CSS-инъекций@hono/node-server >= 2.0.0 требует Node 20+@hono/zod-openapi >= 1.0.0 требует zod ^4.0.0 (peer — только ^4.0.0, не ^3.x)compatibility_date >= "2024-09-23" требуется, чтобы nodejs_compat подразумевал nodejs_compat_v2Там, где правило ссылается на версию (c.json() всегда типизирован с v4.0.0, c.text() типизирован с v4.3.0, JSR для Deno с v4.4.0, secureHeaders Permissions-Policy с v4.6.0, валидатор Standard Schema с v4.7.0, fire(app) с v4.8.0, JSR parseResponse с v4.9.0, типизированный базовый URL на hc с v4.11.0, метод $path() с v4.12.0), перед принятием сверьтесь с журналом изменений для вашей установленной версии.
MIT — смотрите LICENSE
RoninForge создаёт бесплатные инструменты для разработчиков, работающих с AI-помощниками по коду:
hono/devaddEventListener('fetch') + app.handleEvent() (синтаксис Service Worker; используйте export default { fetch: app.fetch })app.head(...) маршруты (HEAD автоматически выводится из GET в v4)hono/nextjs импорт (используйте hono/vercel)hono/middleware баррель-импорт (используйте отдельный подпуть для каждого middleware)c.req.headers() / c.req.body() / c.req.signal() методы доступа (используйте c.req.raw.*)FC с неявными children (используйте PropsWithChildren<P>)app.fire() (устарело с v4.8.0; используйте fire(app) из hono/service-worker)import { Hono } from 'https://deno.land/x/hono/mod.ts' на Deno (устарело с v4.4.0; используйте jsr:@hono/hono)import cors from 'cors' из npm (используйте hono/cors)supertest для тестов (используйте app.request() / testClient(app))c.req.body как уже распарсенный (это ReadableStream)c.req.parseBody() для JSON (только form / multipart)c.req.text() затем c.req.json() (тело потребляется дважды)c.userId = ... прямое присваивание (используйте c.set('userId', ...) с типизированными Variables)new Response(JSON.stringify(...)) в маршрутах RPC (клиент видит unknown)hc<AppType>('/') относительный URL (выбрасывает ошибку при $url())drizzle-orm, fs, нативные зависимости – главная ловушка раздувания бандла RPC)createMiddleware<Env> (типы Variables не распространяются).first().all()cache()streamText (лимит Workers 128MB)secureHeaders() / csrf(); ни один не упоминает bodyLimit CVE-2025-59139 (исправление в v4.9.7); ни один не затрагивает ловушки клиента RPC (относительный URL, утечка импорта значения, типизация c.notFound).| Правило | Область (globs) | Что делает |
|---|
hono-anti-patterns | **/*.ts,**/*.js,**/*.tsx,**/*.jsx,wrangler.{toml,jsonc,json} | 59 регрессий LLM с парами ПЛОХО / ПРАВИЛЬНО, организованные A-H по категориям (утечки Express, API эпохи v3, TypeScript / RPC, CF Workers, безопасность, маршрутизация, среда выполнения, мелкие проблемы) |
hono-core | **/*.ts,**/*.tsx,**/*.js,**/*.jsx (alwaysApply) | Инициализация приложения с типизированными Bindings + Variables, API Context, методы доступа к запросу, сигнатура middleware, список встроенных middleware, вспомогательные функции для cookie, определение среды выполнения |
hono-routing-and-rpc | src/**/*.ts,src/routes/**/*,src/api/**/*,src/server/**/*,src/client/**/*,routes/**/* | Цепочки маршрутов, композиция подприложений, неизменность basePath, исправление перекрытия двойного выполнения, мёртвый код notFound подприложения, настройка hc<AppType>, правило import type, типизированный базовый URL, $path(), интеграция с TanStack Query / SWR, factory.createHandlers, смягчение для 30+ маршрутов RPC |
hono-validators | src/**/*.ts,routes/**/*.ts,api/**/*.ts,handlers/**/*.ts | Размещение @hono/zod-validator, метод доступа c.req.valid(), валидатор выбрасывает ошибку, @hono/zod-openapi (подводный камень peer zod ^4), @hono/standard-validator, @hono/valibot-validator, встроенный hono/validator, дерево решений |
hono-cloudflare-workers | src/**/*.ts,worker/**/*.ts,workers/**/*.ts,wrangler.{toml,jsonc,json},**/cloudflare-env.d.ts,**/worker-configuration.d.ts | Каноническая форма wrangler.jsonc, правила флагов совместимости, wrangler types, типизированные Bindings, c.env vs process.env, c.executionCtx.waitUntil + переносимость, привязка Static Assets, ожидание D1, стек Drizzle + D1, подводный камень Hyperdrive + Prisma адаптер, Durable Objects для WebSockets, правило hono/cache для пользовательских доменов, экспорт ES Module Worker |
hono-security | src/**/*.ts,src/**/*.tsx,src/middleware/**/*.ts,src/auth/**/*.ts,src/index.ts,src/app.ts | secureHeaders(), csrf(), белый список CORS, bodyLimit() + фиксация CVE-2025-59139 c min версией 4.9.7, настройки cookie по умолчанию, секрет JWT из c.env, логирование без утечек PII, etag() + cache(), ограничение по IP, тайм-ауты, ID запроса, решение по библиотеке аутентификации (Lucia устарела; рекомендуется Better Auth / Clerk), @sentry/hono вместо @hono/sentry |
hono-error-handling | src/**/*.ts,routes/**/*.ts,api/**/*.ts,middleware/**/*.ts,src/index.ts,src/app.ts | Канонический выброс HTTPException, глобальный обработчик app.onError, app.notFound только на верхнем уровне, типизированные ошибки RPC через discriminated unions, валидатор выбрасывает исключение, Sentry через @sentry/hono, структурированное логирование с редактированием pino, единый формат тела ответа об ошибке |
hono-jsx | **/*.tsx,**/*.jsx,**/jsx-runtime.ts,src/components/**/*,src/views/**/*,src/islands/**/*,app/islands/**/* | hono/jsx на стороне сервера, настройка tsconfig, FC НЕ включает children, middleware jsxRenderer для макетов, hono/jsx/streaming с Suspense, клиентские компоненты hono/jsx/dom, острова HonoX, интеграция htmx, фиксация безопасности JSX SSR c min версией 4.12.18 |
hono-testing | **/*.test.ts,**/*.test.tsx,**/*.spec.ts,**/*.spec.tsx,vitest.config.{ts,js},**/test/**/*.ts,**/tests/**/*.ts,**/__tests__/**/*.ts | Универсальный паттерн app.request(), типизированные тесты RPC с testClient(app), Vitest + @cloudflare/vitest-pool-workers для D1 в реальной среде, фикстура applyD1Migrations, Bun + bun:test, снапшот-тестирование, тестирование middleware / валидатора / waitUntil, НИКОГДА supertest |
hono-deployment | wrangler.{toml,jsonc,json},deno.json,deno.jsonc,package.json,Dockerfile,fly.toml,vercel.json,netlify.toml,**/serverless.yml,**/template.yaml | Cloudflare Workers (wrangler.jsonc + флаги совместимости), Bun.serve, Deno + JSR, @hono/node-server v2 (Node 20+), AWS Lambda + Lambda@Edge, Vercel Edge, Netlify, конвейеры сборки, минимальные версии, распространённые ошибки развёртывания |
| Навык | Команда | Что делает |
|---|
| Новый маршрут | /hono-new-route | Создаёт цепочечное подприложение с zValidator как аргументом маршрута, типизированным доступом через c.req.valid(), c.json({ ... } as const, status) для типизированных ответов RPC, обобщениями Bindings + Variables, экспортом подприложения как typeof users, подключением к родительскому через цепочечный .route(). Отклоняет контроллеры в стиле Rails, c.notFound() в маршрутах RPC, сырой new Response(). |
| Настройка RPC | /hono-rpc-setup | Создаёт клиент hc<AppType> с import type (основное правило), абсолютным базовым URL, типизированным общим модулем api, интеграцией с TanStack Query / SWR через InferRequestType / InferResponseType, утилитой parseResponse, методом $path(), смягчением замедления IDE для 30+ маршрутов. |
| Настройка Workers | /hono-cloudflare-workers-setup | Создаёт новый проект Hono + Workers с wrangler.jsonc (НЕ .toml), nodejs_compat, типизированными Bindings, сгенерированными из wrangler types, паттерном D1 + Drizzle middleware, стеком secureHeaders + cors + csrf + bodyLimit, конфигом Vitest для @cloudflare/vitest-pool-workers. |
| Миграция на v4 | /hono-migrate-to-v4 | Поэтапная миграция v3 -> v4: обновление минимальных версий (фиксация CVE-2025-59139), замена c.jsonT / c.stream / c.env() / c.req.cookie / app.showRoutes / app.handleEvent, удаление барреля hono/middleware, переход Deno на JSR, @hono/node-server v2 + Node 20+, регистрация app.onError для выбросов валидатора. |
| Валидация | /hono-validate | Запуск validate-plugin.sh + tsc --noEmit + тесты + grep-аудит синтаксических антипаттернов, которые не ловит проверка типов (c.jsonT, c.req.cookie, process.env, node_compat, serveStatic из hono/cloudflare-workers, жёстко закодированный секрет JWT, sameSite:'None' без secure, отсутствие bodyLimit, импорт значения в клиенте hc). |
| Агент | Что делает |
|---|
hono-reviewer | Проверяет код Hono v4 + TypeScript по серьёзности. CRITICAL: hono < 4.9.7 (CVE), ссылки на v5 (галлюцинация), cors с wildcard + credentials, sameSite:'None' без secure, жёстко закодированный секрет JWT, process.env в Workers, отсутствие bodyLimit, нет csrf на cookie-аутентификации, устаревший serveStatic, JSX SSR на версии < 4.12.18. ERROR: отсутствие возврата у c.json, формы middleware из Express, все удалённые API эпохи v3, нецепочечные маршруты / подприложения, Rails-контроллеры, размещение zValidator, c.notFound/сырой Response в RPC, относительный URL hc(), импорт значения серверного приложения, невыполненные D1, формы экспорта среды выполнения. WARN: настройки cookie по умолчанию, secureHeaders, логирование тела без редактирования, app.onError, notFound подприложения, проверка истинности c.executionCtx, отсутствие обобщения Bindings, cors после маршрутов, перекрытие middleware, оператор basePath, конечные слеши, баррель hono/middleware, wrangler.toml на новом проекте, Lucia, @hono/sentry. NIT: отсутствие satisfies ExportedHandler<Env>, самостоятельный OpenAPI, отсутствие observability.enabled. |
c.req.cookiec.env()hono/middlewareapp.head()c.notFoundprocess.envnode_compatserveStatichono/cloudflare-workers*httpOnly/secure/sameSite/pathsameSite:'None'secure:truenotFoundbasePathexport default app@hono/sentrylucia