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)

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())

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)

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() / / (Einfügen wird abgebrochen, wenn Worker terminiert)

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()/ bei statischen GETs

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:

1. Sie decken NICHT die v3 -> v4 entfernten APIs ab. LLMs generieren weiterhin c.jsonT, c.stream, c.env(), c.req.cookie, app.showRoutes, den hono/middleware-Barrel und app.handleEvent – alle in v4.0.0 (Februar 2024) entfernt. Bestehende Regeln erlauben sie stillschweigend.
2. Sie lassen die Express-Verlagerungsklasse aus. (req, res, next), (err, req, res, next), npm cors, app.use(express.json()), supertest, fehlendes return bei c.json – all das passiert ständig in LLM-generiertem Hono-Code. Bestehende Regeln behandeln sie als Einzelfälle.

Dieses Plugin liefert:

• 10 MDC-Regeln mit passenden globs, sodass die Routen-/RPC-Prüfungen auf src/routes/** feuern, Workers-Prüfungen auf wrangler.{toml,jsonc} + Worker-Einstieg, Sicherheitsprüfungen auf Middleware-Dateien usw.
• 59 dokumentierte Anti-Patterns mit BAD/CORRECT TypeScript-Paaren
• 5 Skills: /hono-new-route, /hono-rpc-setup, /hono-cloudflare-workers-setup, /hono-migrate-to-v4, /hono-validate
• 1 Reviewer-Agent mit Schweregrad-Gruppierung (CRITICAL / ERROR / WARN / NIT) und dateibasierten Prüfungen
• 2 Fixture-Projekte: correct-sample (Goldstandard Hono 4.12.19 + Workers + D1 + Drizzle + Zod) und anti-pattern-sample (Hono v3-Nachwehen mit über 25 verfolgten Verstößen)

Installation

Kopieren Sie die Regeln, Skills und den Agenten in die Cursor-Konfiguration Ihres Projekts. Sichern Sie zuerst Ihre vorhandenen Dateien; cp -r überschreibt gleichnamige Regeln.

git clone https://github.com/RoninForge/roninforge-hono.git

# Verwenden Sie -n, um das Überschreiben einer vorhandenen angepassten Regel mit demselben Namen zu vermeiden.
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/

Oder binden Sie das gesamte Repository als Git-Submodul unter your-project/.cursor/plugins/ ein. Siehe die Cursor-Plugin-Dokumentation für den aktuellen globalen Installationspfad Ihrer Cursor-Version.

Was enthalten ist

Regeln (10 Dateien)

Skills (5 Befehle)

Agent (1 Unteragent)

Testprojekte

tests/fixtures/correct-sample/ ist ein schlankes Hono 4.12.19 + Cloudflare Workers + D1 + Drizzle + Zod-Projekt, das die Goldstandard-Form demonstriert: verkettete Routen, typisierte RPC, zValidator als Routenargument, c.json({ ... } as const, status) typisierte Antworten, secureHeaders + cors + csrf + bodyLimit-Stack, app.onError + app.notFound auf oberster Ebene, export default { fetch: app.fetch } satisfies ExportedHandler<Env>.

tests/fixtures/anti-pattern-sample/ ist das Gegenteil. Jede Datei verletzt einen nummerierten Anti-Pattern. package.json pinnt absichtlich hono ^3.12.0 + cors ^2.8.5 + supertest ^6.3.0 + @hono/sentry ^1.0.0 + lucia ^3.2.0 – die v3-Ära ist die LLM-Trainingsdaten-Basislinie für die meisten Modelle vor 2025, plus veraltete Begleiter, die LLMs immer noch empfehlen. Verfolgte Verstöße umfassen: fehlendes return bei c.json (#1), (req, res) Express-Handler-Form (#2), (req, res, next) Middleware (#3), (err, req, res, next) (#4), npm cors (#6), supertest (#12), c.jsonT (#13), addEventListener('fetch') + app.handleEvent (#15), (#16), Funktionsaufruf (#17), Barrel (#20), (#23), keine Bindings/Variables (#24), in RPC-Route (#29), in Workers (#34), Flag (#36), von (#37), nicht abgewartete D1 (#40), cors + credentials (#43), Cookie ohne (#45), ohne (#46), hardcodiertes JWT-Secret (#48), Sub-App (#50), als Anweisung (#53), auf Workers (#55), veraltete + -Referenzen.

Versionsverwaltung

Regeln zielen auf hono ^4.12.19 mit Node 20+ (wenn auf Node), Bun aktuell, Deno aktuell, Wrangler ^4.0.0. Die meisten Muster funktionieren zurück bis Hono 4.0.0 (Feb. 2024) mit den inline genannten Abweichungen. Pin-Untergrenzen:

• hono >= 4.9.7 obligatorisch – CVE-2025-59139 / GHSA-92vj-g62v-jqhh bodyLimit-Bypass-Fix
• hono >= 4.12.18 obligatorisch, wenn JSX SSR gerendert wird – Härtung von Tag-Namen, Attribut-Namen, CSS-Injection
• @hono/node-server >= 2.0.0 erfordert Node 20+
• @hono/zod-openapi >= 1.0.0 erfordert zod ^4.0.0 (Peer ist NUR ^4.0.0, nicht ^3.x)
• compatibility_date >= "2024-09-23" erforderlich, damit nodejs_compat nodejs_compat_v2 impliziert

Wo die Regel eine Version zitiert (c.json() immer typisiert seit v4.0.0, c.text() typisiert seit v4.3.0, JSR für Deno seit v4.4.0, secureHeaders Permissions-Policy seit v4.6.0, Standard-Schema-Validator seit v4.7.0, fire(app) seit v4.8.0, JSR parseResponse seit v4.9.0, typisierte Basis-URL auf hc seit v4.11.0, $path()-Methode seit v4.12.0), überprüfen Sie gegen das Changelog der installierten Version, bevor Sie übernehmen.

Lizenz

MIT – siehe LICENSE

Links

• Hono offizielle Dokumentation
• Hono GitHub
• Hono Migrationsanleitung (v3 -> v4)
• Hono Best Practices
• Hono RPC
• Cloudflare Workers Framework-Anleitung für Hono
• Cursor Plugin-Dokumentation
• RoninForge

Weiteres von RoninForge

RoninForge baut kostenlose Werkzeuge für Entwickler, die mit KI-Code-Assistenten arbeiten:

• LLM-API-Preisvergleich – Token-Preise von Claude, GPT, Gemini, DeepSeek, Mistral und Grok nebeneinander, verifiziert gegenüber offiziellen Preisseiten
• GitHub Copilot AI Credits Rechner – schätzen Sie Ihren monatlichen Credit-Verbrauch unter nutzungsbasierter Abrechnung
• Alle Cursor-Plugins