leostera/riot

Riot-Dienste

Serviceloop

1. Verwende zuerst riot-contributor für den Repository-Workflow, die Handhabung von nicht bereinigtem Arbeitsverzeichnis und Validierungserwartungen.
2. Arbeite aus dem spezifischen Website-/Diensteverzeichnis; jeder Dienst besitzt seine eigenen package.json, bun.lock, tsconfig.json und normalerweise wrangler.toml.
3. Verwende bun run <script> anstelle der direkten Verwendung von Tools, wenn ein Skript existiert.
4. Bewahre service-spezifische Lockfiles auf. Füge keinen JS-Workspace auf Repository-Ebene hinzu, es sei denn, es wird explizit verlangt.
5. Behandle Bereitstellungen, Remote-Migrationen, Live-E2E-Tests, Token-Änderungen, DNS-Änderungen und Änderungen an Produktionsdaten als Operationen, die eine explizite Benutzerfreigabe erfordern.
6. Bevorzuge lokale Prüfungen und Fakes; Live-Tests sind durch service-spezifische Umgebungsvariablen opt-in.

Dienstzuordnung

• sites/api.pkgs.ml: Paket-Registry-Steuerungsebene Worker. Besitzt Veröffentlichung/Authentifizierung/Suche/Ansichten/Ereignisse, D1-Migrationen, Drizzle-Schema, R2-Speicherschlüssel, Warteschlangen, Durable-Object-Veröffentlichungskoordination und D1-Backup-Workflow.
• sites/cdn.pkgs.ml: CDN Worker über Paketartefakten, Sparse-Index-Dokumenten, Riot/OCaml-Binärmetadaten und Zugriffsanalysen. Verwendet Registry-Typen/Speicherhilfen aus ../api.pkgs.ml/src wieder.
• sites/docs.pkgs.ml: Generierter Paketdokumentationsdienst. Serviert Dokumentation aus R2, konsumiert Paket-veröffentlichte/verarbeitete Warteschlangen, zeichnet Pipeline-Läufe/Ereignisse in der Registry-D1 auf und verwendet Cloudflare Sandbox-Container für die docs/build-Verifikation.
• sites/pkgs.ml: Öffentliche Paket-Registry-Webanwendung, Astro + Cloudflare-Adapter + React-Inseln. Liest Registry-Ansichts-APIs und Sparse-Index-Dokumente.
• sites/riot.ml: Hauptstatische Riot-Website, Astro + Tailwind, Pages-artige Bereitstellung.
• sites/get.riot.ml: Installationsskript-Weiterleitungs-/Proxy-Worker.

Cloudflare-Werkzeuge

• Verwende Wrangler für den Lebenszyklus von Worker/Astro-Diensten: wrangler dev, wrangler deploy, wrangler d1 migrations apply, wrangler pages deploy, wrangler types und konfigurationsgesteuerte lokale Entwicklung.
• Halte die dienstlokale wrangler-Abhängigkeit aktuell und durch die Lockdatei fixiert, anstatt dich auf eine globale Installation zu verlassen.
• Verwende die einheitliche cf CLI nur für API-/Ressourceninspektion oder Operationen, die sie derzeit bereitstellt, insbesondere Konto, Zone, DNS, D1 API, R2 API, Warteschlangen API, Workers API Metadaten und Schemaerkennung.
• Bevor du cf für echte Cloudflare-Änderungen verwendest, führe npx cf auth whoami aus und überprüfe die Befehlsstruktur mit npx cf agent-context <product> oder npx cf schema <command...>.
• Ersetze Wrangler-Bereitstellungs-/Entwicklungs-/Migrationsskripte nicht durch cf, es sei denn, der dienstspezifische Befehl wurde lokal verifiziert und unterstützt dasselbe konfigurationsgesteuerte Verhalten.

Konfiguration und Bindungen

