Aller au contenu

#Installation

Le CLI n’a aucune dépendance : il n’importe que des modules node:. Il n’y a donc rien à télécharger, et rien à tenir à jour séparément du dépôt.

Trois façons de l’appeler, et elles exécutent exactement le même code.

Le paquet webcosa est servi par la plateforme elle-même, catalogue de thèmes compris, et il est refait à chaque mise en ligne. C'est la forme à retenir hors du dépôt — sur le poste d'une partenaire, par exemple :

npm i -g https://dev.webcosa.com/cli/webcosa.tgzwebcosa connexion

Pour mettre à jour : la même commande.

Si l’une de ces commandes affiche l’aide, vous êtes prêt. Il reste à enregistrer une clé.

Note

Les deux formes ne divergeront pas. scripts/theme.mjs est à la fois un module que webcosa importe et un programme qu’on peut lancer seul : la séparation tient en une garde sur process.argv[1], et les commandes, les options et les messages sont les mêmes objets des deux côtés.

Le groupe site, lui, n’existe que sous webcosa — il n’a pas de forme historique à préserver.

#Prérequis

Node.js≥ 20.13requis

C’est le seul prérequis. Node 22 LTS ou 24 est le choix recommandé : c’est ce sur quoi le CLI est développé et vérifié.

Un éditeur de texteau choix

Aucune extension n’est nécessaire. La coloration Liquid de n’importe quel éditeur convient — le format est celui de Shopify, donc les greffons existants fonctionnent.

Vérifiez ce que vous avez :

node --versionv24.12.0
Note

D’où vient ce plancher de 20.13. Le dépôt ne fixe aucune version : il n’y a ni champ engines dans package.json, ni .nvmrc. Le plancher est donc celui des API que le script utilise réellement, et deux le fixent :

  • parseArgs de node:util, qui analyse la ligne de commande — stable depuis Node 20 ;
  • fs.watch en mode recursive, dont vit la commande suivre — disponible de longue date sur macOS et Windows, mais sur Linux seulement depuis 20.13.0. En dessous, suivre ne voit passer aucune sauvegarde sur une machine Linux, sans lever la moindre erreur. C’est exactement le genre de panne qu’on met une heure à comprendre.

Sur Node 18, fetch existe mais reste marqué expérimental et écrit un avertissement à chaque appel. Le CLI fonctionne, la sortie devient illisible.

#Où vit le code

Arborescence du dépôt
lyvora-cms/
├── scripts/
│   ├── webcosa.mjs             ← le point d'entrée, celui de `bin`
│   ├── theme.mjs               ← le groupe theme : module ET programme
│   └── lib/
│       ├── cli-noyau.mjs       ← affichage, saisie, configuration, appels
│       ├── site-commandes.mjs  ← le groupe site
│       ├── theme-controles.mjs ← les contrôles locaux de `verifier`
│       └── archive-zip.mjs     ← le .zip d'`empaqueter`
├── themes/                     ← les thèmes D'ORIGINE, pas un dossier de travail
│   ├── origo/
│   ├── forge/
│   └── vela/
└── src/

package.json déclare "bin": { "webcosa": "./scripts/webcosa.mjs" } : c’est ce que npm link installe.

webcosa theme lister
Danger

Le dossier themes/ à la racine du dépôt n’est pas un dossier de travail. Il contient les thèmes d’origine, compilés dans src/lib/liquid/catalogue.ts par scripts/compiler-themes.mjs, et proposés à l’installation à tous les sites. Un thème récupéré là finirait au catalogue sans que personne l’ait décidé.

Le CLI le détecte et vous avertit — mais il n’empêche rien :

bash
! /Users/marc/lyvora-cms/themes/atelier est sous le `themes/` du dépôt — celui
  des thèmes d'ORIGINE, compilé dans le catalogue. Préfère `--dossier=` ailleurs.

Travaillez ailleurs, avec --dossier=. Faire entrer un thème au catalogue est un geste délibéré, décrit dans Ajouter un thème au catalogue.

#L’utiliser hors du dépôt

Le CLI ne lit aucun fichier du produit, ne résout aucun alias @/ et n’a besoin de rien d’autre que Node. Il peut donc vivre ailleurs que dans le dépôt — mais il faut emporter le dossier scripts/ entier, pas un seul fichier : webcosa.mjs importe theme.mjs, qui importe lib/cli-noyau.mjs, lib/theme-controles.mjs et lib/archive-zip.mjs.

Le lien pointe sur le dépôt : une mise à jour de celui-ci met à jour la commande, sans rien recopier.

bash
cd lyvora-cms
npm link

cd ~/themes/atelier
webcosa theme pousser

npm unlink -g webcosa-cms défait le lien.

Attention

Une copie ne se met pas à jour toute seule — c’est la raison de préférer npm link. Le CLI recopie une partie du format des thèmes (les six dossiers, les extensions admises, TAILLE_MAX, FICHIERS_MAX) parce qu’il tourne hors de Next et ne peut pas lire un module TypeScript. La divergence est sans danger : le serveur revalide tout ce qu’il reçoit, donc au pire une copie vieillie enverra un fichier que le serveur refusera avec son propre message. Mais elle ne vous évitera plus l’aller-retour réseau, ce qui est justement sa raison d’être.

Une copie perd aussi webcosa theme nouveau, qui lit les thèmes d’origine dans le themes/ du dépôt — à moins d’emporter ce dossier-là aussi.

#Un dossier de thème, de zéro

Trois façons de commencer, de la plus rapide à la plus nue.

La plus rapide, et celle qui ne demande ni clé ni réseau : un thème d’origine est copié dans un dossier neuf, avec son .webcosa.json déjà posé.

bash
webcosa theme nouveau                                    # la liste des thèmes d'origine
webcosa theme nouveau --depuis=origo --nom="Mon thème"

Le dossier obtenu est complet et fonctionnel : webcosa theme verifier passe dessus sans rien signaler, et webcosa theme pousser --nouveau le crée sur le site, en brouillon.

Note

nouveau lit les thèmes d’origine sur le disque, dans le themes/ du dépôt : elle ne fonctionne donc que dans le dépôt ou dans une installation faite par npm link. Aucune route d’API ne sert le contenu des thèmes du catalogue — elle les installe sur un site, elle ne les rend pas.

#Vérifier que tout répond

  1. L’aide s’affiche

    webcosa aide

    Si vous obtenez command not found: webcosa, c’est que npm link n’a pas été fait — node scripts/webcosa.mjs aide marche sans lui.

  2. La clé est enregistrée

    webcosa theme connexion

    La commande vérifie la clé avant de l’écrire : si elle affiche le nom de votre site, l’authentification fonctionne de bout en bout.

  3. Le site répond

    webcosa theme lister id nom version rôle modifié 11111111 Origo 1.0.0 publié il y a 3 min 22222222 Chantier 2.1.0 brouillon il y a 4 j

    Une liste vide n’est pas une panne : c’est un site sans thème. Pars d’un thème d’origine avec webcosa theme nouveau, ou installez-en un depuis le CMS.

Astuce

--verbeux détaille chaque appel HTTP — méthode, adresse, site visé, présence de la clé. C’est la première chose à ajouter quand une commande ne fait pas ce qu’on croyait :

bash
webcosa theme lister --verbeux

Si une commande échoue, la page des erreurs reprend chaque message avec sa cause et le geste à faire.