Aller au contenu
Webcosa Développeurs
RessourcesOuvrir le CMS

#CLI

Le CLI transporte les fichiers d’un thème entre un dossier de ta machine et un site Webcosa. Tu édites dans ton éditeur — ta coloration syntaxique, ton Git, tes raccourcis — tu pousses, le site rend. Et quand le thème est en ligne, il répond à la question d’après : est-ce que le site va bien ?

Aucune dépendance : node:fs, node:path, node:util, et rien d’autre.

webcosa aide

#Deux groupes

Les commandes s’aiguillent par groupe, parce qu’il y a deux métiers et qu’ils ont chacun un verifier, un diagnostic et un ouvrir qui ne font pas la même chose. Les fondre aurait obligé à inventer verifier-le-site et verifier-le-theme — autant écrire le groupe une fois, devant.

webcosa themeles fichiers d’un thème

Créer un dossier de thème, le récupérer, le pousser, le suivre, le publier, le dupliquer, le peser. C’est la référence des commandes.

webcosa sitele site lui-même

Ce qui manque au site, ce qui y casse, son temps de réponse réel, un export local. Voir Le groupe site.

Note

La forme historique n’a pas bougé. node scripts/theme.mjs pousser marche exactement comme avant, et les deux chemins passent par le même code : le script est à la fois un module que webcosa importe et un programme qu’on peut lancer seul. La documentation emploie désormais webcosa theme partout, parce que c’est la forme qui ne demande pas de savoir où vit le dépôt.

#La boucle de travail

Cinq gestes, dont un seul se fait plusieurs fois par jour.

  1. Se connecter — une fois par machine

    Une clé d’API se crée dans le CMS, puis s’enregistre sur ta machine. Elle est vérifiée avant d’être écrite, et ne repart jamais dans un fichier versionné.

    webcosa theme connexion

    Le détail, les portées et la révocation : Connexion.

  2. Partir d’un thème

    Deux points de départ, selon qu’on part de zéro ou d’un site existant. nouveau copie un thème d’origine dans un dossier neuf — sans clé, sans réseau. recuperer écrit le thème d’un site sur le disque.

    webcosa theme nouveau --depuis=origo --nom="Atelier Rivière"✓ « Atelier Rivière » — 51 fichiers copiés depuis origo

    Dans les deux cas, un .webcosa.json est posé à la racine du dossier : à partir de là, les commandes suivantes n’ont plus besoin d’aucune option.

  3. Éditer, et pousser

    Deux façons, selon le moment. pousser envoie ce qui a changé, à la demande. suivre fait la même chose à chaque sauvegarde de fichier, avec l’heure.

    webcosa theme pousser ↑ modifié assets/theme.css + nouveau sections/temoignages.liquid ✓ 1 nouveau, 1 modifié, 22 inchangés

    Le thème sur lequel tu travailles est un brouillon : il ne remplace pas celui que voient les visiteurs. C’est ce qui rend cette étape sans danger.

  4. Publier

    Quand le brouillon te convient, il prend la place de l’ancien. La commande nomme le thème en ligne aujourd’hui et celui qui va le remplacer, puis demande confirmation.

    webcosa theme publier

  5. Regarder le site, une fois en ligne

    Le thème est parti, mais le site est autre chose que son thème. site verifier l’explore comme le ferait un visiteur et rapporte ce qui casse : liens internes morts, images en 404, pages sans titre, redirections en chaîne.

    webcosa site verifier Ce qui casse (1) • répond 500 https://dubois.webcosa.site/legal/mentions-legales cité par https://dubois.webcosa.site/

    Le groupe entier, et ce qu’il ne peut pas voir : Le groupe site.

#Ce qu’il fait exactement

Il compare des empreintes SHA-256 et n’envoie que ce qui a changé.

Le serveur expose l’empreinte de chaque fichier dans l’arborescence d’un thème. Deux appels suffisent donc à savoir quoi pousser, sans jamais télécharger le thème entier. Ce n’est pas une optimisation de confort : sans elle, chaque Cmd+S de suivre coûterait plusieurs centaines de kilo-octets pour un fichier modifié.

Note

La taille en octets ne pourrait pas jouer ce rôle. Corriger une faute de frappe, changer une couleur hexadécimale ou permuter deux lignes laisse le fichier exactement aussi long — un outil qui se fierait aux octets sauterait précisément les modifications qu’on fait le plus souvent.

#Pourquoi il ne rend pas de Liquid en local

C’est la première question qu’on se pose, et la réponse est non : il n’y a pas de serveur d’aperçu local, et il n’y en aura pas.

Un thème ne rend pas du Liquid dans le vide. Il rend le site de quelqu’un, avec ses pages, son menu, ses articles, ses réglages — des données qui vivent en base, derrière la RLS, et qui changent pendant qu’on édite. Un moteur local devrait donc soit recopier ces données (et afficher un site d’hier), soit les inventer (et afficher un site qui n’existe pas). Dans les deux cas, on déboguerait un rendu que personne ne verra jamais.

Et il y a pire : deux moteurs, ce sont deux comportements. Le jour où {% render %} ou un filtre maison diverge d’un demi-poil entre la machine du développeur et le serveur, l’écart devient un bug qui ne se reproduit que chez l’un des deux. Shopify a mis dix ans à construire un rendu local, puis à le remplacer par un rendu servi par la boutique elle-même. On part de l’endroit où ils sont arrivés.

Le rendu, la validation de syntaxe et les bornes du format restent donc sur le serveur, qui est le seul à connaître le site. L’aperçu, c’est le site lui-même.

Astuce

En pratique, la boucle courte est suivre dans un terminal et l’onglet du site brouillon à côté. Le rechargement est manuel, la poussée ne l’est pas : c’est suffisamment rapide pour qu’on n’y pense plus. Voir La boucle locale.

#Ce qu’il ne fait pas

Il ne fabrique pas de clés. connexion en enregistre une, il ne la crée pas. Créer une clé demande une session dans le CMS : une clé volée ne doit pas pouvoir s’en fabriquer d’autres et se perpétuer — sinon la révocation ne révoque plus rien.

Il n’envoie pas de .js. La liste des extensions est fermée, et c’est une mesure de sécurité, pas de rangement. Un fichier hors format est signalé et ignoré, jamais envoyé :

Sortie du CLIbash
! ignoré : assets/menu.js — extension non admise dans ce dossier

Il ne supprime rien par défaut. Les fichiers présents à distance mais absents en local sont signalés, pas effacés. Il faut --supprimer, qui les liste et demande confirmation avant d’agir.

Il n’écrit jamais ta clé dans le dossier du thème. .webcosa.json dit quel site et quel thème, rien de plus. La clé vit dans ~/.webcosa/config.json en 0600, ou dans une variable d’environnement pour l’intégration continue.

#La suite

InstallationLes prérequis, et la première mise en route en trois commandes.ConnexionObtenir une clé d'API depuis le CMS, l'enregistrer, et vérifier qu'elle répond.CommandesRéférence complète du groupe `theme` : `nouveau`, `recuperer`, `pousser`, `suivre`, `publier` et leurs options.Le groupe site`diagnostic`, `verifier`, `vitesse`, `sauvegarder` : ce qui manque au site et ce qui y casse.Configuration`.webcosa.json`, variables d'environnement, options de ligne de commande : l'ordre de priorité.ErreursChaque message d'erreur du CLI, ce qu'il signifie, et quoi faire.Créer son premier thèmeDu dossier vide à une page qui rend, pas à pas, avec les trois fichiers minimaux.