L’outil en ligne de commande

overcrow-widget crée, vérifie et empaquette les widgets PlayerVox OverCrow, les exécute dans OverCrow pendant que vous les écrivez, et les teste. C’est un seul programme pour Linux et Windows. Il contient les mêmes 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.

overcrow-widget init my-widget --template counter --id nova.my-widget
cd my-widget
overcrow-widget check
overcrow-widget package
overcrow-widget inspect dist/nova.my-widget-0.1.0.ocpkg
overcrow-widget doctor
overcrow-widget dev
overcrow-widget test

Chaque commande prend le dossier du projet en argument ; sans argument, elle utilise le dossier courant. La sortie lisible par un programme et les codes de sortie sont stables pour vos scripts.

Installation

Chaque release de PlayerVox OverCrow contient les outils créateurs dans un ZIP par plateforme : l’outil avec sa licence et ses notices tierces, le runtime headless d’OverCrow qu’utilise test, un README.txt et un SHA256SUMS de tous les fichiers.

Décompressez-le, vérifiez les fichiers, renommez l’outil overcrow-widget (overcrow-widget.exe sous Windows), rendez-le exécutable sous Linux (chmod +x) et placez-le dans votre PATH. Il n’a besoin de rien d’autre pour vérifier et empaqueter un widget. overcrow-widget --version donne sa version et celle du SDK qu’il embarque.

unzip overcrow-creator-tools-VERSION-linux-x86_64.zip
cd overcrow-creator-tools-VERSION-linux-x86_64
sha256sum --check SHA256SUMS
install -m 755 overcrow-widget-*-linux-x86_64 ~/.local/bin/overcrow-widget

L’outil se compile aussi avec Rust depuis le dépôt public ; le dépôt épingle la toolchain nécessaire. Le programme est alors target/dist/overcrow-widget.

cargo build -p overcrow-widget-cli --profile dist --locked

Les types du SDK

check vérifie les types de votre logique avec le TypeScript du projet, si Node.js 22 ou plus récent et node_modules/typescript sont présents. Sinon, il signale par un avertissement que les types n’ont pas été vérifiés (typecheck.skipped) et continue. Le SDK lui-même est inclus dans l’outil : l’empaquetage ne dépend donc jamais de node_modules.

@overcrow/sdk est sur npm. Le package.json d’un projet créé par init nomme TypeScript et la version du SDK que l’outil embarque : lancez npm install dans le projet. Dans un autre projet, installez le SDK avec :

npm install --save-dev --save-exact @overcrow/sdk@1.0.0

Gardez la version que l’outil embarque (overcrow-widget --version). overcrow-widget doctor signale l’absence de TypeScript, ainsi qu’un SDK dans node_modules dont la version diffère de celle que l’outil embarque.

Fichiers d’un projet

init

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 être vide : init n’écrase jamais un fichier.

Passez --id avec l’ID de votre widget : <pseudo>.<nom>, votre pseudo d’éditeur dans l’espace créateurs de PlayerVox 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. 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.

check

overcrow-widget check
overcrow-widget check --deny-warnings --format json

Exécute toutes les vérifications, dans cet ordre, et n’écrit rien :

1. Fichiers du projet : les fichiers requis sont présents et respectent leurs limites de taille, il y a un seul module de logique, et les deux fichiers de langue ou aucun.
2. Manifeste : le validateur de manifeste de PlayerVox OverCrow lui-même.
3. Vue : view.ocml est compilé et le résultat validé ; les images statiques doivent exister dans assets/.
4. Style : style.ocss est analysé avec l’analyseur syntaxique de PlayerVox OverCrow.
5. Fichiers de langue : des objets de chaînes aux clés valides, avec les mêmes clés dans les deux fichiers. Un t("key") de la vue dont la clé n’a pas de message donne un avertissement.
6. Logique : son analyse statique, et les exports que la vue appelle.
7. Types : le tsc --noEmit -p tsconfig.json du projet.
8. Paquet : logic.js est construit, puis le paquet est écrit en mémoire et relu exactement comme PlayerVox OverCrow le lira.

Options : --no-typecheck, --deny-warnings (un avertissement fait échouer la commande), --format json.

package

overcrow-widget package
overcrow-widget package --out build/my-widget.ocpkg

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 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.

inspect

overcrow-widget inspect dist/nova.my-widget-0.1.0.ocpkg

Valide un paquet comme le fait PlayerVox OverCrow, puis le montre tel qu’un relecteur le voit : l’ID, la version et les noms ; la taille et le SHA-256 de l’archive ; la version du SDK que contient son logic.js ; chaque permission en toutes lettres (routes réseau avec les contraintes de leurs paramètres et la limite de réponse déclarée, stockage, presse-papiers, événements de jeu) ; chaque capability avec son résumé, en précisant si elle est sensible ou demande un compte ; le nombre de lignes du menu ; et chaque fichier avec sa taille et son SHA-256. Quand OverCrow refuserait le paquet, la commande le signale à la place, avec la raison.

dev

overcrow-widget dev

Exécute le widget dans l’overlay PlayerVox OverCrow qui tourne sur votre machine, pendant que vous le modifiez :

1. la commande se connecte à l’overlay, qui doit avoir été lancé avec les installations de développement autorisées ;
2. elle construit le paquet comme le fait package et l’envoie à l’overlay, qui le valide entièrement et l’affiche avec la mention Unverified · development package, les permissions de son manifeste étant accordées pour la session seulement ;
3. elle surveille les fichiers du projet et, 200 ms après la dernière modification, reconstruit et recharge le widget. Une construction en erreur n’est pas envoyée : le widget continue de s’exécuter avec sa dernière construction valide ;
4. elle affiche ce que l’overlay rapporte : les états du widget (starting, running, restarting avec l’échec, failed…) et les sorties log.* de sa logique ;
5. sur Ctrl+C, elle retire le widget de l’overlay.

Options : --no-typecheck, --format json (un objet JSON par ligne). Codes de sortie : 0 après Ctrl+C, 1 quand l’overlay met fin à la session, 2 quand aucun overlay n’est joignable. Le canal de développement explique comment lancer PlayerVox OverCrow pour cela, et ce que signifient chaque état et chaque refus.

test

overcrow-widget test
overcrow-widget test --scenario example
overcrow-widget test --update

Joue les scénarios de tests/ dans le runtime headless de PlayerVox OverCrow et compare les images qu’il rend avec les références :

1. la commande construit le paquet comme le fait package ;
2. elle lit chaque tests/<name>.scenario.json et le vérifie par rapport au manifeste avant toute exécution ; une erreur dans un scénario donne un diagnostic test.scenario dans son fichier ;
3. elle exécute chaque scénario dans le runtime headless que l’outil épingle, ou celui donné par --runtime, et affiche la version et le SHA-256 de ce runtime. La première fois, elle télécharge le runtime épinglé ;
4. elle compare chaque image capturée avec tests/reference/<name>/<image>.png. Une différence, un changement de taille ou une référence manquante fait échouer le scénario et écrit tests/output/<name>/<image>.actual.png et, pour une différence, <image>.diff.png.

Options : --runtime <path> (un autre programme overcrow-widget-headless), --offline (ne jamais télécharger le runtime), --scenario <name> (ce scénario seulement), --update (enregistre les images capturées comme références : examinez-les avant de les commiter), --format json, --no-typecheck.

Codes de sortie : 0 quand tous les scénarios ont réussi, 1 quand l’un d’eux a échoué, 2 quand aucun runtime ne peut s’exécuter. Les scénarios sont décrits dans tester un widget.

doctor

overcrow-widget doctor

Options : --format json, --deny-warnings.

admit

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 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). La commande n’exécute jamais votre code ni tsc :

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 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 ;
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 ajoutées, élargies et retirées, ainsi que la revue dont la version a besoin.

Options : --publisher HANDLE, --domain DOMAIN (répétable), --previous FILE, --package FILE, --source-map FILE (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 vérifications et catalogue.

--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 :

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

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

overcrow-widget submit --dry-run --submission submission.json
overcrow-widget submit --submission submission.json

Envoie une version de votre widget à l’espace créateurs de PlayerVox OverCrow, depuis un terminal ou une CI, puis suit ses contrôles. La commande ne pose jamais de question : ce qui manque est signalé, avec un code 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 un an au plus (90 jours 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), 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é. 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.

Le fichier de textes

{
  "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."
}

Chaque clé est facultative ; toute autre clé est refusée. Le serveur MCP de PlayerVox OverCrow écrit ce fichier.

Dans une CI

Un workflow GitHub Actions qui installe l’outil (installation) et soumet le widget d’exemple nova.weather à chaque étiquette de version, avec la clé dans les secrets du dépôt :

# Sends the widget to the PlayerVox 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 PlayerVox 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 PlayerVox 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 de PlayerVox OverCrow ne la pose jamais.

status

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.

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.

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.

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. 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

Chaque problème est un diagnostic, avec un code stable, une position et, quand il y en a une, une suggestion :

error[view.unknown_attribute]: `clas` is not an attribute of <text>
  --> view.ocml:4:9
   |
 4 |   <text clas="value">{state.count}</text>
   |         ^
   = help: did you mean `class`?
check: 1 error(s), 0 warning(s)

Le code a la forme <domain>.<category> :

• Les lignes et les colonnes commencent à 1 ; une colonne compte des caractères, pas des octets.
• Un nom inconnu est accompagné du nom existant le plus proche.
• Avec --format json, chaque diagnostic est un objet JSON sur une ligne de 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","sourceMap"} ; admit et diff affichent un seul rapport (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 :

diff :

submit et status :

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, publish_key_owner_suspended, 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

Ces significations ne changent pas d’une version de l’outil à l’autre.