• Halte wrangler.toml, exportierte Env TypeScript-Schnittstellen und Test-Fake-Umgebungen synchron.
• Bevorzuge explizite Env-Schnittstellen in Worker-Einstiegspunkten und gemeinsam genutzten Modulen.
• Platziere Standardwerte, die keine Geheimnisse sind, in [vars]; halte Geheimnisse in .env, Wrangler-Secrets oder von Cloudflare verwalteten Geheimnissen.
• Füge für D1-Schemaänderungen in api.pkgs.ml SQL-Migrationen unter sites/api.pkgs.ml/migrations/ hinzu und aktualisiere src/schema.ts/DB-Hilfen zusammen.
• Der D1-Zugriff zur Laufzeit erfolgt über Drizzle-Hilfen in api.pkgs.ml/src/db.ts, metadata-db.ts, pipeline-db.ts, access-db.ts oder einem eng benannten Geschwistermodul.
• R2-Objektschlüsselverträge leben in api.pkgs.ml/src/storage.ts; aktualisiere CDN/API/Web-Nutzer und Tests gemeinsam bei Schlüsseländerungen.
• Die Ereignisnutzlastform der Registry ist der benutzersichtbare Dienstverlauf. Füge neue Ereignistypen zu api.pkgs.ml/src/types.ts, DB-Serialisierung, Ansichten und Tests hinzu.

Testen

• Führe bun run check des geänderten Dienstes aus, bevor du fertig bist.
• Führe bun run test aus, wenn der Dienst lokale Tests definiert.
• Führe bun run deploy, bun run migrate:remote oder Live-test:e2e nicht aus, es sei denn, es wird explizit angefordert.
• Für api.pkgs.ml verwenden lokale Tests FakeR2Bucket, FakeD1Database, FakeQueue und FakeExecutionContext aus tests/helpers.ts.
• Für cdn.pkgs.ml verwende Registry-Test-Fakes wieder, anstatt Cloudflare SDK-Mocks zu erfinden.
• Für docs.pkgs.ml bevorzuge Fake-Pipeline-Ausführer und Warteschlangen-Drain-Helfer; bestätige dauerhafte Reihenfolge durch Datenbanksequenz beim Testen von Ereignisströmen.
• Führe für Astro-Dienste bun run check aus; erwarte, dass Astro .astro-Typdateien als Teil der Prüfung neu generiert.

Webarbeit

• Passe den bestehenden UI-Stack jedes Dienstes an. pkgs.ml verwendet Astro-Serverausgabe, React-Inseln, Tailwind und Cloudflare-Adapter; docs*.ml verwenden Starlight, wo zutreffend; riot.ml ist eine statische Astro-Website.
• Halte die ersten Bildschirme als tatsächliche Produkt-/Dienstoberflächen, nicht als Marketing-Platzhalter.
• Verwende vorhandene Komponenten, Layouts, CSS-Token, Schriftarten und Routen-Konventionen, bevor du Abstraktionen hinzufügst.
• Bevorzuge für Registry-Webänderungen Registry-Ansichts-APIs in sites/pkgs.ml/src/lib/web-views.ts und Sparse-Index-Hilfen in package-index.ts.

Betriebssicherheit

• Behandle Produktionsendpunkte als echt: api.pkgs.ml, registry.pkgs.ml, cdn.pkgs.ml, pkgs.ml, docs.pkgs.ml, docs.riot.ml, play.riot.ml, riot.ml und get.riot.ml.
• Führe niemals Remote-D1-Wiederherstellung/Export/Import, DNS-Schreibvorgänge, Routen-/Domain-Schreibvorgänge, Bereitstellungen oder Token-Operationen ohne explizite Benutzeranweisung aus.
• Wenn ein Live-Smoke-Test angefordert wird, lies zuerst die README/Umgebungsgates dieses Dienstes und gib an, welche Umgebungsvariablen den Test destruktiv oder authentifiziert machen.