@overcrow/mcp 0.1.0 → 0.1.1

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

@@ -7,11 +7,11 @@ validateurs que ceux qu’OverCrow exécute quand il installe et démarre un
 widget : un paquet qu’il accepte est un paquet qu’OverCrow lit.
 
 ```sh
-overcrow-widget init my-widget --template counter
+overcrow-widget init my-widget --template counter --id nova.my-widget
 cd my-widget
 overcrow-widget check
 overcrow-widget package
-overcrow-widget inspect dist/com.example.my-widget-0.1.0.ocpkg
+overcrow-widget inspect dist/nova.my-widget-0.1.0.ocpkg
 overcrow-widget doctor
 overcrow-widget dev
 overcrow-widget test
@@ -26,10 +26,14 @@ overcrow-widget test
 | [`dev`](#dev) | Exécute le widget dans OverCrow et le recharge à chaque enregistrement. |
 | [`test`](#test) | Joue les scénarios de test du projet et compare leurs images. |
 | [`doctor`](#doctor) | Indique ce que votre installation a et ce qui lui manque. |
-| [`admit`](#admit) | Exécute l’admission de la marketplace sur votre soumission. |
+| [`admit`](#admit) | Exécute l’admission de l’espace créateurs sur vos sources, un dossier ou un ZIP. |
+| [`diff`](#diff) | Compare deux versions des sources d’un widget. |
+| [`submit`](#submit) | Envoie une version à l’espace créateurs avec une clé de publication, et suit ses contrôles. |
+| [`status`](#status) | Montre les versions d’un widget, leurs contrôles et leur revue. |
 
 Chaque commande prend le dossier du projet en argument ; sans argument,
-elle utilise le dossier courant.
+elle utilise le dossier courant. La [sortie lisible par un programme](#sortie-lisible-par-un-programme)
+et les [codes de sortie](#codes-de-sortie) sont stables pour vos scripts.
 
 ## Installation
 
@@ -97,15 +101,15 @@ dans `node_modules` dont la version diffère de celle que l’outil embarque.
 | `logic.ts` ou `logic.js` | [La logique](logic.md), un seul module ; regroupée avec le SDK dans `logic.js`. | regroupé |
 | `locales/en.json`, `locales/fr.json` | [Les messages](logic.md#messages) ; les deux fichiers ou aucun, avec les mêmes clés. | oui |
 | `LICENSE` | Le texte de la licence du paquet. Les templates partent de la licence MIT ; choisissez la vôtre. | oui |
-| `assets/` | Images PNG, JPEG ou WebP ; facultatif. | oui |
+| `assets/` | Images PNG, JPEG ou WebP ; facultatif. Les fichiers cachés (`.DS_Store`) et ce que les outils créateurs n’envoient jamais (`dist/`…) sont ignorés, comme dans les [archives de sources](#archives-de-sources). | oui |
 | `package.json`, `tsconfig.json` | Outillage uniquement : TypeScript et les types du SDK. | non |
-| `listing.json` | Le texte de marketplace d’une [soumission](publishing.md#la-fiche) ; lu par `admit`. | non |
+| `listing.json` | Le texte de marketplace d’une [soumission](publishing.md#la-fiche) ; lu par `admit`. Dans l’espace créateurs, où la fiche se modifie, une simple proposition d’import. | non |
 | `tests/` | Les [scénarios](testing.md#scénarios) (`tests/<name>.scenario.json`), leurs images de référence (`tests/reference/`) et vos tests unitaires. `tests/output/` contient les images des exécutions en échec. | non |
 
 ## init
 
 ```sh
-overcrow-widget init my-widget --template list --id com.example.my-widget --name "My widget"
+overcrow-widget init my-widget --template list --id nova.my-widget --name "My widget"
 ```
 
 Écrit un nouveau projet dans le dossier, qui ne doit pas exister ou doit
@@ -118,8 +122,12 @@ overcrow-widget init my-widget --template list --id com.example.my-widget --name
 | `list` | Une liste de tâches à clés : `for`, gestionnaires avec arguments, `t()` avec paramètres. |
 | `chart` | Un graphique en direct, mis à jour par un minuteur. |
 
-Par défaut, l’ID vaut `com.example.<dir>`. Passez `--id` avec un ID en DNS
-inversé, sous un domaine que vous contrôlez (`com.playervox.*` est réservé).
+Passez `--id` avec l’ID de votre widget : `<pseudo>.<nom>`, votre pseudo
+d’éditeur dans l’espace créateurs d’OverCrow et un nom (`nova.lol-timers`),
+ou un domaine que vous avez vérifié, inversé, et un nom
+(`gg.nova.lol-timers`) ; voir [le manifeste](manifest.md#identité-et-version).
+Sans `--id`, l’ID vaut `yourhandle.<dir>` : remplacez `yourhandle` avant
+d’envoyer le widget, car `admit` le refuse. `com.playervox.*` est réservé.
 Chaque template est livré avec un scénario de test,
 `tests/example.scenario.json` ; `counter`, `list` et `chart` fournissent
 aussi ses images de référence.
@@ -165,6 +173,10 @@ Exécute `check`, puis écrit le paquet dans `dist/<id>-<version>.ocpkg`, ou
 à l’emplacement donné par `--out`. La commande affiche le chemin, la taille
 et le SHA-256 de l’archive.
 
+Avec `--source-map FILE`, elle écrit aussi dans ce fichier
+[la carte du code](#la-carte-du-code) de `logic.js`. La carte n’entre
+jamais dans le paquet : le paquet est le même avec ou sans elle.
+
 L’empaquetage est déterministe : les mêmes sources et la même version de
 l’outil donnent les mêmes octets à chaque exécution et sur tous les
 systèmes. Le contenu du paquet est décrit dans [le paquet](package.md).
@@ -172,7 +184,7 @@ systèmes. Le contenu du paquet est décrit dans [le paquet](package.md).
 ## inspect
 
 ```sh
