roninforge-hono

Cursor-Plugin für Hono v4 (TypeScript Edge Web Framework) + TypeScript. Fixiert auf 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+). Lehrt die v4-APIs, die LLMs, die auf Daten vor 2024 trainiert wurden, nicht kennen (c.json() immer typisiert, Validator wirft HTTPException, getCookie/setCookie aus hono/cookie, c.env als Eigenschaft, streamText aus hono/streaming, showRoutes aus hono/dev, getRuntimeKey aus hono/adapter, fire(app) aus hono/service-worker, Workers Static Assets Binding statt des veralteten serveStatic, JSR @hono/hono für Deno). Fängt über 50 LLM-Regressionen mit BAD/CORRECT TypeScript-Paaren.

Es existiert kein Hono v5. Die aktuellste stabile Version ist v4.12.19. Jedes „v5“ im generierten Code ist eine Halluzination.

Das Problem

Die Maintainer von Hono selbst haben die Issues #3906 („llm.txt file“) und #4812 („Official AI Agent Skill for Hono“) eröffnet, explizit weil „LLMs praktisch kein Wissen darüber haben, wie das neueste Hono funktioniert.“ Trainingsdaten von vor 2025 sind aus der v3-Ära. LLMs generieren:

v3 -> v4 entfernte APIs

• c.jsonT() statt c.json() (seit v4.0.0 immer typisiert)
• c.stream() / c.streamText() als Context-Methoden (in v4 nach hono/streaming verschoben)
• c.env() Funktionsform (jetzt Eigenschaft; Laufzeiterkennung via getRuntimeKey() aus hono/adapter)
• c.req.cookie() (entfernt; verwende getCookie(c) aus hono/cookie)
• app.showRoutes(), app.routerName (verschoben nach hono/dev)
• addEventListener('fetch') + app.handleEvent() (Service-Worker-Syntax; verwende export default { fetch: app.fetch })
• app.head(...) Routen (HEAD wird in v4 automatisch von GET abgeleitet)
• hono/nextjs Import (verwende hono/vercel)
• hono/middleware Barrel-Import (verwende pro Middleware-Unterpfad)
• c.req.headers() / c.req.body() / c.req.signal() Accessor-Methoden (verwende c.req.raw.*)
• FC mit impliziten children (verwende PropsWithChildren<P>)
• app.fire() (veraltet seit v4.8.0; verwende fire(app) aus hono/service-worker)
• import { Hono } from 'https://deno.land/x/hono/mod.ts' auf Deno (veraltet seit v4.4.0; verwende jsr:@hono/hono)

Express-/Koa-/Fastify-Verlagerungen (die größte Kategorie)

• Fehlendes return bei c.json() (löst zu undefined auf; v4 wirft „Context is not finalized“)
• res.json() / res.send() statt c.json() (kein res in Hono)
• (req, res, next) Middleware-Signatur (verwende (c, next))
• (err, req, res, next) Error-Middleware (verwende app.onError + HTTPException)
• app.use(express.json()) Body-Parser (Hono parst bedarfsgesteuert via c.req.json())
• import cors from 'cors' von npm (verwende hono/cors)
• supertest für Tests (verwende app.request() / testClient(app))
• c.req.body als bereits geparst (es ist ein ReadableStream)
• c.req.parseBody() für JSON (nur Form/Multipart)
• c.req.text() gefolgt von c.req.json() (Body wird zweimal konsumiert)
• c.userId = ... Inline-Zuweisung (verwende c.set('userId', ...) mit typisierten Variables)

TypeScript-/RPC-Inferenzfehler

