Développer et tester une appli avec le DEV HUB

Cette fiche décrit les fichiers, le build et la recette d’une appli. Pour choisir les API, partir du mémo. Pour les champs du manifeste, lire manifeste et affichage, plugins, panneaux de préférences et formats.

Retrouver le projet et les outils

Le Kappapps DEV HUB fournit le contexte courant dans HUB-DEV.md : identité de l’appli, workspace source, runtime effectif, chemin du corpus global et endpoint MCP. L’accès MCP s’active par appli depuis son onglet IA. Le port par défaut est 7581 ; 7580 est celui du HUB streamer. Utilise l’adresse indiquée, sans remplacer arbitrairement localhost par 127.0.0.1.

Les fichiers AGENTS.md et CLAUDE.md peuvent contenir les consignes propres au projet ; le HUB y maintient un aiguillage vers HUB-DEV.md. Ce dernier est généré : ne l’édite pas à la main. Le corpus est global au poste, sans copie ai-knowledge/ nécessaire dans l’appli. Une extraction manuelle du ZIP reste possible hors HUB ; elle fournit AGENTS.md et ai-knowledge/.

Besoin	Outil MCP
Vérifier l’appli, son état et le dossier documentaire	get_app_status ; propriété knowledge_dir
Découvrir les fiches et exemples disponibles	read_app_doc sans doc
Lire une fiche	read_app_doc avec doc: "reference/preferences", par exemple
Rechercher une méthode ou un concept	search_app_knowledge avec query, puis lire la fiche trouvée
Lire un exemple complet	read_app_example avec son name ; sans nom pour l’index
Actualiser le corpus global et le contexte généré	download_app_knowledge
Actualiser les types locaux	download_sdk_typedefs → app-sdk.d.ts

Les identifiants MCP restent reference/<nom>, y compris pour les fiches partagées. Dans le site web, les liens conservent les racines applis/ et common/ ; dans le ZIP, le corpus global et les réponses de read_app_doc / read_app_example, les références sont réunies sous reference/. Pour suivre un lien avec MCP, résous-le par rapport à la fiche courante et passe le chemin obtenu à read_app_doc ; l’extension .md est optionnelle. Les pièges partagés portent l’identifiant common-PITFALLS.

Sans outils MCP, consulter le mémo web, l’index documentaire ou les types SDK V2. La fiche et les types servent à vérifier un contrat ; ne déduis pas une signature du seul nom d’un service.

Une appli créée sur le portail peut manquer dans la liste déjà chargée du HUB. refresh_apps recharge cette liste, mais arrête les serveurs locaux actifs : relever les sessions utiles puis redémarrer serve pour chacune. Pour une nouvelle appli, récupérer son bootstrap avec pull avant de compiler ; si le garde-fou de l’onglet IA refuse le pull de l’agent, demander au développeur de l’effectuer dans le HUB. Vérifier ensuite get_app_status pour chaque projet, notamment lors d’une recette de services entre deux applis.

Sources et fichiers générés

Le bootstrap classique utilise ces fichiers ; un projet compilé peut organiser ses sources autrement.

Fichier	Rôle
index.html	Charge le SDK, puis styles et code métier après AppliLoaded ; voir cycle de vie.
script.js, style.css	Logique et présentation de l’appli.
infos.json	Manifeste source à la racine du workspace : modes, scopes, entrées, services, plugins et formats.
textset.js	Textes traduits, déclaré par textset dans le manifeste.
preferences.config.js	Schéma des réglages streamer, compilé en config/preferences.config.json.
cli-config.json	Entrées du compilateur, exclusions et éventuel runtime.root.
modules/, assets/	Modules sources et ressources ; inclure ce qui est nécessaire dans le runtime publié.
config/ dans le runtime	JSON compilés : modifier leurs sources, puis recompiler.

Chaque exemple précise les fichiers à conserver, ajouter ou remplacer. Fusionne ses extraits de manifeste avec le manifeste courant ; ne remplace pas les autres déclarations du projet par un extrait.

Le bootstrap précise les six configurations, les guides déclarés et l’ordre d’initialisation. Le projet compilé complet montre les fichiers à construire ; la livraison distingue runtime, présentation du catalogue et guides destinés aux utilisateurs.

Classique ou runtime compilé

Sans bloc runtime, ou avec "runtime": { "root": "." }, le workspace contient aussi les fichiers exécutés. En mode classique, push publie les fichiers non exclus et pull remplace ce périmètre, en préservant les dotfiles (dont .git), node_modules et les exclusions. Les sauvegardes locales n’embarquent ni .git ni node_modules.

Pour un projet avec build, préfère un runtime autonome, par exemple "runtime": { "root": "dist" }. Ce chemin doit rester relatif et interne au workspace, sans segment ... Seul ce dossier est servi, comparé, sauvegardé et publié. Le ZIP publié contient directement index.html, sans dossier dist/ supplémentaire. Le pull et la restauration remplacent ce runtime en préservant les sources.

Modifie les sources, puis lance explicitement la commande de build du projet, par exemple npm run build. Le HUB ne lance pas automatiquement les scripts npm ou les commandes déclarées dans cli-config.json. N’édite pas le résultat dans dist/.

Les entrées de configCompiler restent relatives au workspace ; les JSON sont écrits dans <runtime>/config. Le HUB copie le infos.json source dans le runtime avant comparaison, synchronisation ou push. transpile compile les configurations ; watch les recompile à leurs changements. Ils ne remplacent pas le build de l’appli. Voir aussi les pièges de publication.

Après push ou transpile, lis le rapport validation : un brouillon enregistré peut encore contenir des erreurs bloquant sa soumission. Le panneau Diagnostics Kappapps et get_app_status.local.validation conservent le dernier résultat. check_app vérifie les fichiers déjà en ligne, sans compiler, envoyer ou soumettre les fichiers locaux. Voir diagnostics et blocages.

Recette locale

1. Vérifie l’appli ciblée et son runtime avec get_app_status. Construis le projet si nécessaire, puis compile les configurations : un build qui vide le runtime efface aussi les JSON déjà générés. Pour les images nombreuses, utilise create_image_atlas (alias historique compact_image_assets) ; voir atlas.
2. Démarre la session de développement ou serve. Le serveur local couvre le runtime et les dossiers plugins déclarés ; les pages Kappapps du brouillon peuvent alors charger ces fichiers.
3. Appelle prepare_preview avec la surface déclarée à tester : overlay, external, viewers_plugin ou streamer_plugin. Ouvre immédiatement preview_url dans ton navigateur/Playwright, au viewport fourni. Attends data-dev-preview-ready, puis cible frame.selector / frame.origin.
4. Pour les plugins, conserve le shell Kappapps fourni : il porte le bridge, l’authentification et les sockets du channel DEV. Charger directement leur iframe localhost ne reproduit pas ce contexte. L’overlay OBS n’est pas cliquable ; teste les interactions dans la popout ou le plugin approprié.
5. Vérifie le démarrage, l’état initial, les changements de préférences, les interactions et les sorties concernées. Pour un plugin, teste aussi une arrivée tardive et une reconnexion selon le protocole prévu. Pour le vertical, teste chaque format déclaré. Note les erreurs de console et les effets réellement observés.

Le ticket de preview_url est à usage unique et expire en deux minutes. Après redirection, l’URL nettoyée reste rechargeable pendant la durée annoncée par session_ttl_seconds, tant que son contexte est actif et son cookie conservé. Un second contexte ouvert dans le même profil invalide le premier au rechargement (voir le dépannage). Ne conserve aucune de ces URLs dans les logs, le compte rendu ou le dépôt.

Le marqueur data-dev-preview-ready signale que le shell est prêt ; vérifie ensuite le démarrage effectif de l’appli. Une URL locale joignable ne prouve pas que son iframe a chargé ni que le handshake SDK a abouti. Inversement, ouvrir directement index.html peut laisser une page vide : elle attend normalement son parent Kappapps.

Conserve une trace des versions, cas testés, résultats et limites. Une simulation avec des doublures ne prouve pas le fonctionnement des sockets ou permissions réels. Les tests qui parlent dans le chat, distribuent des récompenses ou modifient des données doivent correspondre à la demande du développeur. Une preview réussie n’effectue pas de publication ; pour push ou pull, respecte le périmètre demandé et les gardes du HUB.

Dépannage de la preview

À lire seulement si la recette normale échoue.

• Iframe vide dans un navigateur piloté : relever l’URL, les erreurs et l’état du core (get_app_status). Comparer avec le même profil après détachement du débogueur (dans Chrome, « Annuler » dans le bandeau de débogage) puis rechargement. Si l’appli apparaît, c’est une limite de l’outil de pilotage : ne modifier ni scopes, ni sandbox, ni permissions.
• Repli géré : fermer l’onglet, puis open_managed_preview avec context_id. Cet outil remplace le contexte et renvoie un nouveau context_id, à passer à snapshot_app, capture_app_screenshot, interact_app, evaluate_app, wait_for_app, resize_app et restart_app. C’est une fenêtre masquée : elle ne valide pas la cadence d’une animation ; utiliser pour cela une surface visible (popout si external est autorisé), attendre qu’elle soit visible et, après un redimensionnement, la mise à jour de kapp.overlay.layout. resize_app ne cible que le repli.
• Plusieurs previews de la même appli : plugin et overlay géré peuvent coexister dans les deux ordres. get_app_status les liste dans local.preview_contexts (context_id, surface, controllable, selected). Les outils de pilotage acceptent context_id ; sans cet argument, ils ciblent la dernière preview réellement ouverte dans le HUB. Préparer une URL ne change pas cette cible. read_app_console accepte aussi context_id pour filtrer une preview ; sans cet argument, sa console regroupe les previews de l’appli.
• Fermer ou remplacer une preview : unload_preview attend la fermeture de sa session d’overlay côté serveur avant de révoquer son accès et de fermer ses fenêtres. Avec context_id, il ferme uniquement ce contexte ; sans cet argument, tous ceux de l’appli. Un arrêt non confirmé renvoie une erreur et conserve le contexte pour une nouvelle tentative. La préparation d’un nouvel overlay vérifie aussi que le core a libéré l’ancienne instance. Ne pas boucler sur un context_id déjà consommé, ni conclure au nettoyage sur la seule fermeture d’un onglet.
• « Preview DEV expirée » : un second contexte dans le même profil remplace le cookie du premier ; redemander une URL pour la surface concernée.