-overcrow-widget inspect dist/com.example.my-widget-0.1.0.ocpkg
+overcrow-widget inspect dist/nova.my-widget-0.1.0.ocpkg
 ```
 
 Valide un paquet comme le fait OverCrow, puis le montre tel qu’un relecteur
@@ -280,39 +292,381 @@ Options : `--format json`, `--deny-warnings`.
 ## admit
 
 ```sh
-overcrow-widget admit
-overcrow-widget admit --package dist/com.example.my-widget-0.1.0.ocpkg
+overcrow-widget admit --publisher nova
+overcrow-widget admit lol-timers.zip --publisher nova --previous lol-timers-1.0.0.ocpkg
+overcrow-widget admit --publisher nova --package dist/nova.my-widget-0.1.0.ocpkg
 ```
 
-Exécute l’admission statique par laquelle passe une soumission à la
-marketplace, exactement comme la marketplace l’exécute. La commande
-n’exécute jamais votre code ni `tsc` :
+Exécute l’admission statique que l’espace créateurs fait passer à chaque
+version que vous envoyez. Les sources sont le dossier du projet ou un ZIP
+de ce dossier, lus comme l’espace créateurs les reçoit
+([archives de sources](#archives-de-sources)). La commande n’exécute
+jamais votre code ni `tsc` :
 
-1. le dossier est construit comme `package` le construit ;
+1. les sources sont construites comme `package` les construit ;
 2. avec `--package`, la vue compilée de cette archive doit être, à l’octet
    près, ce que donne la compilation de `view.ocml` ;
-3. l’ID n’est pas réservé, `listing.json` est valide, son aperçu est un PNG
-   empaqueté d’au plus 256 Kio ;
+3. l’ID appartient à l’éditeur donné par `--publisher` (ses ID
+   `<pseudo>.<nom>` et, avec `--domain`, les ID sous un domaine qu’il a
+   vérifié) ; sans `--publisher`, l’ID n’est ni réservé, ni un ID
+   d’exemple (`nova.*`, `yourhandle.*`, `gg.nova.*`, `com.example.*`…), ni
+   sous un pseudo que personne ne peut prendre (`admin.*`, `com.*`).
+   `listing.json` est valide, son aperçu est un PNG empaqueté d’au plus
+   256 Kio ;
 4. les pouvoirs que le widget demande sont listés pour le relecteur :
    capabilities (les sensibles sont signalées), routes réseau avec leur
    limite de réponse, écritures dans le presse-papiers, stockage et
-   événements de jeu.
+   événements de jeu ;
+5. avec `--previous`, la dernière version approuvée (son `manifest.json`,
+   son paquet, son dossier ou son ZIP) : l’ID doit être le même et la
+   version supérieure, et le rapport liste les
+   [clés de permission](#clés-de-permission) ajoutées, élargies et
+   retirées, ainsi que la revue dont la version a besoin.
 
 | Code | Sévérité | Signification |
 | --- | --- | --- |
-| `admission.reserved_id` | erreur | Un ID `com.playervox.*`, réservé à PlayerVox. |
-| `admission.listing_missing`, `admission.listing` | erreur | Pas de `listing.json`, ou un fichier qui enfreint les règles de la fiche. |
-| `admission.preview` | erreur | `preview` ne désigne pas un PNG empaqueté dans les limites. |
-| `admission.license` | erreur | Un widget PlayerVox dont la licence n’est pas MIT. |
+| `admission.reserved_id` | erreur | Un ID `com.playervox.*`, réservé à PlayerVox ; sans `--publisher`, aussi un ID sous un pseudo réservé (`playervox.*`, `admin.*`…). |
+| `admission.placeholder_id` | erreur | Un ID d’exemple, sans `--publisher`. |
+| `admission.id_not_owned` | erreur | L’ID n’appartient pas à l’éditeur, ou, sans `--publisher`, ne peut appartenir à personne. |
+| `admission.listing_missing`, `admission.listing` | erreur | Pas de `listing.json`, ou un fichier qui enfreint les règles de la fiche (un avertissement avec `--listing optional`). |
+| `admission.preview` | erreur | `preview` ne désigne pas un PNG empaqueté dans les limites (un avertissement avec `--listing optional`). |
+| `admission.license` | erreur | Un widget PlayerVox dont la licence n’est pas MIT (un avertissement avec `--listing optional`). |
 | `admission.view_not_reproducible` | erreur | La vue compilée soumise diffère de ce que donne la compilation de `view.ocml`. |
+| `admission.previous` | erreur | La version précédente ne peut pas être lue. |
+| `admission.previous_mismatch` | erreur | La version précédente est un autre widget. |
+| `admission.version_not_newer` | erreur | La version n’est pas supérieure à la précédente. |
 | `admission.package_rebuilt` | avertissement | L’archive soumise diffère de la reconstruction dans d’autres fichiers. |
 | `admission.not_rebuilt` | avertissement | Une archive a été admise sans ses sources. |
 
-Options : `--package FILE`, `--out DIR` (écrit le paquet admis, sa fiche et
-un rapport dans un dossier vide), `--format json`, `--deny-warnings`.
-`admit <file.ocpkg> --listing FILE` vérifie une archive sans ses sources.
-Codes de sortie : 0 admis, 1 refusé, 2 pour une erreur d’utilisation ou de
-fichier. Voir [publication et revue](publishing.md).
+Options : `--publisher HANDLE`, `--domain DOMAIN` (répétable), `--previous
+FILE`, `--package FILE`, `--source-map FILE` ([la carte du
+code](#la-carte-du-code), écrite quand les sources sont admises), `--out
+DIR` (écrit le paquet admis, sa fiche et un rapport dans un dossier vide),
+`--format json`, `--deny-warnings`. `admit <file.ocpkg> --listing FILE`
+vérifie une archive sans ses sources. Codes de sortie : 0 admis, 1 refusé,
+2 pour une erreur d’utilisation ou de fichier. Voir
+[publication et revue](publishing.md).
+
+`--listing required|optional` concerne les sources. `required`, par
+défaut, refuse des sources sans `listing.json` valide. `optional` est le
+mode de l’espace créateurs : la fiche s’y modifie, donc `listing.json` peut
+manquer, et un fichier qui pose problème est écarté (aucune fiche dans le
+rapport ni dans `--out`) avec des avertissements, au lieu de refuser les
+sources.
+
+### Clés de permission
+
+Chaque permission a une clé stable, la même dans l’espace créateurs :
+
+| Clé | Permission |
+| --- | --- |
+| `network:GET https://api.nova.gg/v1/timers` | Une route réseau : méthode, origine et chemin. |
+| `storage` | Le stockage. |
+| `clipboardWrite` | Les écritures dans le presse-papiers. |
+| `capability:<name>` | Une capability. |
+| `gameEvent:<name>` | Un événement de jeu. |
+
+Une clé est *ajoutée* quand la version précédente ne l’avait pas,
+*élargie* quand sa route reste mais que sa règle change (contraintes du
+chemin ou de la requête, limite de réponse), et *retirée* quand elle
+disparaît. Une clé ajoutée ou élargie demande une revue **complète** ;
+sinon la revue est **rapide**.
+
+## diff
+
+```sh
+overcrow-widget diff lol-timers-1.0.0.zip .
+overcrow-widget diff old/ new/ --format json
+```
+
+Montre ce qui a changé entre deux versions des sources d’un widget,
+chacune un dossier ou un ZIP, lues comme `admit` les lit : les fichiers que
+reçoit l’espace créateurs. Les fichiers sont triés par chemin ; chaque
+fichier ajouté, modifié ou supprimé est accompagné de ses changements au
+format unifié (trois lignes de contexte) et du nombre de lignes ajoutées et
+retirées. Un fichier qui n’est pas du texte UTF-8 est binaire : seul son
+SHA-256 est comparé. De même pour un texte de plus de 1 Mio ou de
+20 000 lignes, ou une fois 200 000 lignes comparées dans un même diff
+(`tooLarge`). Quand les deux versions ont un manifeste valide, les
+[clés de permission](#clés-de-permission) que la nouvelle version ajoute,
+élargit et retire sont listées, avec la revue dont elle a besoin.
+
+Option : `--format json`. Codes de sortie : 0 quand les deux versions ont
+été lues, qu’elles diffèrent ou non ; 1 quand l’une est refusée ; 2 pour
+une erreur d’utilisation ou de fichier (une version absente ou illisible).
+
+## submit
+
+```sh
+overcrow-widget submit --dry-run --submission submission.json
+overcrow-widget submit --submission submission.json
+```
+
+Envoie une version de votre widget à l’espace créateurs d’OverCrow, depuis
+un terminal, une CI ou le serveur MCP d’OverCrow, puis suit ses contrôles.
+La commande ne pose jamais de question : ce qui manque est signalé, avec un
+[code de sortie](#codes-de-sortie) stable. Elle prend le dossier du widget
+(le dossier courant sans argument) ou un ZIP de ce dossier.
+
+### La clé de publication
+
+- Créez-la dans l’espace créateurs (Éditeur, Clés de publication). Une clé
+  ne permet que de soumettre des versions d’un seul widget, pour 1 à
+  365 jours (90 par défaut), et n’est affichée qu’une fois.
+- `submit` et `status` la lisent dans la variable d’environnement
+  `OVERCROW_PUBLISH_KEY`, et seulement là : jamais dans un argument ni dans
+  un fichier du projet. Dans une CI, gardez-la comme secret.
+- L’outil ne l’affiche jamais : tout texte `ocw_pub_…` est masqué dans ses
+  sorties, ses erreurs et ses journaux. Quelle que soit la commande, il
+  retire la variable de l’environnement des programmes qu’il lance
+  (TypeScript, le runtime).
+- Une clé qui expire dans moins de 14 jours donne un avertissement. Une clé
+  expirée ou révoquée finit avec le code 2 : créez-en une autre et
+  remplacez le secret.
+- Chaque requête nomme le widget du `manifest.json` des sources (en-tête
+  `Overcrow-Widget`). Une clé qui couvre plusieurs widgets de son éditeur
+  (réservée à PlayerVox pour l’instant) envoie celui qui est nommé ;
+  `status` prend alors `--widget`.
+
+### Ce que fait la commande
+
+1. Elle vérifie la clé et lit ce dont l’espace créateurs a besoin pour ce
+   widget : la dernière version approuvée, la plus petite version acceptée
+   maintenant, les envois restants (20 sur 24 heures), la présence d’une
+   politique de confidentialité dans la fiche.
+2. Elle vérifie exactement ce qu’elle va envoyer. Le dossier est zippé tel
+   que l’espace créateurs le lit ([archives de sources](#archives-de-sources)),
+   relu, puis admis comme l’espace créateurs l’admet, `listing.json` étant
+   facultatif ; un ZIP donné à la place est envoyé tel quel, octet pour
+   octet. L’ID du manifeste doit être le widget de la clé, et la version
+   supérieure à la dernière approuvée. Chaque permission que la version
+   ajoute ou élargit (chaque permission, pour une première version) demande
+   une justification, par sa [clé](#clés-de-permission). Les textes
+   doivent suivre les règles de l’espace créateurs. Au moindre problème,
+   rien n’est envoyé (code 1).
+3. Elle envoie l’archive, puis suit les six contrôles de l’espace créateurs,
+   environ une minute : manifeste, numéro de version, analyse du code,
+   construction du paquet, permissions, taille et ressources.
+4. Elle se termine quand la version entre en revue (code 0), quand un
+   contrôle échoue (code 1 : chaque problème est montré sur la ligne de
+   votre fichier), ou quand la version a réussi ses contrôles mais attend
+   dans l’espace créateurs ce que seul l’espace créateurs reçoit (code 3) :
+   une politique de confidentialité si le widget utilise le réseau, une
+   fiche complète pour une première version, ou la place en revue d’un
+   nouvel éditeur. Le lien pour finir là-bas est affiché.
+
+### Une version que l’espace créateurs a déjà
+
+Avant toute autre vérification, `submit` cherche une version du même
+numéro dans l’espace créateurs. Si elle a les mêmes sources (octet pour
+octet, telles que `submit` les zippe) ou, une fois admise, le même paquet,
+rien n’est envoyé : la commande se termine sur l’état de cette version,
+avec `outcome` `already_known`.
+
+- Code 0 : elle est publiée, approuvée, en revue, ou attend votre réponse à
+  des modifications demandées.
+- Code 3 : elle attend dans l’espace créateurs (le lien pour finir est
+  affiché).
+- Code 1 : elle a échoué à ses contrôles, a été refusée, retirée ou
+  abandonnée : montez la version dans `manifest.json` pour envoyer d’autres
+  sources.
+- Une version encore en contrôle est suivie, comme après un envoi.
+
+Le même numéro avec un autre paquet est refusé avant l’envoi
+(`submit.version_known_differs`) : montez la version dans `manifest.json`.
+Une CI peut donc lancer `submit` à chaque push : une version déjà envoyée
+ne change rien.
+
+Ctrl+C pendant les contrôles arrête de les suivre ; ils continuent dans
+l’espace créateurs, et `overcrow-widget status --version 1.3.1 --wait` les
+suit de nouveau (code 4). Une commande coupée avant la fin (réseau, Ctrl+C)
+reprend le même envoi quand vous la relancez à l’identique ; des sources ou
+des textes modifiés font un nouvel envoi. Un envoi non terminé dans l’heure
+expire, et chaque envoi compte dans la limite quotidienne.
+
+| Option | Effet |
+| --- | --- |
+| `--submission FILE` | Les textes de la version ([ci-dessous](#le-fichier-de-textes)). |
+| `--release-notes-en TEXT`, `--release-notes-fr TEXT`, `--review-message TEXT` | Remplacent ceux du fichier. |
+| `--dry-run` | Étapes 1 et 2 seulement, sans rien envoyer : ce que l’espace créateurs exigera (justifications, politique de confidentialité, type de revue, version minimale, envois restants) et l’empreinte SHA-256 de l’archive. Pour une première version, l’espace créateurs vérifie aussi toute la fiche, qu’il est seul à connaître : un essai à blanc qui finit avec 0 peut encore finir avec 3. |
+| `--expect-sha256 HEX` | N’envoie qu’une archive de cette empreinte, l’`archive.sha256` d’un `--dry-run` : ce qui part est ce qui a été vérifié. |
+| `--no-wait` | S’arrête après l’envoi (code 4). |
+| `--format json` | Un seul objet JSON ([sortie lisible par un programme](#sortie-lisible-par-un-programme)). |
+| `--verbose` | Une ligne par requête sur la sortie d’erreur : méthode, adresse sans sa requête, statut et durée ; jamais un en-tête, une clé ou un corps. |
+
+### Le fichier de textes
+
+<!-- source: docs/content/examples/weather/submission.json -->
+```json
+{
+  "releaseNotes": {
+    "en": "First version: the forecast of your city, in metric or imperial units.",
+    "fr": "Première version : les prévisions de votre ville, en unités métriques ou impériales."
+  },
+  "justifications": [
+    {
+      "permission": "network:GET https://api.example.com/v1/forecast/{city}",
+      "text": "Reads the forecast of the city the player chose, every 30 minutes at most."
+    },
+    {
+      "permission": "storage",
+      "text": "Keeps the chosen city and units between two games."
+    }
+  ],
+  "reviewMessage": "The forecast API needs no account and receives only the city."
+}
+```
+
+| Clé | Valeur |
+| --- | --- |
+| `releaseNotes` | Les notes publiques de la version, montrées aux joueurs : `en` (exigé dès qu’il y a des notes) et `fr`, 500 caractères chacune, texte simple, retours à la ligne admis. |
+| `justifications` | Pour le relecteur, un `{permission, text}` par permission nouvelle ou élargie, par sa [clé](#clés-de-permission) ; 500 caractères chacun. |
+| `reviewMessage` | Un message privé au relecteur, 2 000 caractères. |
+
+Chaque clé est facultative ; toute autre clé est refusée. Le serveur MCP
+d’OverCrow écrit ce fichier.
+
+### Dans une CI
+
+Un workflow GitHub Actions qui installe l’outil ([installation](#installation))
+et soumet le widget d’exemple `nova.weather` à chaque étiquette de version,
+avec la clé dans les secrets du dépôt :
+
+<!-- source: docs/content/examples/weather/.github/workflows/submit.yml -->
+```yaml
+# Sends the widget to the OverCrow creator space when a version tag is
+# pushed. The publish key is a secret of the repository, and the OverCrow
+# release whose creator tools to use is a variable of the repository.
+name: Submit to OverCrow
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  submit:
+    runs-on: ubuntu-24.04
+    env:
+      OVERCROW_VERSION: ${{ vars.OVERCROW_VERSION }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install overcrow-widget
+        run: |
+          tools="overcrow-creator-tools-$OVERCROW_VERSION-linux-x86_64"
+          curl --fail --location --silent --show-error --remote-name \
+            "https://github.com/Valhallab/playervox-overcrow-releases/releases/download/v$OVERCROW_VERSION/$tools.zip"
+          unzip -q "$tools.zip"
+          (cd "$tools" && sha256sum --check --quiet SHA256SUMS)
+          install -D -m 755 "$tools"/overcrow-widget-*-linux-x86_64 "$HOME/.local/bin/overcrow-widget"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - name: Submit to OverCrow
+        run: overcrow-widget submit --submission submission.json
+        env:
+          OVERCROW_PUBLISH_KEY: ${{ secrets.OVERCROW_PUBLISH_KEY }}
+```
+
+Le job échoue pour tout code autre que 0. `OVERCROW_API_URL` dirige
+`submit` et `status` vers une autre API, pour des essais seulement :
+`https://`, ou `http://` vers `127.0.0.1`, `localhost` ou `[::1]`, avec un
+avertissement à chaque fois. Ne la posez jamais dans une vraie CI ; le
+serveur MCP d’OverCrow ne la pose jamais.
+
+## status
+
+```sh
+overcrow-widget status
+overcrow-widget status --version 1.3.1 --wait
+```
+
+Montre les versions du widget de la clé, avec leur état et leur type de
+revue. Avec `--version`, une seule version, par son numéro (la plus récente
+de ce numéro) ou son ID : ses six contrôles et leurs problèmes, ce qui la
+retient avant la revue, les remarques du relecteur et le délai de revue.
+`--wait` suit une version encore en contrôle. `--widget ID` nomme le widget,
+pour une clé qui en couvre plusieurs (code 2 sans lui, avec les widgets que
+la clé couvre). Options : `--widget ID`, `--version VERSION|ID`, `--wait`,
+`--format json`, `--verbose`. Code de sortie : 0
+quand la lecture a réussi, 2 sur une erreur ; avec `--wait`, les codes de
+`submit`.
+
+| État | Signification |
+| --- | --- |
+| `checking` | Les contrôles tournent. |
+| `checks_failed` | Un contrôle a échoué : rien n’est parvenu aux relecteurs. |
+| `ready` | Les contrôles ont réussi ; la version attend dans l’espace créateurs. |
+| `in_review` | Une personne la relit. |
+| `changes_requested`, `approved`, `rejected` | La décision de la revue. |
+| `published` | Dans le catalogue. |
+| `superseded`, `discarded` | Remplacée par un envoi plus récent, ou abandonnée. |
+| `withdrawn`, `suspended` | Hors du catalogue. |
+
+## Archives de sources
+
+`admit` et `diff` acceptent le dossier du widget ou un ZIP de ce dossier
+(son nom finit par `.zip`), tel que l’espace créateurs le reçoit. Le ZIP
+peut contenir les fichiers directement, ou un seul dossier qui les contient
+tous, comme le font Windows et macOS. Il peut porter un court commentaire
+d’archive (1 024 octets au plus), comme l’écrivent le « Download ZIP » de
+GitHub et `git archive` ; ce commentaire n’est jamais lu.
+
+Laissés de côté dans les deux cas, et jamais envoyés par les outils
+créateurs : les fichiers et dossiers cachés (`.env`, `.git/`,
+`assets/.DS_Store`…), `node_modules/`, `dist/`, `tests/output/`,
+`__MACOSX/`, les paquets construits, les fichiers de clés et les fichiers
+système, et, dans un dossier, les liens et les noms qui ne sont pas en
+ASCII portable. Dans un ZIP, ils comptent tout de même dans les limites
+ci-dessous et sont vérifiés comme le reste. Un nom qui contient un
+caractère interdit par Windows (`\ : * ? " < > |`) est refusé, dans un
+dossier aussi.
+
+| Limite | Valeur |
+| --- | --- |
+| Archive | 32 Mio |
+| Décompressé | 64 Mio |
+| Fichiers | 2 000 |
+
+Tout est vérifié avant d’écrire le moindre octet : une archive refusée
+n’écrit rien, et une archive admise n’est écrite que dans un dossier de
+travail privé, supprimé à la fin.
+
+| Code | L’archive contient |
+| --- | --- |
+| `sources.archive_size` | Plus de 32 Mio. |
+| `sources.too_large`, `sources.too_many_files` | Plus de 64 Mio ou de 2 000 fichiers une fois décompressée. |
+| `sources.unsafe_name` | Un nom qui pourrait sortir du dossier du widget (`../`, `/` en tête), ou qu’un système ne peut pas utiliser : un caractère interdit par Windows (`\`, `:`, `*`, `?`, `"`, `<`, `>`, \|), autre chose que de l’ASCII imprimable, un point ou une espace final, `CON`, `NUL`, `COM1`… Le message nomme le caractère et le fichier. |
+| `sources.backslash` | Des dossiers séparés par `\`, comme les écrit `Compress-Archive` de Windows PowerShell 5.1. Envoyez le dossier du widget lui-même dans l’espace créateurs, ou utilisez [`submit`](#submit), qui fait un ZIP correct. |
+| `sources.duplicate_name` | Deux noms qui ne diffèrent que par la casse, ou un fichier qui est aussi un dossier. |
+| `sources.link`, `sources.special_file` | Un lien, ou un périphérique, une FIFO ou un socket. |
+| `sources.bomb` | Une entrée qui se décompresse bien au-delà de sa taille compressée, ou de sa taille déclarée. |
+| `sources.read` | Le fichier ne peut pas être lu (code de sortie 2). |
+| `sources.encrypted` | Une entrée chiffrée. |
+| `sources.zip64` | Du ZIP64, dont des sources n’ont jamais besoin. |
+| `sources.archive` | Tout autre élément qu’un ZIP ne doit pas contenir : un commentaire de plus de 1 024 octets ou qui contient un enregistrement de fin, des octets avant, entre ou après les entrées ou après les données compressées d’une entrée, un autre nom dans un champ extra, des tailles ou des sommes de contrôle qui ne concordent pas. |
+
+## La carte du code
+
+`--source-map FILE` écrit une carte qui relie chaque position du
+`logic.js` livré, regroupé et minifié, au fichier, à la ligne et à la
+colonne de vos sources : une [Source Map v3](https://tc39.es/ecma426/).
+L’espace créateurs la garde privée et s’en sert pour vous montrer les
+erreurs de votre widget dans votre propre code.
+
+- `sources` : `logic.ts` (ou `logic.js`), les fichiers de `@overcrow/sdk`
+  (listés dans `ignoreList`) et `overcrow:view-table`, la table des
+  expressions générée depuis `view.ocml`, dont le texte est dans
+  `sourcesContent`.
+- `x_overcrow_functions` : les fonctions nommées des sources,
+  `{"source", "name", "start": [line, column], "end": [line, column]}`,
+  numérotées à partir de 0, colonnes en unités UTF-16 comme `mappings`. La
+  fonction d’une position est la plus intérieure qui l’entoure. Les
+  expressions de la table de vue s’appellent `view expression <n>`, `<n>`
+  étant leur rang dans `view.json`.
+
+Les mêmes sources donnent toujours la même carte. Elle ne fait jamais
+partie du paquet, et `logic.js` ne la désigne pas.
 
 ## Diagnostics
 
@@ -342,7 +696,9 @@ Le code a la forme `<domain>.<category>` :
 | `typecheck` | TypeScript | `tsc` (le message de TypeScript lui-même), `skipped`, `sdk_version`, `timeout` |
 | `package` | Le paquet relu | `archive_size`, `file_size` et les catégories du lecteur de paquets d’OverCrow |
 | `test` | Les scénarios | `scenario`, `scenario_name`, `too_many_scenarios` |
+| `sources` | Une archive de sources | voir [archives de sources](#archives-de-sources) |
 | `init`, `doctor`, `admission` | Ces commandes | listés ci-dessus |
+| `submit` | Ce que `submit` vérifie avant l’envoi | `widget_not_submittable`, `agreement_required`, `limit_reached`, `version_too_low`, `justification_missing`, `archive_too_large`, `archive_mismatch`, `release_notes`, `justification`, `review_message` |
 
 - Les lignes et les colonnes commencent à 1 ; une colonne compte des
   caractères, pas des octets.
@@ -351,17 +707,96 @@ Le code a la forme `<domain>.<category>` :
   la sortie standard :
   `{"severity","code","file","line","column","message","help"}`, avec
   `null` pour ce qui est inconnu. `package --format json` se termine par un
-  objet `{"package","bytes","sha256","logicBytes"}`.
+  objet `{"package","bytes","sha256","logicBytes","sourceMap"}` ; `admit` et
+  `diff` affichent un seul rapport ([sortie lisible par un
+  programme](#sortie-lisible-par-un-programme)).
 - Les textes qui viennent d’un widget (ses journaux, ses noms) sont affichés
   avec les caractères de contrôle du terminal neutralisés.
 
 Dans vos scripts, appuyez-vous sur les codes : les messages et les textes
 d’aide peuvent être reformulés.
 
+## Sortie lisible par un programme
+
+Avec `--format json`, `admit`, `diff`, `submit` et `status` affichent un
+seul objet JSON sur une ligne. Des champs peuvent seulement s’ajouter ; tout autre changement
+est annoncé par un nouveau `formatVersion`.
+
+`admit` :
+
+| Champ | Valeur |
+| --- | --- |
+| `formatVersion` | `1`. |
+| `admitted` | Si les sources sont admises. |
+| `publisher` | Le pseudo de `--publisher`, ou `third-party`. |
+| `id`, `version`, `reservedId` | Le widget ; `null` quand les sources ont été refusées avant la construction. |
+| `package` | `bytes`, `sha256` et les `bytes` et `sha256` de chaque fichier. |
+| `reproducible` | `viewJson` et `archive`, comparés avec `--package`, sinon `null`. |
+| `listing` | `bytes`, `sha256`, `spdxLicense` et `preview` de `listing.json`. |
+| `sources` | `kind` (`folder` ou `archive`), `files`, `bytes`, `ignored` (`path`, `reason`) et, pour un ZIP, `sha256` et `prefix` (le dossier englobant). |
+| `review` | Les pouvoirs à relire, un objet par élément (`kind`, puis ses champs). |
+| `permissions` | `keys` ; avec `--previous`, aussi `previous` (`id`, `version`), `added`, `changed`, `removed` et `reviewType` (`full` ou `quick`), sinon `null`. |
+| `listingPolicy` | `required` ou `optional` (`--listing`). |
+| `diagnostics` | Les diagnostics, comme ci-dessus. |
+
+`diff` :
+
+| Champ | Valeur |
+| --- | --- |
+| `formatVersion` | `1`. |
+| `compared` | `false` quand une version est refusée ; seul `diagnostics` suit alors. |
+| `old`, `new` | `kind`, `files`, `bytes`, `sha256`, `prefix`, `ignored`, `id` et `version` de chaque version. |
+| `files` | Les fichiers modifiés, par chemin : `path`, `status` (`added`, `modified`, `removed`), `binary`, `tooLarge`, `oldSha256`, `newSha256`, `additions`, `deletions` et `hunks` (`oldStart`, `oldLines`, `newStart`, `newLines`, `lines`, chaque ligne commençant par ` `, `-`, `+` ou `\`). |
+| `totals` | `added`, `modified`, `removed`, `additions`, `deletions`. |
+| `permissions` | `added`, `changed`, `removed` et `reviewType`, ou `null` sans deux manifestes valides. |
+| `diagnostics` | Les diagnostics. |
+
+
+`submit` et `status` :
+
+| Champ | Valeur |
+| --- | --- |
+| `formatVersion`, `command` | `1` ; `submit` ou `status`. |
+| `outcome`, `exitCode` | La fin de la commande (ci-dessous) et son [code de sortie](#codes-de-sortie). |
+| `dryRun` | `submit` : si rien ne devait partir. |
+| `key` | `name`, `hint` (les quatre caractères après `ocw_pub_`), `expiresAt`, `expiresSoon`, `widgets` (les widgets que la clé couvre). |
+| `widget` | `id` ; `submit` : `publisher`, `status` ; `status` : `name`. |
+| `archive` | `submit` : `kind` (`folder`, zippé par l’outil, ou `archive`), `bytes`, `sha256`, `files`, `uncompressedBytes`, `ignored`. |
+| `local` | `submit` : `admitted`, `version`, `minimumVersion`, `previousVersion`, `permissions` (`keys`, `added`, `changed`, `removed`, `reviewType`), `diagnostics`. |
+| `requirements` | `submit` : `justifications` (`required`, `given`, `missing`, `unused`), `privacyPolicy` (`required`, `present`), `reviewType`, `submissions` (`limit`, `remaining`, `nextSubmissionAt`), `review` (`available`, `blockedBy`), `agreement` (`version`, `accepted`), `blockers` (`code`). |
+| `known` | `submit` : la version que l’espace créateurs a déjà (rien n’est parti) : `versionId`, `state`, `match` (`sources` ou `package`). |
+| `submission` | `submit` : `id`, `state`, `resumed`, `quota`. |
+| `version` | La version de l’espace créateurs, ses champs en camelCase : `id`, `version`, `state`, `reviewType`, `checks` (`key`, `status`, `diagnostics`), `reviewBlockers`, `completeInPortal` (`message`, `url`), `permissions`, `remarks`, `deadline`, `history`… |
+| `versions` | `status` sans `--version` : toutes les versions. |
+| `error` | `code`, `message` et, quand ils sont connus, `httpStatus`, `retryAfter`, `nextSubmissionAt`, `minimumVersion`, `expiredAt`, `fields` ; sinon `null`. |
+
+`outcome` vaut `ready_to_send` (`--dry-run`), `refused_locally`, `refused`
+(l’espace créateurs a refusé l’envoi), `complete_in_portal`,
+`already_known` (rien n’est parti, voir `known`), `error`, ou l’état de la
+version ; `status` sans `--wait` n’en a pas. Les codes
+d’erreur sont ceux de l’espace créateurs (`version_not_newer`,
+`submission_limit_reached`, `publish_key_expired`, `publish_key_revoked`,
+`widget_required`, `publish_key_widget_not_covered`…)
+ou ceux de l’outil : `publish_key_missing`, `invalid_publish_key`,
+`api_url_invalid`, `submission_file`, `sources`, `sources.read`, `network`,
+`timeout`, `server`, `response`, `redirect`, `upload_refused`,
+`build_failed`, `submission_state`, `not_found`, `internal`. Les problèmes
+trouvés avant l’envoi sont des diagnostics : `sources.*`,
+`project.missing_file` (ce n’est pas le dossier du widget), `admission.*`
+et `submit.*`
+(`widget_not_submittable`, `agreement_required`, `limit_reached`,
+`version_too_low`, `justification_missing`, `archive_too_large`,
+`archive_mismatch`, `version_known_differs`, `release_notes`,
+`justification`, `review_message`).
+
 ## Codes de sortie
 
 | Code | Signification |
 | --- | --- |
-| 0 | Succès. Les avertissements sont admis, sauf avec `--deny-warnings`. |
-| 1 | Des erreurs ont été trouvées ; `admit` a refusé la soumission ; un scénario de `test` a échoué ; l’overlay a mis fin à une session `dev`. |
-| 2 | Une erreur d’utilisation ou de fichier ; pas d’overlay pour `dev` ; pas de runtime pour `test`. |
+| 0 | Succès. Les avertissements sont admis, sauf avec `--deny-warnings`. `diff` a lu les deux versions, qu’elles diffèrent ou non. `submit` : la version est en revue (avec `--dry-run`, elle y entrerait), ou déjà au-delà (approuvée, publiée, retirée), ou l’espace créateurs l’avait déjà en revue, avec des modifications demandées, approuvée ou publiée. |
+| 1 | Des erreurs ont été trouvées ; `admit` a refusé les sources ; `diff` a refusé une version ; un scénario de `test` a échoué ; l’overlay a mis fin à une session `dev`. `submit` : quelque chose à corriger (une vérification avant l’envoi, un refus de l’espace créateurs, un contrôle échoué, une version que l’espace créateurs a déjà refusée, retirée ou abandonnée). |
+| 2 | Une erreur d’utilisation ou de fichier ; pas d’overlay pour `dev` ; pas de runtime pour `test`. `submit`, `status` : la clé (absente, invalide, expirée, révoquée), le réseau ou le serveur. |
+| 3 | `submit`, `status --wait` : la version a réussi ses contrôles et attend dans l’espace créateurs. |
+| 4 | `submit`, `status --wait` : la version est encore en contrôle (Ctrl+C, `--no-wait`, ou 15 minutes). |
+
+Ces significations ne changent pas d’une version de l’outil à l’autre.