• new Hono() ohne Bindings/Variables Generics (c.env ist {})
• Routen als Anweisungen definiert (app.get(...) dann app.post(...)) – wirft RPC-Typen weg
• Sub-App app.route()-Aufrufe als Anweisungen – gleiche Regel
• Rails-artige Controller, die Context herumreichen (verliert Pfadparam-Inferenz, gemäß Hono Best Practices)
• app.use('/path', zValidator(...)) statt als Routenargument (TS-Fehler: 'json' not assignable to 'never')
• c.notFound() in RPC-konsumierten Routen (kann nicht auf Client getypt werden)
• new Response(JSON.stringify(...)) in RPC-Routen (Client sieht unknown)
• hc<AppType>('/') relative URL (wirft Fehler bei $url())
• Wert-Import der Server-App in das Client-Bundle (schleppt drizzle-orm, fs, native Abhängigkeiten – das #1 RPC-Bundle-Bloat-Problem)
• Middleware ohne createMiddleware<Env> (Variables-Typen propagieren nicht)

Cloudflare Workers Fettnäpfchen

• process.env.X in Workers-Code (undefined; verwende c.env.X mit typisierten Bindings)
• fs-/path-Imports in Workers (kein Dateisystem)
• compatibility_flags: ["node_compat"] veraltetes Flag (verwende nodejs_compat)
• Veraltetes serveStatic von hono/cloudflare-workers (seit v4.3.0; verwende Asset-Binding)
• Fehlendes c.executionCtx.waitUntil() für Fire-and-Forget
• Wahrheits-Check if (c.executionCtx) (Getter wirft Fehler auf Bun und Next.js App Router)
• Nicht abgewartete D1 .run() / .first() / .all() (Einfügen wird abgebrochen, wenn Worker terminiert)
• WebSocket-Upgrade ohne Durable Object Weiterleitung (Zustand verschwindet)

Sicherheits-/Produktionslücken

• Keine secureHeaders() Middleware
• Kein csrf() bei cookie-authentifizierten Mutationen
• cors({ origin: '*', credentials: true }) (Browser lassen es stillschweigend fallen; AJAX schlägt fehl)
• Fehlendes bodyLimit() bei POST/PUT-Routen und Pin auf hono >= 4.9.7 für CVE-2025-59139
• Cookies ohne httpOnly/secure/sameSite/path
• sameSite: 'None' ohne secure: true (stillschweigend entfernt)
• Body-logging Middleware ohne Redaktion (Passwörter/Token/PII-Leak)
• Kein etag()/cache() bei statischen GETs
• Hardcodiertes JWT-Geheimnis (leckt via Bundle)
• Großes JSON im Speicher aufbauen statt streamText (Workers 128 MB Grenze)

Routing-/Strukturfehler

• Sub-App notFound Handler (toter Code; nur die oberste Ebene feuert)
• Inkonsistenz beim abschließenden Schrägstrich (/users vs /users/ sind standardmäßig unterschiedliche Routen)
• await next() mehr als einmal (verdoppelt nachgelagerte Arbeit)
• app.use(prefix, mw) + app.route(prefix, subApp) Überlappung (Middleware feuert zweimal)
• app.basePath('/api') als Anweisung (Präfix wird aus dem Typ entfernt)

Laufzeit stillschweigend falsch

• serve(app) auf @hono/node-server (verwende serve({ fetch: app.fetch }))
• export default app auf Workers (verwende export default { fetch: app.fetch })
• Bun.serve({ fetch: app }) (verwende app.fetch)

Kleinere echte Probleme

• c.req.query() ohne Argument bei Erwartung eines einzelnen Werts
• c.req.param('id') in globaler Middleware (undefined, wo :id nicht im Pfad ist)
• Handgemachtes OpenAPI ohne @hono/zod-openapi
• cors() NACH Routen eingebunden (trifft nie zu)

Warum dieses Plugin (im Vergleich zu den bestehenden Community-Hono-Regeln)

Es gibt bereits einige Hono-Regeln auf cursor.directory und in awesome-cursorrules (PR #152): Sie decken c.json() Returns, zValidator + Zod, c.env für Workers, verkettete Routen für RPC und den app.fetch Workers-Export ab. Sie haben drei strukturelle Probleme, die dieses Plugin behebt: