quest'n'click 4.5.0 · r1

Construite pour quest'n'click 4.5.0, révision r1. Si elle est publiée, et laquelle est la courante, est dit par publication.json.

Scripts npm

English · Type : référence · Public : auteur, contributeur · Contexte : dépôt du moteur, projet créé · Statut : prête · S'applique depuis : 4.5.0

Chaque script npm run du dépôt du moteur, et chaque script que reçoit un projet créé par quest-n-click create. Chaque script a sa propre section : on y renvoie par reference.npm-scripts.md#verify-game (le nom en minuscules, : écrit - ; le script d’un projet créé est #project-<nom>).

Où les lancer

Toutes les commandes se lancent depuis le dossier racine de leur projet, celui qui contient package.json :

Un script qui prend des arguments les reçoit après -- : npm run solve -- --prove. npm run -s <script> fait taire les lignes de npm lui-même (ce dont un client MCP a besoin avec npm run -s mcp).

Limite · repository-only Les scripts du dépôt du moteur n’existent pas dans un projet créé : là, npm run validate n’existe pas, utilisez npx quest-n-click validate (ou npm run quest-n-click -- validate).

Les sections ci-dessous sont générées depuis package.json, depuis cli/create.mjs et depuis les descriptions de wiki/data/npm-scripts.json (npm run wiki -- generate reference.npm-scripts) : un script ajouté sans description, ou une description dont le script a disparu, fait échouer npm run wiki -- check.

Scripts du dépôt du moteur

À lancer dans un clone du dépôt du moteur, depuis son dossier racine (celui qui contient package.json), après npm ci.

Jouer, servir et choisir le jeu

Lancer le jeu ou le Studio sur cette machine, servir un build, choisir le jeu courant du dépôt.

npm run dev

Le jeu dans le navigateur sur un serveur de dev Vite limité à la boucle locale, rechargé à chaque modification. Il pointe d’abord .cache/game vers le jeu courant (npm run game). Les paramètres d’URL comme ?dev et ?edit=<lieu> y fonctionnent (reference.dev-url-parameters).

npm run dev:lan

Le serveur de dev en mode réseau local explicite, pour un téléphone sur le même réseau : tools/serve.ts --lan lance Vite avec un jeton de capacité neuf pour chaque route qui écrit des fichiers et affiche une URL à jeton, valable une session, à ouvrir sur le téléphone.

npm run game

Pointe .cache/game (un lien symbolique que git ignore) vers games/<GAME>/, où les chemins @game de tsconfig.json regardent d’abord (games/demo ensuite, pour qu’un clone neuf passe les types). dev, check et build le lancent d’abord ; GAME=<id> npm run game change de jeu courant (4.1.6).

npm run new-game

Crée games/<id> depuis games/_template et en fait le jeu courant ; il écrit un provenance.json pour les images empruntées (toutes provisoires, CC BY 4.0).

npm run preview

Sert dist/ sur 127.0.0.1 (vite preview) : ce vers quoi les scripts e2e sont pointés après un build.

npm run start

Sert dist/ sur toutes les interfaces au port $PORT (8080 par défaut) avec sirv, via scripts/start.mjs : un lanceur Node, donc il tourne aussi sous Windows (4.1.8). Ce qu’un hébergeur comme Clever Cloud lance.

npm run studio

Le Studio (STUDIO=1), limité à la boucle locale, ouvert sur /__studio/ : lieux, dialogues, graphe des énigmes, mixage.

npm run studio:lan

Le Studio sur le réseau local, protégé par un jeton de capacité (tools/serve.ts --lan --studio).

Images, sons et pages de relecture

Préparer ce que le contenu cite, écrire les prompts d’images, et les pages qu’une personne relit sur téléphone.

npm run assets

Prépare dans public/assets/ les images et les sons que le contenu cite : tools/refs.ts les liste (lieux, personnages, objets, carte, paramètres des mini-jeux, skin, écrans de titre et de crédits, ending.scratch, extraImages) dans .cache/refs.json, puis python3 tools/assets.py les convertit (Python 3 avec Pillow) et écrit games/<GAME>/assets.gen.json, en ne retraitant que ce qui a changé.

npm run audio

La chaîne musique et effets sonores façon Mega Drive (python3 tools/audio.py ; create.music, create.sound-effects).

npm run code-wheel

La roue à codes imprimable d’un jeu (4.1.15) : le grand disque avec les portraits tirés des sprites, le petit disque et ses fenêtres, un livret (montage, la question, réponses d’entraînement tête-bêche), en couleur et en économie ; SVG toujours, PDF avec Pillow (tools/code-wheel-pdf.py ; npm run doctor le vérifie).

npm run icons

Écrit public/icons/icon-192.png, icon-512.png et public/og.png depuis le site.json du jeu (title, ogLines facultatif : jusqu’à trois lignes au-dessus du titre), sans dépendance.

npm run import-layout

Fusionne dans games/<id>/layout/<room>.json les placements exportés de la page de placement. Accepté par fichier : { "layouts": { "<room>": Layout } } (« Export JSON » de la page), { "room", "layout" } (un document de la collection layouts), ou une liste de tels documents. --dry : dire, ne rien écrire.

npm run page:placement

Écrit la page de placement, pour placer depuis un téléphone ; son export revient par npm run import-layout (create.review-pages).

npm run page:puzzles

Écrit le graphe des énigmes en page : ce que chaque règle demande et change, une fiche par objet et drapeau (create.review-pages).

npm run page:review

Écrit la page de relecture des images : chaque case de chaque planche de games/<id>/art/ en vignette avec une décision garder / refaire / inutilisée et une note, les cases que le jeu utilise marquées avec les ids qui les citent, les ids qu’aucun fichier ne fournit listés comme manquants (create.review-pages).

npm run page:storyboard

Écrit games/<id>/storyboard.json en page pour téléphone avec une zone de notes sous chaque case (--md écrit aussi games/<id>/storyboard.md, le texte brut que lisent les sous-agents, le même que l’export Markdown du Studio) (create.review-pages).

npm run page:world

Écrit la carte du monde en page : sorties, gotos, lieux inaccessibles, la source DOT (create.review-pages).

npm run prompts

Écrit games/<id>/prompts.md : tous les prompts d’images du jeu prêts à coller, une section par planche, avec un bloc STYLE et une planche de référence communs (games/<id>/art/_reference.png, ou la planche validée du héros tant qu’elle n’existe pas) ; les cases déjà découpées sont marquées « (exists — keep) ». --missing : seulement les planches dont une image n’est pas encore découpée, et seulement leurs cases manquantes ; --out <fichier> : un autre fichier de sortie. Il lit le module du jeu et le dossier d’images : personnages (cast.ts : la planche de base 6 × 4 avec les lignes de poses du moteur, human() ou cat() ; les poses spéciales que le contenu utilise — clés sprites en plus, { pose: [who, p] } et { anim: [who, p] } dans les lieux, poses des acteurs, variants — une nouvelle planche <sheet>_poses pour les poses qu’aucun sprite ne fournit encore avec les lignes à ajouter à cast.ts, la règle d’assise, le kit de bouches des poses de mouths) ; objets (chaque image d’un accessoire, d’un objet, d’un mini-jeu ou de l’interface, par dossier de planche ; les états d’un accessoire dessinés comme « the SAME object, state … ») ; décors (decor/<name> : LOCATION, les zones à montrer, les EMPTY SPOTS gauche / centre / droite tirés de layout/<room>.json) ; mobilier (accessoires dont l’image est dans un dossier furniture_*, et la liste furniture d’un lieu) ; et une liste de contrôle (référence → héros → autres personnages → objets → décors → mobilier, chacun avec sa commande python3 tools/cut-sheet.py, --cells pour les cases manquantes, puis npm run assets). Trois champs facultatifs l’alimentent sans rien changer au jeu : description d’un personnage (la ligne CHARACTER ; absente, un repère <describe: …> reste), description d’un lieu (la ligne LOCATION), furniture d’un lieu (des ids d’images dessinées sur leur propre planche, par exemple furniture_dining/table). L’outil MCP asset_prompts ({ missing?: boolean }) donne le même texte et les ids manquants en JSON.

npm run seal

Chiffre la fin scellée (ticket et carte finale) dans public/data/dossier.bin, seulement l’issue choisie (une clé de outcomes dans games/<GAME>/private/ending.config.ts ; sans lui, l’exemple commité ending.config.example.ts). Le mot de passe de la configuration doit être ending.password du fichier du jeu.

Vérifier le jeu

Ce qu’un jeu doit passer : la validation, le solveur et ses preuves, le lint, les traductions, les voix, le poids, la provenance, les gates de publication.

npm run audit:corpus

Les abstractions du solveur face à la recherche explicite sur de nombreux jeux aléatoires (simples, objets libres, trois personnages), chaque nuit : essayés, comparés, partiels, divergents par genre ; sortie 1 sur une divergence. --shard/--merge répartissent et réunissent les graines (3.7, 3.7.1).

npm run bench

Un jeu généré à la taille donnée, chaque outil chronométré dessus (--prove ajoute la preuve exhaustive, --v3 des ids stables) ; --workers-table le tableau des workers de preuve ; --matrix [--eras] le tableau de référence de 3.3 (contribute.benchmarks).

npm run i18n

Traductions : extract écrit games/<id>/locales/<lang>.json (le fichier de référence de la langue de base, ou une traduction gardée, suivie et complétée), status la couverture de chaque fichier (un texte identique à la source échoue sauf i18n: { same: [chemins] }), voices les lignes avec un id sans clip, et les clips qu’aucune ligne ne réclame.

npm run ids

Des ids stables (schéma 3) pour les règles, sujets, écouteurs, choix, blocs once/nth/cycle/random et étapes de script. Sans option, un essai à blanc. --write : dans les sources (rooms/*.ts, rules.ts, game.ts), clés de traduction renommées ; --map : ids.migration.json et ids.paths.json, et les étapes manuelles affichées ; --lines : aussi chaque objet say / toast / guide, ligne de liste, indice et réaction par genre (traductions et voix s’y rattachent) ; --lines=all : les chaînes simples aussi, exigé pour une version traduite ou doublée.

npm run ir

La représentation intermédiaire du jeu (4.1.12) : les lieux et ce qui s’y trouve, règles, sujets, écouteurs, scripts, objectifs, chacun avec le fichier:ligne qui l’écrit, et l’empreinte des extensions de confiance ; --json imprime toute l’IR, le même texte pour les mêmes sources.

npm run lint

Le lint du contenu (alias de lint:content depuis 4.1.0) : conditions que rien ne peut satisfaire, règles masquées, fausses pistes, indices bloqués, sujets et options morts, puis après un passage du solveur les actions vivantes jamais jouées et les lieux jamais atteints. Sortie 1 seulement sur une erreur que GameDef.lint.ignore n’ignore pas. --prove : la recherche exhaustive d’abord ; --static : sans solveur.

npm run lint:content

Le lint du contenu lui-même (tools/lint.ts) ; npm run lint le lance avec les mêmes arguments, et npm run quality le lance en dernier.

npm run migrate

Un projet de jeu amené à cette version (quest-n-click migrate) : un schéma plus ancien reçoit ses ids stables et les étapes manuelles s’affichent ; depuis 4.3.0 il renomme d’abord les imports web-scumm/… de l’ancien nom, les chemins du tsconfig et les commandes web-scumm des scripts (--check les nomme).

npm run playtests

Rejoue chaque session partagée par des joueurs (games/<id>/playtests/) sur le contenu actuel et les résume : temps par lieu, blocages, indices, où ils se sont arrêtés, une carte de chaleur sur le graphe des énigmes. Une session qui diverge est signalée (la réenregistrer ou la supprimer) ; --strict (le gate de publication) en fait une erreur, sortie 1, et n’exige aucun nombre de sessions. Quotas de terrain (3.7.1) : --require=N sessions, --require-completed=N, --require-devices=N familles d’appareils ; un quota manqué est une erreur. Aucun fichier : sortie 0.

npm run prove:game

Le gate exhaustif des blocages : la preuve, la preuve par chapitres, puis solve:reality ; échoue sur un blocage ou une troncature. release-check le lance.

npm run prove:matrix

La matrice de preuve (4.1.13) : douze jeux générés à trois personnages, chacun prouvé dans son propre processus sous les budgets publiés ; une ligne chacun (verdict, verdict attendu, états, temps, pic mémoire). Sortie 1 sur un verdict faux ; hors budget, c’est unknown, jamais proved. La nuit seulement.

npm run provenance

Les assets publiés par licence et ce qui a changé depuis le verrou relu ; --lock écrit games/<id>/provenance.lock.json (SHA-256 et taille de chaque fichier) après une relecture. Sortie 0 propre, 1 quelque chose à relire.

npm run remix

Un monde Remix du jeu courant (4.1.15) : --seed affiche la valeur de chaque dimension et l’empreinte du monde (--json tout le WorldVariant), --preview ajoute validate et un témoin du solveur sur ce monde, --record=N résout les N premières graines de l’échantillon publié et écrit chacune comme session de playtest portant son monde (games/<id>/playtests/remix-<seed>.session.json).

npm run replay

Joue une session exportée du jeu (réglages › sauvegarde › « Exporter la session », l’onglet Jouer du Studio, le panneau DEV) sur le vrai moteur sans affichage ; affiche le journal, le journal sémantique (4.1.11) et l’état final ; sortie 1 là où la relecture cesse de correspondre à l’enregistrement ou si son journal sémantique diffère de celui du fichier.

npm run solve

Le solveur : un témoin rapide que le jeu peut être fini depuis Nouvelle partie. --prove : la preuve exhaustive des états atteignables, blocages signalés. Autres options : --from=<checkpoint>, --max=<états>, --chapters (une recherche bornée par checkpoint qui a des goals ; avec --prove, chaque chapitre prouvé depuis chaque état frontière atteignable), --goal=100% (chaque objectif non facultatif, 4.1.12 ; sortie 2 pour un jeu qui n’en déclare aucun), --json, --profile, --por=sleep|stubborn, --workers=N|auto [--batch=64], --time=<s>, --mem=<Mo>, --ownership=off, --dominance, --symmetry, --representation=objects, --checkpoint=<fichier> [--checkpoint-every=300] [--resume], --audit-abstractions. Sortie 0 résolu, 2 tronqué (rien n’est prouvé : augmenter le budget), 1 sinon (reference.error-codes) ; voir create.solver-options.

npm run solve:reality

Un jeu qui reçoit des signaux de l’extérieur, prouvé dans chaque monde qu’il peut rencontrer (4.1.1) : fermé (par le repli de chaque signal requis), chaque scénario de games/<id>/reality/scenarios/*.json, chaque replay enregistré de games/<id>/replays/ (4.1.9), et adversarial.

npm run validate

Vérifie le contenu du jeu : références cassées, texte vide ou trop long, lignes Regarder manquantes, drapeaux jamais posés ou jamais lus. Sortie 1 pour un problème bloquant. --report : le profileur de contenu (lieux, objets, personnages, ce qui est maigre, en Markdown). --release : aussi la provenance des assets (games/<id>/provenance.json exigé, un asset provisoire est une erreur sauf exception qui le nomme) et un id stable sur chaque ligne d’un jeu publié dans une autre langue que la sienne ou doublé. --commercial : aucune exception, aucun provisoire, aucune licence non commerciale, chaque source vérifiable.

npm run verify:commercial

verify:release, puis validate --commercial --errors (aucune exception, aucun provisoire, aucune licence NC/ND, chaque source vérifiable), puis verify:dist.

npm run verify:dist

Chaque fichier du jeu construit justifié (3.7.1) : code du moteur, assets verrouillés de ce jeu (leurs octets relus), données nommées, polices, icônes, notices sous licenses/ ; tout autre fichier, ou un fichier verrouillé manquant, échoue.

npm run verify:field

verify:commercial, puis les playtests stricts avec les quotas de terrain (--require=5 --require-completed=3 --require-devices=2) : ce qu’exige une version testée par des joueurs ; pas une étape de release-check (D12).

npm run verify:game

Les gates du jeu : validate, solve, solve par chapitres, verify:variants, i18n status, lint, playtests. Une étape de build:game.

npm run verify:release

validate --release, weight --release, i18n status, voices check --release, playtests stricts : une étape de release-check.

npm run verify:variants

Chaque monde de chaque mode Remix (4.1.15, D25) : tout monde logique d’un catalogue, l’échantillon publié d’un générateur, chacun validé et résolu jusqu’à la fin et à chaque objectif (--prove : la preuve exhaustive), un certificat par monde dans .cache/proofs/variants/, la couverture par dimension et par paire, les valeurs jamais tirées, les dominantes ; --out écrit le rapport qu’une version publie ; sortie 1 si un monde échoue. Partie de verify:game.

npm run voices

Le tableau de production des voix : status par langue (lignes par statut draft, record, recorded, approved ; une ligne à aiguillages a une ligne par valeur, <id>~form=f), export le tableau pour les comédiens (CSV ou JSON), import leurs statuts, comédiens et notes dans voices.json (sortie 1 sur une ligne ou un statut inconnu), check chaque clip mesuré par ffmpeg (codec, fréquence, durée, sonie ≈ −16 LUFS, crête ; sortie 1 sur une erreur ; --release : une ligne approuvée exige son clip).

npm run weight

Ce qu’un téléphone télécharge avant que le premier lieu soit jouable, par lieu et par chapitre, face à assetBudgets (initialKB, roomKB, chapterKB), d’après les fichiers construits et le graphe des assets. Sortie 0 dans le budget, 1 au-delà ou fichier manquant (--release : ou budget non posé). --stems compte les pistes séparées des partitions.

Tests et qualité du code

Les suites de tests du moteur, ses ensembles de mutation, le formatage, les types et la base de qualité.

npm run check

Pointe .cache/game vers le jeu courant, vérifie les types (tsc --noEmit), puis lance test:node.

npm run doctor

Un rapport exploitable des prérequis, sans rien installer : Node et Chromium exigés ; Python, ses modules, ffmpeg et WebKit facultatifs. --release (4.1.8) exige Python, ses modules et ffmpeg comme release-check, et Chromium comme toujours ; Firefox et WebKit restent facultatifs.

npm run format

Le formatage Biome, écrit (biome format --write .).

npm run format:check

Le formatage Biome, vérifié sans écrire (npm run quality le lance).

npm run lint:code

Le lint Biome du code seul (biome lint .).

npm run quality

Le gate du code du moteur (4.1.0) : formatage et lint Biome, knip (fichiers et exports inutilisés), types avec tsconfig.json et tsconfig.strictest.json, puis le lint du contenu.

npm run quality:baseline

Le comportement de 4.0.0 conservé (4.1.0) : pour la démo, le jeu de référence, l’exemple des héros et les jeux de test du solveur, le témoin et la preuve, chaque sauvegarde de référence jouée jusqu’au bout, la surface publique de l’API et du MCP, la première visite (tests/quality-baseline.json). --check compare ; sans lui, il écrit le fichier et les trois chiffres des README : un nouveau test ou un bundle plus léger impose de le lancer (4.1.8).

npm run test

Lance test:node : les tests Node du moteur et des outils et ceux du jeu choisi, sans les tests lourds du solveur ni ceux liés à Python.

npm run test:assets

Les tests d’images et de la chaîne d’assets qui passent par Python (tests/pixel.test.ts, tests/studio-assets.test.ts).

npm run test:coverage

La suite sous couverture V8 (sans les tests lourds), face aux planchers de vite.config.ts ; puis npx tsx tools/coverage-ratchet.ts --strict échoue sur un plancher en retard d’au moins trois points sur ce que les tests atteignent (CI sur main et les tags, release-check, 4.1.8 ; un avertissement sur une pull request, 4.1.9).

npm run test:heavy

Les tests du solveur qui saturent le processeur (audits d’abstraction, propriétaire canonique, preuves de mémo et de propriété, la preuve du chapitre de référence, dominance, partition, matrice de checkpoints), un fichier à la fois : la nuit, plusieurs minutes chacun.

npm run test:mutation:core

Les tests de mutation des modules dont dépendent une sauvegarde, une session, une condition, un signal, une course ou un store, et des parties pures des connecteurs (SDK, lecteur MIME, éditeur de ligne, disque virtuel, cryptographie et récupération des badges : connectors-pure, que connectors nomme encore jusqu’à 4.2). Tous les ensembles sont des gates depuis 4.1.20, dont reality-store-postgres (l’adaptateur Postgres, sur un Postgres) et connectors-edge (configuration, email, vérification des badges, garde et shell du terminal, SSH, Telnet, en 4 tranches). 4.1.20 : --shard=i/n mute une tranche (des fichiers entiers, une découpe déterministe équilibrée sur leurs mutants) et --merge réunit les tranches d’un ensemble en son rapport, en refusant une tranche manquante, en double, annulée ou d’autres entrées ; ci, la nuit, le candidat et la publication lancent une matrice générée par npx tsx tools/mutation-shards.ts --matrix=gated|nightly. Chaque entrée de docs/dev/mutants.json a une catégorie, une raison, une preuve, un responsable et une version de révision, refusée à partir de cette version (une entrée échue arrête tous les ensembles). Une exécution qui mute reality-store-postgres (--set=all compris, donc release-check) exige BRIDGE_PG_URL. Un rapport dont l’empreinte des entrées (sources, tests, configurations, lockfile) est l’actuelle est réutilisé sauf --fresh ; --hash affiche cette empreinte (la clé du cache de CI) ; --doc écrit le tableau des survivants nommés dans docs/dev/MUTANTS.md.

npm run test:mutation:reality

Un ensemble de mutation (4.1.16) : le chemin des signaux Reality. core, reality, runs, remix et speedrun sont des gates depuis 4.1.17 (--set=all, un job chacun en ci avec full-ci, la nuit, le candidat et la publication).

npm run test:mutation:remix

Un ensemble de mutation (4.1.16) : la graine, l’empreinte, la compilation, l’application, les contraintes, la catégorie et les jetons Daily/Mystery d’un monde. core, reality, runs, remix et speedrun sont des gates depuis 4.1.17 (--set=all, un job chacun en ci avec full-ci, la nuit, le candidat et la publication).

npm run test:mutation:runs

L’ensemble de mutation de la file des speedruns (4.1.17) : admission, quota et classement (bridge/src/runs.ts, runs-store.ts, runs-limiter.ts), jugé par les quatre fichiers de tests courts des courses du Bridge ; gate dès le départ (--set=all, la publication, un job à lui).

npm run test:mutation:speedrun

Un ensemble de mutation (4.1.16) : l’enveloppe et le h0 d’une course, l’enregistreur et le vérificateur. core, reality, runs, remix et speedrun sont des gates depuis 4.1.17 (--set=all, un job chacun en ci avec full-ci, la nuit, le candidat et la publication).

npm run test:node

La suite unitaire sans les tests liés à Python (tests/pixel.test.ts, tests/studio-assets.test.ts) ni ceux qui saturent le processeur (les fichiers de test:heavy) ; npm run check la lance, les lourds tournent la nuit.

npm run tsc

Le compilateur TypeScript 7 lui-même (4.1.8 ; le lien tsc peut appartenir au paquet typescript6 des outils) : check et quality l’appellent.

Tests dans le navigateur (e2e)

Chacun fait tourner le produit dans un vrai navigateur avec Playwright (npm run doctor dit quels navigateurs sont installés). Un navigateur qui ne se lance pas sort en 3 là où le script le dit (0 avec --allow-skip).

npm run e2e

Une partie jouée au toucher dans un navigateur à la taille d’un téléphone (E2E_BROWSER=chromium|webkit|firefox ; captures dans E2E_OUT, par défaut /tmp/e2e) ; le serveur doit déjà répondre à l’URL. Le games/<id>/e2e.mjs propre au jeu (qui exporte run(harness)) est utilisé s’il existe, sinon le chemin du solveur (npm run solve -- --json) est joué au toucher. --renderer canvas : tout le jeu dessiné par le peintre Canvas ; --lang <xx> : tout le jeu dans cette langue, en échouant sur tout texte anglais par défaut du moteur resté visible.

npm run e2e:a11y

Les gates d’accessibilité et de stockage dans un vrai navigateur (E2E_BROWSER=chromium|webkit) sur le build de production du jeu d’exemple : axe sur la conversation, la carte, les emplacements, les confirmations et chaque mini-jeu ; chaque mini-jeu gagné au clavier ; une ancienne sauvegarde mise à niveau. Sortie 3 : une vérification que le navigateur ne sait pas automatiser.

npm run e2e:canonical

canonicalJson (src/engine/core/canonical.ts, 4.1.12) sur cinquante valeurs limites dans Chromium, WebKit et Firefox, face aux textes qu’écrit Node : un navigateur qui écrit une valeur autrement échoue ; sortie 3 quand un navigateur ne se lance pas (0 avec --allow-skip).

npm run e2e:music

Les gates du directeur musical (3.5) sur le build de production servi : 30 minutes hors ligne sans dérive, 100 changements sans clic, gigue en temps réel, les pistes du thème dans le jeu ; --only=reference (GAME=reference) : deux partitions, des ponts, une restauration et un arrêt en pleine transition, la crête décodée (Chromium et WebKit, 3.8).

npm run e2e:perf

Images par seconde pendant que le héros marche, le processeur ralenti (4× par défaut, le substitut du téléphone) ; échoue sous --min (30 par défaut).

npm run e2e:pwa

La PWA dans un vrai navigateur (E2E_BROWSER) : installée, tout le jeu préchargé puis ouvert hors ligne. Avec --serve=dist le script sert lui-même le build et peut en publier un second : --update (la bannière, la sauvegarde gardée, le nouveau worker aux commandes), --interrupted (le chargement du worker échoue : pas de bannière, l’ancien sert), --reinstall (worker et caches supprimés, réinstallés, la sauvegarde gardée) ; --allow-skip accepte la navigation hors ligne de WebKit, que Playwright ne sait pas piloter.

npm run e2e:reality

Le Reality Bridge de bout en bout sur le build de production de games/signals et un vrai Bridge de référence qu’il lance sur 127.0.0.1:8787 (4.1.1) : appairage, le même webhook deux fois, hors ligne, retour en ligne, le signal appliqué une fois, la session rejouée ; depuis 4.1.9 deux connecteurs et les replays du chapitre d’exemple.

npm run e2e:remix

La même graine donne le même monde, la même empreinte et la même roue à codes dans Node, Chromium, WebKit et Firefox (4.1.15, ADR 0018) : 50 graines de la référence dans trois modes ; un navigateur qui diffère échoue, la graine nommée ; sortie 3 quand un navigateur ne se lance pas (0 avec --allow-skip).

npm run e2e:remix-speedrun

Remix et Time Attack ensemble (4.1.16) : pour chaque politique de monde de la référence (Story, Remix Fixed, Remix Random, Daily, Mystery) le monde construit, la route du solveur enregistrée par le vrai enregistreur dans Node, Chromium, WebKit et Firefox (les quatre .wsrun identiques à l’octet), vérifiée dans un nouveau processus, puis par le worker isolé d’une file du Bridge : verdict, clé de classement, confiance ; sortie 3 quand un navigateur ne se lance pas (0 avec --allow-skip).

npm run e2e:smoke

La partie générique sur le build de production (e2e.mjs --generic --prod) : le chemin du solveur rejoué au toucher.

npm run e2e:speedrun

Le déterminisme du speedrun dans Chromium (aussi avec un processeur quatre fois plus lent), WebKit et Firefox (4.1.14) : les vecteurs du générateur, la course de référence rejouée jusqu’au même état final, IGT et preuve finale, une course reprise depuis IndexedDB après fermeture de son onglet ; sortie 3 quand un navigateur ne se lance pas (0 avec --allow-skip).

npm run e2e:studio

Le Studio dans un navigateur sur le serveur de dev : une mise en scène éditée sans JSON à la main (le formulaire, l’aperçu du diff, Appliquer validé par le serveur, Annuler), le fichier du lieu restauré dans tous les cas.

npm run e2e:studio-collab

Trois personnes sur un même Studio hébergé (4.2.1, le job studio-hosted de la CI ; studio-client d’abord) : présence, une zone tenue par un autre refusée avec le brouillon gardé, un relecteur empêché d’écrire, une coupure rattrapée depuis le journal, l’écran des membres, les pages de connexion et « accès non accordé ».

npm run e2e:studio-hosted

Le Studio hébergé dans un navigateur (4.2.1, le job studio-hosted de la CI ; studio-client d’abord) : connexion, l’éditeur de lieu sur l’origine du jeu, sa sauvegarde via le Studio, le mur entre les deux origines, Jouer, déconnexion (Firefox et WebKit en https ; WebKit sous macOS seulement).

npm run e2e:taps

Les verbes par défaut dans le navigateur, sur le chapitre de référence (4.0, GAME=reference) : un double toucher sur une sortie la franchit, sur un personnage lui parle ; un objet pris dans le sac est donné à un personnage, utilisé sur tout le reste.

npm run e2e:visual

Chaque lieu, à l’arrêt, face à tests/visual/<game>/<room>.png (la scène seule, animations figées) ; plus de 0,5 % des pixels changés échoue ; --update écrit les références. Le build de production doit être servi.

npm run e2e:weight

Le budget de poids face aux octets qu’un navigateur transfère vraiment : une première visite du build de production dans Chromium, du titre au premier lieu jouable ; une requête hors du périmètre initial prévu (npm run weight -- --json) échoue.

npm run e2e:worker-container

Le worker de speedrun dans son profil de conteneur (4.1.17, Linux avec Docker, le job worker-container de la CI) : la course de référence vérifiée dedans ; un script hostile privé de HTTP, DNS, TCP, d’écriture hors de /tmp et des secrets de l’hôte, son processus enfant sans réseau, tous tués par le délai du conteneur lui-même ; puis une course à nouveau. node tools/speedrun/container.mjs --image= --app= [--games=] [--allow-network] affiche le profil sous forme de commande worker.

Construire, empaqueter et publier

Le build, les archives qu’une version publie, les vérifications d’un candidat, les passes des personnes (Field Kit) et la chaîne de publication.

npm run audit

Lance audit:assets.

npm run audit:assets

Fait échouer le build si quelque chose du projet privé d’origine fuit dans le dépôt public (noms de vraies personnes, ids de planches privées, nom du projet privé), les mots bloqués gardés en préfixes SHA-1. build:game le lance. Les licences des fichiers de dist/ relèvent de verify:dist.

npm run audit:deps

npm audit --omit=dev : les alertes des dépendances d’exécution (CI sur main et release-check).

npm run build

npm run check (types et tests Node), puis build:game : le dist/ statique (le jeu, ses assets, le service worker). Il exige un témoin gagnant.

npm run build:game

Les gates du jeu (verify:game), le bundle Vite, verify:dist, la vérification des spoilers, l’audit de fuite (audit:assets) : ni tsc ni suite unitaire (la CI les lance une fois).

npm run build:web

vite build seul, sans gate : ce qu’un hébergeur lance après sa propre installation (sur Clever Cloud, CC_POST_BUILD_HOOK=npm run build:web).

npm run check:spoilers

Vérifie qu’aucun texte de la fin scellée, quelle que soit l’issue, n’apparaît en clair dans dist/.

npm run connector-archive-e2e

Les quatre connecteurs joués de bout en bout depuis leur archive face à un Bridge depuis la sienne (4.1.19) : email par webhook et par IMAP (un serveur propre au script), Telnet, SSH et Open Badge ; le job connector-archive-e2e du candidat. Les vrais fournisseurs et l’exposition restent une passe humaine (connectors-real-security).

npm run external-consumer

Les quatre archives utilisées comme un tiers les utilise, sous Linux, macOS et Windows (4.1.18) : lues (noms, versions, licences, exécutables, exports, dépendances), un jeu fait sur l’ancienne version amené à elles (depuis 4.3.0 comme son auteur le ferait : l’ancien paquet web-scumm désinstallé, quest-n-click installé, migrate, verify, build, sa sauvegarde et une nouvelle partie jouées jusqu’au bout via quest-n-click/testing), create-quest-n-click, le Bridge (SQLite, Postgres avec CONSUMER_PG_URL) et un scénario de connecteur (un code d’appairage, une lettre signée acceptée, son doublon, une contrefaçon refusée) ; aucun module du dépôt. Le candidat le lance sur ses propres archives.

npm run field:bundle

Un rapport et ses preuves listées dans une archive, journaux caviardés, refusé sur une clé ou un jeton. (contribute.field-passes)

npm run field:carry

4.1.20 (ADR 0024) : une passe reportée sur un nouveau candidat quand aucun fichier de sa surface n’a changé (version comprise) : une attestation en attente que le mainteneur approuve dans un commit signé ; --check-range=<a..b> refuse une plage qui change à la fois la racine de confiance et une attestation. (contribute.field-passes)

npm run field:check

Chaque rapport de passe vérifié face à son candidat (commit, exécution, empreintes), le SHA-256 de ses preuves et la recherche de fuites. (contribute.field-passes)

npm run field:init

Le Field Kit (4.1.18) : les passes humaines en rapports JSON à not-run, liés à cette exécution candidate. (contribute.field-passes)

npm run field:report

Le tableau des passes humaines généré depuis les rapports. (contribute.field-passes)

npm run field:verify-bundle

4.1.19 : l’intégrité d’une archive de passe, son candidat, puis qui a fait son manifeste (son attestation, ou l’exécution). (contribute.field-passes)

npm run fresh-install

Le moteur utilisé comme un autre projet l’utilise (3.9) : un jeu créé depuis le modèle empaqueté hors du dépôt, l’archive installée, ses propres assets, verify et build, puis joué jusqu’à la fin dans un navigateur ; create-quest-n-click installé depuis son archive et lancé, le Bridge installé et qui sert, les connecteurs installés sans code natif et qui répondent à --help. La CI le lance.

npm run locks

Les verrous versionnés du Bridge, des connecteurs et de l’image du Bridge (scripts/locks/, 4.1.19), faits depuis le verrou racine (chaque version gardée) ; --check dit si chacun correspond encore à son manifeste et au verrou racine, sans réseau. scripts/pack.mjs les copie dans les archives comme npm-shrinkwrap.json ; scripts/sbom.mjs et scripts/bridge-image.mjs font les cinq SBOM CycloneDX du candidat et son image. À lancer quand une dépendance de ces paquets change, relire le diff, le commiter.

npm run ops:qualify

Le profil de qualification du Bridge (ops/qualify/, 4.1.18) construit depuis l’archive et monté derrière HTTPS sur Docker : trois instances sur un Postgres, deux tenants, une instance tuée pendant des propositions, un flux sur une autre, les tenants séparés, sauvegarde, la topologie détruite et restaurée, puis (4.1.20) une restauration refusée pendant que les Bridges servent et --mode=replace-store une fois arrêtés. Il écrit ops-qualify.json (schéma 2 : le profil, le commit, --candidate-run, le SHA-256 des quatre archives, chaque étape par son id stable avec sa durée et son premier défaut ; le workflow qualify). Un candidat lancé à la main exécute le profil complet et son gate refuse moins (tools/release/candidate.mjs qualification) ; celui d’une pull request lance --short.

npm run pack

Les archives quest-n-click, create-quest-n-click, quest-n-click-bridge et quest-n-click-connectors (4.1.9) qu’une version publie, depuis les fichiers suivis seulement : un fichier non suivi sous une racine publiée refuse l’empaquetage (4.1.8) ; --publish-dry-run montre ce que npm publish enverrait (contribute.npm-packages).

npm run readme-quickstart

Le démarrage rapide du README tel qu’un lecteur le copie (4.1.19) : le bloc sous « ## Start » lancé tel quel dans un dossier hors du dépôt, son URL d’archive pointée vers l’archive du candidat (file:), npm run dev jusqu’à ce qu’il réponde, puis verify et build ; le job readme-quickstart du candidat. --published, après le tag : l’URL du README répond avec le SHA-256 que liste le SHA256SUMS de la version.

npm run release-check

Ce que lance la CI, d’un coup : doctor --release, quality, build, la couverture et son cliquet strict, verify:release, prove:game, solve --audit-abstractions, la contre-vérification Rust (--require-rust), chaque ensemble de mutation (--set=all), les paquets avec --publish-dry-run, audit:deps et npm audit --audit-level=high.

npm run release-check:ci

La même chose sans les ensembles de mutation (4.1.10 ; le workflow de publication les lance en jobs à côté), la couverture rapportée pour GitHub Actions et en JSON dans .cache/test-report/vitest.json.

npm run release-check:local

Ce qu’une machine peut lancer de la chaîne de publication : quality, docs:truth, la suite unitaire, build:game, quality:baseline -- --check --dist.

npm run ship

La chaîne de publication en commandes (4.1.8) : attendre les vérifications d’une pull request (une relance d’un job échoué), la fusionner, attendre la CI de main sur la fusion, taguer et pousser, suivre la CI du tag et l’exécution de publication, télécharger la version et vérifier ses sommes et attestations ; chain <pr> <version> fait tout. Chaque commande écrit son PID dans .cache/pids/. tag exige --candidate=<id d’exécution> depuis 4.1.17 : une exécution verte du workflow candidate (gh workflow run candidate --ref main -f sha=<sha> : release-check, la suite lourde trois fois sur des runners neufs, la charge sur SQLite et Postgres, les quatre environnements, un job par ensemble de mutation en gate) dont le manifeste nomme ce SHA ; release.yml publie les fichiers .wsrun de cette exécution après vérification de leur SHA-256 (tools/release/candidate.mjs). 4.1.20 : preflight-stable --candidate=<exécution> dit ce qui manque encore pour la 4.2 stable, vérification par vérification, sans rien changer ; tag --sign signe un tag avec une clé SSH ; verify lance aussi gh release verify (contribute.releasing).

npm run upgrade-check

Un jeu fait sur une version plus ancienne amené à celle-ci comme le ferait une équipe (4.0) : créé avec l’ancien paquet, vérifié, une sauvegarde faite dedans, puis ce paquet installé, migré, mis à niveau et joué avec cette sauvegarde. La CI le lance.

Studio, Studio Server et MCP

La démo statique du Studio, le serveur et l’application de traitement du Studio hébergé, et le serveur MCP pour un assistant IA.

npm run build:studio-demo

Le build statique du Studio en mode démo (STUDIO=1 VITE_STUDIO_DEMO=1 vite build), avec son instantané du jeu courant (studio.demo-mode).

npm run mcp

Le serveur MCP du jeu courant sur stdio, pour un assistant IA (-s garde la bannière de npm hors de la sortie du protocole) ; avec --server <url>, les outils d’un Studio hébergé via son API, avec le jeton de la CLI (studio-server login --server <url> d’abord, 4.2.3). studio.mcp-setup, studio.mcp-tools.

npm run studio-apply

Applique au jeu courant un patch téléchargé depuis la démo du Studio (« Download patch ») via le cœur du Studio : les mêmes écritures que le Studio du serveur de dev aurait faites (textes, placements, storyboard.json, notes).

npm run studio-client

La page du Studio que sert le Studio Server (4.2.1) : studio.html et son code seuls, construits dans .cache/studio-client (STUDIO_CLIENT=1 VITE_STUDIO_HOSTED=1).

npm run studio-server

Le Studio Server, un Studio en ligne pour une équipe (4.2.1 ; reference.cli liste ses commandes) ; backup --to-bucket [--keep n] écrit la sauvegarde dans le bucket de l’instance (4.2.3).

npm run studio-snapshot

L’instantané de la démo seul : tout ce que le Studio lit du serveur de dev pour le jeu courant, dans un fichier JSON (par défaut public/studio-demo/snapshot.json).

npm run studio-worker

L’application de traitement du Studio Server, qui ne détient aucun secret de la plateforme (ADR 0028) ; WORKER_PUBLIC_KEY et WORKER_INSTANCE sont exigées.

Reality Bridge, connecteurs et speedrun

Le monde hors du jeu (signaux, connecteurs) et les outils de speedrun.

npm run bridge

La ligne de commande du Reality Bridge pour le jeu courant : init, serve (--tenants=a,b, --store=, --trust-proxy=<liste>, --tenant-header), grant, rotate, revoke, doctor, compact ; depuis 4.1.10 migrate --from=jsonl --to=sqlite et migrate --schema=N, tenant export|delete, backup --out=, restore --from= --mode=merge|replace-store [--lock-timeout=<ms>] (4.1.20 : le mode toujours dit, le store tenu seul sous un bail de maintenance). bridge.cli.

npm run bridge:load

Le Bridge sous charge (4.1.10) : trois processus serve sur un store (SQLite, ou Postgres avec --store ou BRIDGE_STORE ; une valeur vide n’est pas une valeur), le rapport nommant le backend vraiment ouvert et le commit, vérifié par npx tsx tools/load-report.ts <rapport> --store=<genre> (4.1.17) ; débit et latence p50/p95/p99, le journal et les flux vérifiés ensuite (sortie 1 sur un signal perdu, doublé ou désordonné). La nuit le lance sur les deux stores.

npm run connector

Un connecteur du monde extérieur, dans son propre processus, depuis les sources du dépôt (4.1.9) : santé et métriques sur un port local, SIGTERM vide le travail en cours et sort en 0 ; la commande du paquet est quest-n-click-connector (bridge.connectors).

npm run fuzz:connectors

Les analyseurs des connecteurs sous mutations aléatoires à graine de leur corpus, sans réseau : chaque entrée reçoit une réponse, aucun plantage, RSS avant et après (4.1.9 ; la nuit une minute par connecteur, la CI une demi-minute).

npm run reality:spike

Une sonde de la cryptographie du Bridge (4.1.1) : Ed25519 dans WebCrypto (Node, Chromium, WebKit), un JWS compact vérifié sur ses octets exacts, la taille gzip de ce vérificateur, les temps de création, d’atténuation et d’autorisation Biscuit ; un tableau Markdown.

npm run reality:xcheck

La contre-vérification Rust du protocole (4.1.1) : les échantillons officiels de Biscuit passés par l’implémentation JavaScript du Bridge et par la crate Rust (bridge/xcheck, quand cargo est là) ; --require-rust échoue sans elle, comme la CI et release-check.

npm run runs:load

Le classement des speedruns à l’échelle (4.1.17) : un store au schéma du Bridge rempli de --runs courses vérifiées sur un tableau (et autant sur un autre), le tableau lu --reads fois ; latence p50/p95, mémoire résidente et plan SQL (EXPLAIN QUERY PLAN / EXPLAIN) rapportés avec le backend et le commit ; une borne dépassée sort en 1. Le candidat et la nuit le lancent sur les deux stores (2 000 ms en p95, 512 Mo).

npm run speedrun:livesplit

LiveSplit (4.1.14, D23) : export écrit un fichier de splits .lss depuis une course (sa catégorie, ses splits et ses temps en jeu comme record personnel) ; serve est l’autosplitter, qui pilote LiveSplit via son propre serveur WebSocket local à partir des événements que le jeu envoie (?speedrunTool=7778).

npm run speedrun:overlay

Une Browser Source OBS (4.1.14, D23) : http://127.0.0.1:7777/?mode=full, compact ou transparent, par Server-Sent Events, sur 127.0.0.1 seulement ; le jeu envoie les événements de sa course avec ?speedrunTool=<port>, rien d’autre, et seulement depuis son origine (le serveur de dev et la prévisualisation par défaut).

npm run speedrun:verify

Le .wsrun d’un speedrun rejoué contre le jeu courant (GAME=<id>) : un verdict, son code, sa raison et la confiance qu’il accorde (ADR 0017) ; sortie 0 pour valid et valid-unranked, 1 sinon (inconclusive compris). quest-n-click speedrun verify de la CLI et l’outil MCP speedrun_verify le lancent. npx tsx tools/speedrun/reference-run.ts réenregistre la course de référence commitée (après npm version ou un changement de la logique du chapitre de référence).

Documentation, changements et CI

Les outils qui gardent la documentation, le CHANGELOG et le plan de la CI fidèles au code.

npm run changes

Les fragments CHANGELOG et LOG d’une branche (changes/<slug>.md, <slug>.log.md) : --check fait échouer une pull request qui change le code sans fragment (le job check de la CI) ; --assemble les verse dans CHANGELOG.md et docs/dev/LOG.md dans l’ordre où ils ont atteint main.

npm run ci:plan

Quels jobs lourds de la CI un changement demande (4.1.9, tools/ci-plan.ts) : chaque fichier changé classé par la première règle qui correspond, une ligne de JSON (un booléen par gate : node24, e2e, reference, reality, pwaFirefox, windows, secondGame, freshInstall, upgrade, auditDeps), et depuis 4.5.0 docs avec docsPages, les pages du wiki dont le changement touche les sources ; le workflow, le plan, une configuration commune, le cœur du moteur et un chemin qu’aucune règle ne connaît lancent tout ; en lecture seule.

Chaque lien externe de la documentation interrogé une fois (HEAD, puis GET), statuts par domaine, sortie 1 sur un lien ni 2xx ni 3xx ; une personne le lance avant une version, jamais la CI (le réseau n’est pas un test).

npm run docs:screenshots

Les images du README tirées du vrai bundle de production et du vrai Studio (Playwright, puis Pillow) : des WebP dans docs/img/readme/, 1440 px de large au plus, nommés pour la version qui les a prises ; --keep-png garde les captures brutes dans .cache/docs-shots.

npm run docs:truth

Ce qu’affirme la documentation, face au code (4.1.16) : les schémas de sauvegarde et de .wsrun, chaque script npm et fichier tools/ ou scripts/ cité, les capacités dites montées, aucun lien de version plus récent que la version ; sortie 1, chaque contradiction nommée. Le job check de la CI.

npm run wiki

La source de la documentation dans wiki/ (4.5.0, tools/wiki.ts) : check valide le manifeste (wiki/manifest.json : ids, URL EN-<Domain>-<Topic> / FR-<Domaine>-<Sujet>, états, sources, questions), les pages, leurs liens, sections et parties générées, et n’échoue que sur des erreurs (les liens vers des pages prévues sont listés) ; stats compte les pages par état, domaine, type et langue ; build --target wiki écrit le dossier publié sur le wiki GitHub (Home.md, une barre latérale par langue, le pied de page, les pages ready sous leur URL, --preview y ajoutant les brouillons sous un bandeau, les quatre index), dans un dossier hors de l’arbre de travail (ou sous .cache/) qu’il ne vide que s’il l’a construit ; env et generate réécrivent depuis le code les pages de référence générées ; les autres commandes empaquettent, archivent et publient (contribute.writing-docs).

Scripts d’un projet créé

Écrits par quest-n-click create (ou npx create-quest-n-click) dans le package.json du nouveau projet. À lancer depuis le dossier du projet, après npm install : chacun appelle la commande quest-n-click du moteur installé.

npm run dev

quest-n-click dev : le jeu dans le navigateur sur le serveur de dev de Vite, rechargé à chaque modification ; ?edit=<lieu> ouvre l’éditeur de placement.

npm run studio

quest-n-click studio : le Studio (lieux, dialogues, graphe des énigmes, mixage), ouvert sur /__studio/.

npm run assets

quest-n-click assets : game/art et game/audio vers public/assets (Python 3 avec Pillow).

npm run verify

quest-n-click verify : validate, solve, i18n status, lint, playtests : le contenu vérifié, le solveur trouve la fin.

npm run build

quest-n-click build : assets, verify, le build de production dans dist/, chacun de ses fichiers justifié, licences comprises.

npm run release

quest-n-click release : build, puis les gates de publication (validate et weight --release, i18n status, voices check --release, playtests stricts, la preuve exhaustive, solve-reality) ; --commercial : aucune exception, aucun provisoire. Les images du modèle sont provisoires : une publication les refuse tant que chaque fichier n’est pas remplacé et relu (npx quest-n-click provenance --lock).

npm run preview

quest-n-click preview : sert dist/ sur 127.0.0.1.

npm run quest-n-click

La commande du moteur elle-même, pour toutes les autres (doctor, validate, solve, lint, migrate…) : npm run quest-n-click -- help les liste (reference.cli).

Modifier la source de cette page · Signaler une erreur