leostera/riot

Services Riot

Boucle de Service

1. Utilisez d'abord riot-contributor pour le flux de travail du dépôt, la gestion d'arbre de travail sale et les attentes de validation.
2. Travaillez depuis le répertoire spécifique du site/service ; chaque service possède son propre package.json, bun.lock, tsconfig.json, et généralement wrangler.toml.
3. Utilisez bun run <script> plutôt que d'invoquer directement les outils lorsqu'un script existe.
4. Préservez les lockfiles par service. N'ajoutez pas d'espace de travail JS à la racine du dépôt sauf demande explicite.
5. Traitez les déploiements, migrations distantes, tests e2e en direct, modifications de jetons, modifications DNS et modifications de données de production comme des opérations nécessitant une approbation explicite de l'utilisateur.
6. Privilégiez les vérifications locales et les simulations ; les tests en direct sont optionnels via des variables d'environnement propres au service.

Carte des Services

• sites/api.pkgs.ml : Worker du plan de contrôle du registre de paquets. Gère la publication/authentification/recherche/vues/événements, les migrations D1, le schéma Drizzle, les clés de stockage R2, les files d'attente, la coordination de publication via Durable Object, et le workflow de sauvegarde D1.
• sites/cdn.pkgs.ml : Worker CDN pour les artefacts de paquets, les documents d'index clairsemé, les métadonnées binaires Riot/OCaml et les analyses d'accès. Réutilise les types de registre et les aides de stockage de ../api.pkgs.ml/src.
• sites/docs.pkgs.ml : Service de documentation générée pour les paquets. Sert les documents depuis R2, consomme les files d'attente de publication/traitement des paquets, enregistre les exécutions de pipeline/événements dans le D1 du registre et utilise les conteneurs Cloudflare Sandbox pour la vérification de construction des docs.
• sites/pkgs.ml : Application web publique du registre de paquets, Astro + adaptateur Cloudflare + React islands. Lit les API de vue du registre et les documents d'index clairsemé.
• sites/riot.ml : Site web Riot statique principal, Astro + Tailwind, déploiement de type Pages.
• sites/get.riot.ml : Worker de redirection/proxy pour le script d'installation.

Outillage Cloudflare

• Utilisez Wrangler pour le cycle de vie des services Worker/Astro : wrangler dev, wrangler deploy, wrangler d1 migrations apply, wrangler pages deploy, wrangler types, et le développement local piloté par configuration.
• Maintenez la dépendance wrangler locale au service à jour et épinglée par lockfile plutôt que de vous fier à une installation globale.
• Utilisez l'interface cf unifiée uniquement pour l'inspection d'API/ressources ou les opérations qu'elle expose actuellement, en particulier les comptes, zones, DNS, API D1, API R2, API files d'attente, API Workers, et la découverte de schémas.
• Avant d'utiliser cf pour des mutations Cloudflare réelles, exécutez npx cf auth whoami et inspectez la forme de la commande avec npx cf agent-context <product> ou npx cf schema <command...>.
• Ne remplacez pas les scripts de déploiement/développement/migration de Wrangler par cf sauf si la commande spécifique au service a été vérifiée localement et prend en charge le même comportement piloté par configuration.

Configuration et Liaisons

• Maintenez wrangler.toml, les interfaces TypeScript Env exportées et les environnements de test simulés synchronisés.
• Privilégiez les interfaces Env explicites dans les points d'entrée Worker et les modules partagés.
• Placez les valeurs par défaut non secrètes dans [vars] ; conservez les secrets dans .env, les secrets Wrangler ou les secrets gérés par Cloudflare.
• Pour les modifications de schéma D1 dans api.pkgs.ml, ajoutez des migrations SQL sous sites/api.pkgs.ml/migrations/ et mettez à jour src/schema.ts/les aides DB ensemble.
• L'accès D1 à l'exécution passe par les aides Drizzle dans api.pkgs.ml/src/db.ts, metadata-db.ts, pipeline-db.ts, access-db.ts, ou un fichier frère nommé précisément.
• Les contrats de clés d'objet R2 se trouvent dans api.pkgs.ml/src/storage.ts ; mettez à jour les consommateurs CDN/API/web et les tests lorsque vous modifiez les clés.
• La forme des charges utiles d'événements de registre fait partie de l'historique de service visible par l'utilisateur. Ajoutez les nouveaux types d'événements à api.pkgs.ml/src/types.ts, la sérialisation DB, les vues et les tests.

Tests

• Exécutez bun run check du service modifié avant de terminer.
• Exécutez bun run test lorsque le service définit des tests locaux.
• N'exécutez pas bun run deploy, bun run migrate:remote ou le test:e2e en direct sauf demande explicite.
• Pour api.pkgs.ml, les tests locaux utilisent FakeR2Bucket, FakeD1Database, FakeQueue et FakeExecutionContext de tests/helpers.ts.
• Pour cdn.pkgs.ml, réutilisez les fausses similitudes du registre au lieu d'inventer des mocks SDK Cloudflare.
• Pour docs.pkgs.ml, préférez les exécuteurs de pipeline simulés et les aides de vidage de file d'attente ; affirmez l'ordre durable par séquence DB lors des tests de flux d'événements.
• Pour les services Astro, exécutez bun run check ; attendez-vous à ce qu'Astro régénère les fichiers de type .astro dans le cadre de la vérification.

Travail Web

• Respectez la pile UI existante de chaque service. pkgs.ml utilise la sortie serveur Astro, React islands, Tailwind, et l'adaptateur Cloudflare ; docs*.ml utilisent Starlight le cas échéant ; riot.ml est un site Astro statique.
• Gardez les premiers écrans comme de véritables surfaces produit/service, pas des espaces réservés marketing.
• Utilisez les composants, mises en page, jetons CSS, polices et conventions de routage existants avant d'ajouter des abstractions.
• Pour les modifications web du registre, préférez les API de vue du registre dans sites/pkgs.ml/src/lib/web-views.ts et les aides d'index clairsemé dans package-index.ts.

Sécurité Opérationnelle

• Considérez les points de terminaison de production comme réels : api.pkgs.ml, registry.pkgs.ml, cdn.pkgs.ml, pkgs.ml, docs.pkgs.ml, docs.riot.ml, play.riot.ml, riot.ml, et get.riot.ml.
• N'exécutez jamais de restauration/exportation/importation distante de D1, d'écritures DNS, d'écritures de route/domaine, de déploiements ou d'opérations sur les jetons sans indication explicite de l'utilisateur.
• Si un test de fumée en direct est demandé, lisez d'abord le README/les portes d'entrée des variables d'environnement de ce service et indiquez quelles variables d'environnement rendent le test destructeur ou authentifié.