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. Il n’y a rien d’autre à apprendre : six commandes, aucune dépendance, un seul fichier de script.

Le script vit dans le dépôt, à scripts/theme.mjs. Il s’appelle avec Node, sans installation :

node scripts/theme.mjs aide

#La boucle de travail

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

    node scripts/theme.mjs connexion

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

  2. Récupérer le thème

    Le thème distant arrive sur le disque, et un .webcosa.json est posé à la racine du dossier. À partir de là, les commandes suivantes n’ont plus besoin d’aucune option.

    node scripts/theme.mjs recuperer --dossier=~/themes/origo ✓ 24 fichiers de « Origo » écrits dans /Users/marc/themes/origo

  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.

    node scripts/theme.mjs 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.

    node scripts/theme.mjs publier

#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 : `lister`, `recuperer`, `pousser`, `suivre`, `publier` et leurs options.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.