@overcrow/mcp 0.0.0 → 0.1.0

package/dist/content/docs/fr/package.md

@@ -0,0 +1,139 @@
+# Le paquet
+
+Un widget PlayerVox OverCrow est distribué en un seul fichier,
+`<id>-<version>.ocpkg` : une archive qui réunit le manifeste, la vue
+compilée, le style, un script, les messages, les images et la licence.
+`overcrow-widget package` la construit, et OverCrow la lit avec le code
+même qui l’a construite.
+
+```sh
+overcrow-widget package
+overcrow-widget inspect dist/com.example.my-widget-0.1.0.ocpkg
+```
+
+`package` vérifie le projet, écrit l’archive dans `dist/` et affiche sa
+taille et son SHA-256. `inspect` montre ce qu’un paquet contient et ce
+qu’il demande, tel que le voit un relecteur.
+
+## Ce qu’il contient
+
+<!-- generated:package-files -->
+| Chemin | Obligatoire | Limite | Signification |
+| --- | --- | --- | --- |
+| `manifest.json` | oui | 64 Kio | Le manifeste, tel qu’il a été écrit. |
+| `ledger.json` | oui | 64 Kio | Registre canonique du SHA-256 et de la taille de chaque autre entrée, écrit par la CLI. |
+| `logic.js` | oui | 512 Kio | Le seul contenu exécutable : un script ES2023 sans import, expressions compilées de la vue comprises. UTF-8, non vide. |
+| `view.json` | oui | 512 Kio | La vue compilée. Le source `view.ocml` n’est pas embarqué. |
+| `style.ocss` | non | 128 Kio | Source de la feuille de style, analysée par l’hôte au démarrage du widget. UTF-8. |
+| `locales/en.json` | non | 256 Kio | Messages en anglais ; présent si et seulement si `locales/fr.json` l’est, avec les mêmes clés. |
+| `locales/fr.json` | non | 256 Kio | Messages en français. |
+| `LICENSE` | oui | 64 Kio | Texte de la licence du paquet. UTF-8, non vide. |
+| `assets/<path>.{png,jpg,jpeg,webp}` | non | 2 Mio | Images dont la signature correspond à l’extension ; segments en minuscules `[a-z0-9_-]`, au plus 4 sous `assets/`. |
+<!-- /generated:package-files -->
+
+Toute autre entrée fait refuser le paquet : un second script, un fichier
+HTML, un module WebAssembly, du code natif, un fichier caché, une autre
+langue. Les fichiers texte sont en UTF-8, sans marque d’ordre d’octets.
+
+Tout ce que vous écrivez n’est pas empaqueté tel quel :
+
+| Dans le projet | Dans le paquet |
+| --- | --- |
+| `manifest.json` | les mêmes octets |
+| `view.ocml` | `view.json`, la vue compilée ; le fichier source n’est pas livré |
+| `logic.ts` ou `logic.js` | `logic.js` : votre module, le SDK et les expressions compilées de la vue, en un seul script |
+| `style.ocss`, `locales/`, `assets/`, `LICENSE` | les mêmes octets |
+| `package.json`, `tsconfig.json`, `node_modules/`, `listing.json`, `tests/` | non empaquetés |
+
+Les images sont des fichiers PNG, JPEG ou WebP placés sous `assets/`, à des
+chemins en minuscules, et le contenu de chaque fichier doit correspondre à
+son extension. La vue en désigne une par `src="assets/logo.png"`, et
+l’aperçu (`preview`) d’une [fiche](publishing.md#la-fiche) est l’une de ces
+images empaquetées.
+
+## Le script
+
+`logic.js` est le seul contenu exécutable d’un paquet. L’outil le construit
+à partir de votre module de logique, du SDK qu’il embarque et d’une
+fonction par expression et par gestionnaire de la vue, puis retire ce qui
+ne sert pas et raccourcit les noms locaux. Deux conséquences :
+
+- le SDK de votre `node_modules` ne sert qu’à la vérification des types :
+  celui qui s’exécute est celui de l’outil, et `inspect` affiche sa
+  version ;
+- la vue elle-même ne contient aucun code : `view.json` désigne les
+  fonctions de `logic.js` par leur numéro.
+
+Un paquet contient des sources qu’OverCrow peut lire et vérifier, jamais de
+bytecode compilé.
+
+## Les mêmes octets à chaque fois
+
+L’empaquetage est déterministe : les mêmes sources et la même version de
+l’outil donnent la même archive, octet pour octet, à chaque exécution et
+sur chaque système. C’est ce qui permet à un relecteur de reconstruire
+votre paquet à partir des sources que vous soumettez, puis de comparer.
+C’est aussi ce qui permet au catalogue de désigner un paquet par son
+SHA-256.
+
+Pour cela, l’archive n’admet qu’une seule structure, exacte : un zip non
+compressé, aux entrées triées, aux dates fixes et sans champ
+supplémentaire. Écrivez-la avec `overcrow-widget package` ; une archive
+produite par un autre outil zip est refusée.
+
+## Le registre
+
+`ledger.json`, écrit par l’outil, liste tous les autres fichiers avec leur
+taille et leur SHA-256. OverCrow le recalcule à partir de l’archive et
+exige les mêmes octets. C’est lui qui lie chaque fichier au paquet : un
+fichier modifié, ajouté ou retiré après l’empaquetage ne correspond plus.
+
+## Comment OverCrow vérifie un paquet
+
+OverCrow valide un paquet en entier lors de son admission au catalogue,
+lors de son installation, puis **à chaque démarrage du widget** :
+
+1. la taille de l’archive, sa structure exacte et la somme de contrôle de
+   chaque entrée ;
+2. chaque chemin, comparé à la liste de fichiers ci-dessus et à leurs
+   limites de taille, ainsi que la présence des fichiers obligatoires ;
+3. le registre, octet pour octet ;
+4. le manifeste, le script, le style, la paire de langues, la licence,
+   chaque image et la vue compilée : des éléments connus à des emplacements
+   autorisés, des attributs connus dont les valeurs ont le bon type, des
+   événements propres à leur élément, des composants utilisés comme ils
+   sont déclarés, les limites de la vue, et la présence dans le paquet de
+   chaque image statique.
+
+Pour un paquet du catalogue, la taille et le SHA-256 de l’archive doivent
+d’abord être ceux qu’indique le catalogue signé, et le manifeste doit être
+identique à celui que liste le catalogue. Un widget dont le paquet échoue à
+l’une de ces vérifications ne démarre pas. `overcrow-widget check` et
+`package` exécutent les mêmes vérifications : vous voyez donc un problème
+avant qu’un utilisateur ne le rencontre.
+
+## Installé depuis le catalogue, ou localement
+
+- Un paquet **issu du catalogue signé** est vérifié : c’est ainsi que les
+  utilisateurs obtiennent les widgets. Voir
+  [publication et revue](publishing.md).
+- Un paquet envoyé par `overcrow-widget dev` est un **paquet de
+  développement** : marqué « Unverified », pour la durée de la session
+  seulement. Voir [le canal de développement](dev-channel.md).
+
+Un paquet qui ne vient pas du catalogue ne peut pas utiliser un ID sous
+`com.playervox`.
+
+## Limites d’un paquet
+
+Les tailles de chaque fichier et de l’archive figurent dans les
+[limites](limits.md#fichiers-du-projet-et-paquet). Quand un paquet dépasse
+une limite, `check` indique laquelle :
+
+| Code | Problème |
+| --- | --- |
+| `project.file_size` | Un fichier source dépasse sa limite. |
+| `project.entry_limit` | Le projet compte plus de fichiers qu’un paquet ne peut en contenir. |
+| `project.asset_path` | Le chemin d’une image n’est pas en minuscules, est trop profond ou porte une autre extension. |
+| `package.file_size` | Un fichier construit (`logic.js`, `view.json`) dépasse sa limite. |
+| `package.archive_size` | L’archive dépasse 16 Mio. |

package/dist/content/docs/fr/publishing.md

@@ -0,0 +1,172 @@
+# Publication et revue
+
+Les widgets atteignent les utilisateurs de PlayerVox OverCrow par le
+catalogue signé des widgets : OverCrow n’installe que ce que liste ce
+catalogue. Cette page va du dossier de sources d’un widget à une version
+listée. Ni une pull request ni une fusion ne publient quoi que ce soit : la
+publication est une étape distincte des mainteneurs, hors de la CI.
+
+## La soumission
+
+Une soumission est le dossier de sources d’un widget, placé sous
+`widgets/<dir>/` du
+[dépôt public](https://github.com/Valhallab/playervox-overcrow-releases),
+dans une pull request vers sa branche `candidate` :
+
+```text
+widgets/<dir>/
+  manifest.json   view.ocml   style.ocss?   logic.ts | logic.js
+  locales/en.json + locales/fr.json?   assets/**?   LICENSE
+  listing.json    (marketplace text, never packaged)
+```
+
+Vous soumettez des sources, pas un paquet : le catalogue livre toujours le
+paquet reconstruit à partir des sources relues.
+
+Les IDs de paquet sous `com.playervox` sont réservés aux widgets publiés
+par PlayerVox. Utilisez un ID en DNS inversé sous un domaine que vous
+contrôlez, et gardez-le : l’ID est l’identité du widget dans le catalogue.
+
+## La fiche
+
+`listing.json` contient ce qu’affiche la marketplace :
+
+<!-- source: docs/content/examples/weather/listing.json -->
+```json
+{
+  "author": "Example Studio",
+  "spdxLicense": "MIT",
+  "sourceUrl": "https://github.com/example/weather-widget",
+  "defaultLocale": "en",
+  "localizations": [
+    { "locale": "en", "name": "Weather", "description": "The temperature of a city, refreshed every 30 minutes." },
+    { "locale": "fr", "name": "Météo", "description": "La température d’une ville, actualisée toutes les 30 minutes." }
+  ]
+}
+```
+
+<!-- generated:listing-fields -->
+| Champ | Type | Obligatoire | Signification |
+| --- | --- | --- | --- |
+| `author` | texte ≤ 128 octets | oui | Texte brut, sans espaces en début ni en fin, sans `<` ni `>`. |
+| `spdxLicense` | texte ≤ 64 octets | oui | Expression SPDX, faite des caractères `[A-Za-z0-9.+-]`. |
+| `sourceUrl` | texte ≤ 2 Kio | oui | URL HTTPS canonique des sources relues, sans port, requête ni fragment. |
+| `defaultLocale` | `locale` | oui | L’une des localisations. |
+| `localizations` | liste de `Localization` ≤ 16 | oui | `{ locale, name, description }` avec des locales distinctes de la forme `xx` ou `xx-YY` ; nom ≤ 128 octets, description ≤ 512 octets. |
+<!-- /generated:listing-fields -->
+
+- `author`, les noms et les descriptions sont du texte brut, sans espace au
+  début ni à la fin, sans `<` ni `>` ; les langues sont de la forme `xx` ou
+  `xx-YY`, l’une d’elles étant `defaultLocale`.
+- `spdxLicense` est une expression SPDX ; le `LICENSE` du paquet en
+  contient le texte. Les widgets PlayerVox sont sous MIT. La politique pour
+  les licences des tiers n’est pas encore arrêtée : une expression valide
+  est relue, pas approuvée par les métadonnées
+  ([licences](../../../LICENSING.md)).
+- `sourceUrl` est une URL HTTPS canonique des sources relues, sans port,
+  requête ni fragment.
+- `preview` (facultatif) désigne un PNG empaqueté sous `assets/`, de
+  256 Kio au plus, par exemple `"preview": "assets/preview.png"`. Le
+  Centre de contrôle et la marketplace le montrent entier dans un cadre
+  4:3, centré sur la couleur `#1e242e`, à 1,5 pixel par point d’écran au
+  plus : rendez le widget à 150 % (`"scale": 1500` dans un scénario) et
+  donnez à l’image un format 4:3, il apparaît à sa taille réelle, jamais
+  recadré ni agrandi.
+
+## L’admission : lancez-la vous-même
+
+```sh
+overcrow-widget admit widgets/<dir>
+overcrow-widget admit widgets/<dir> --package dist/<id>-<version>.ocpkg
+overcrow-widget admit widgets/<dir> --format json
+```
+
+`admit` est exactement l’admission statique de la marketplace. Elle
+n’exécute jamais votre code ni `tsc` :
+
+1. elle construit le dossier comme le fait `package` : toutes les
+   vérifications des sources, du style, de la logique et du paquet, puis le
+   lecteur de paquets d’OverCrow lui-même ;
+2. avec `--package`, la vue compilée de votre archive doit être, octet pour
+   octet, le résultat de la compilation de `view.ocml` ;
+3. elle vérifie les limites du schéma, les IDs réservés, `listing.json`,
+   l’aperçu et, pour les widgets PlayerVox, la licence MIT ;
+4. elle liste pour le relecteur l’autorité que demande le widget :
+   capabilities sensibles, chaque route réseau, écritures dans le
+   presse-papiers, stockage et événements de jeu.
+
+La commande se termine avec le code de sortie 1 quand la soumission serait
+refusée. Ses codes sont listés avec la [commande `admit`](cli.md#admit).
+
+Sur une pull request, l’outil d’admission est construit depuis la branche
+de base relue, jamais depuis votre révision, et il lit vos fichiers comme
+des données : votre JavaScript, votre TypeScript, vos commandes de build,
+vos tests et vos scripts n’y sont jamais exécutés. Une pull request ne peut
+pas modifier les outils de l’admission eux-mêmes.
+
+## La revue
+
+Un mainteneur lit le rapport d’admission et les sources, puis fusionne dans
+`candidate`. Les relecteurs vérifient :
+
+- **L’identité.** Un nouvel ID sous un domaine que l’auteur contrôle. Une
+  nouvelle version pour tout changement : les versions publiées sont
+  immuables, et une version inférieure à une version listée est refusée.
+- **La reproductibilité.** Le paquet est reconstruit à partir des sources
+  relues.
+- **L’autorité.** Chaque capability, surtout les sensibles ; chaque route
+  réseau, qui doit servir l’objet annoncé du widget ; les écritures dans le
+  presse-papiers, le stockage et les événements de jeu. Voir
+  [services et permissions](services.md).
+- **La fiche.** Un texte exact et brut dans chaque langue, une URL de
+  sources canonique, un aperçu qui montre le widget.
+- **La licence.** `LICENSE` correspond à `spdxLicense`, et chaque
+  ressource, police ou code tiers embarqué garde sa mention.
+
+À la fusion, la révision exacte est admise de nouveau, et un reçu lie le
+paquet admis au commit relu. Accepter une soumission ne signe et ne publie
+rien.
+
+## Le catalogue
+
+Les mainteneurs préparent le catalogue suivant à partir des révisions
+admises et le signent hors de la CI avec la clé du catalogue, dont la moitié
+publique est dans [`keys/`](../../../keys/). Le catalogue :
+
+- liste chaque version avec le SHA-256 et la taille de son paquet ; une
+  version publiée ne change jamais, et un changement est une nouvelle
+  version ;
+- porte un numéro de séquence strictement croissant et expire au bout de
+  90 jours au plus : OverCrow refuse une séquence plus ancienne et un
+  catalogue expiré ;
+- marque `built-in` les widgets de référence PlayerVox (IDs
+  `com.playervox.*` uniquement) : ils sont installés sur un nouveau profil
+  avec leurs permissions déclarées accordées, sauf pour une mise à jour qui
+  en demande davantage.
+
+OverCrow vérifie la signature, l’empreinte du paquet, son registre et sa
+vue compilée avant l’installation, puis à chaque démarrage du widget. Voir
+[le paquet](package.md#comment-overcrow-vérifie-un-paquet).
+
+## Mises à jour
+
+Une nouvelle version de votre widget est une nouvelle soumission, avec une
+`version` plus élevée : une version publiée n’est jamais remplacée. Une
+mise à jour dont le manifeste demande plus que la version installée (une
+règle réseau, un événement de jeu, une capability, le stockage ou le
+presse-papiers) exige l’accord de l’utilisateur, dans le Centre de
+contrôle, avant de s’exécuter.
+
+## Statuts des versions
+
+Chaque version listée a un statut :
+
+| Statut | Signification |
+| --- | --- |
+| `verified` | Installable. |
+| `security-suspended` | Soupçonnée de compromission : ni installée ni proposée en mise à jour, et une copie installée est arrêtée. Réversible dans un catalogue ultérieur. |
+| `revoked` | Définitif : plus jamais installée, et une copie installée est arrêtée. |
+
+Omettre une version dans un catalogue ne change jamais son statut. La
+signature d’un catalogue ne contourne jamais la validation du paquet, le
+consentement de l’utilisateur ni le sandbox.

package/dist/content/docs/fr/reference.md

@@ -0,0 +1,59 @@
+# Référence
+
+La référence des widgets PlayerVox OverCrow liste chaque élément, chaque
+propriété de style, chaque service et chaque fonction du SDK de l’API
+widget v1. Cette page indique où trouver chaque réponse. Les pages de la
+rubrique « Écrire un widget » expliquent comment les parties fonctionnent
+ensemble ; celles qui suivent sont à garder ouvertes pendant que vous
+écrivez.
+
+| Question | Page |
+| --- | --- |
+| Que contient `manifest.json` ? | [Le manifeste](manifest.md) |
+| Quels éléments, attributs et événements une vue peut-elle utiliser ? | [Éléments et attributs](elements.md) |
+| Quelles propriétés de style et quelles valeurs sont acceptées ? | [Propriétés de style et tokens](style-properties.md) |
+| Quels tokens du design system et quelles icônes existent ? | [Tokens du design system](style-properties.md#tokens-du-design-system), [icônes](style-properties.md#icônes) |
+| Quelles fonctions `@overcrow/sdk` exporte-t-il ? | [Référence du SDK](sdk.md) |
+| Comment formater les heures, les dates et les nombres ? | [Heure, dates et nombres](sdk.md#heure-dates-et-nombres) |
+| Qu’autorise chaque permission et chaque capability ? | [Services et permissions](services.md) |
+| Quels sont les paramètres et le résultat d’un service ? | [Référence des services](service-reference.md), [formes de résultat](result-shapes.md) |
+| Que signifie un code d’erreur ? | [Erreurs](services.md#erreurs) |
+| Quels champs un intent d’écriture prend-il ? | [Les intents](forms.md#les-intents) |
+| Quelles sont les limites (tailles, nombres, budgets) ? | [Limites](limits.md) |
+| Que fait chaque commande et chaque diagnostic de la CLI ? | [L’outil en ligne de commande](cli.md) |
+| Comment écrire un scénario de test ? | [Tester un widget](testing.md#scénarios) |
+| Que contient un `.ocpkg` ? | [Le paquet](package.md) |
+
+## Comment la référence reste exacte
+
+- Les tableaux des éléments, des attributs, des propriétés de style, des
+  tokens, des services, des formes de résultat et des limites sont
+  **générés à partir du schéma des widgets**, les mêmes tables qu’OverCrow
+  et l’outil en ligne de commande compilent dans leurs validateurs. Une
+  vérification échoue dès qu’une page diffère du schéma, en anglais ou en
+  français.
+- Les **types du SDK** sont générés à partir du même schéma : un élément,
+  une icône, une capability ou un paramètre de service erroné est donc une
+  erreur TypeScript dans votre logique.
+- La **référence du SDK** est vérifiée par les tests du SDK : chaque export
+  de `@overcrow/sdk` y figure.
+- Chaque **exemple de code** de ces pages est un extrait d’un projet que
+  l’outil en ligne de commande vérifie, empaquette et admet à chaque
+  changement : un template, un widget de référence ou l’un des deux
+  exemples.
+
+## Versions
+
+Ces pages décrivent l’API widget v1 (`"apiVersion": 1` dans le manifeste)
+et `@overcrow/sdk` 1.0.
+
+## Spécifications pour les implémenteurs
+
+Trois spécifications, dans le dépôt public, s’adressent à ceux qui
+implémentent un hôte ou un autre outil plutôt qu’un widget : la
+[référence complète du schéma, générée](../../widget-schema-v1.md), qui
+couvre aussi le protocole entre OverCrow et le processus du widget ainsi que
+les données du catalogue ; le
+[protocole du canal de développement](../../dev-channel.md) ; et le
+[format de l’archive et du catalogue](../../widget-package-v1.md). L’auteur
+d’un widget n’en a pas besoin.