CLI

Le CLI SitePing automatise l'installation du projet et les vérifications de santé. Il est livré comme un binaire autonome unique, avec zéro dépendance à l'exécution, et exige Node 20 ou plus récent.

npx @siteping/cli --help

Le nom du package compte. Lancez toujours npx @siteping/cli <commande>. Il n'existe pas de package siteping sur npm : npx siteping ne fonctionne que si @siteping/cli est déjà installé dans votre projet.

init — installation interactive

npx @siteping/cli init

init vous guide à travers deux confirmations :

1. Synchroniser les modèles Prisma — si un schéma est trouvé (voir détection du schéma), il propose d'ajouter les modèles SitePing : SitepingFeedback, SitepingAnnotation et SitepingComment (les fils de discussion).
2. Générer la route API — propose de créer une route Next.js App Router qui sert le widget. Le fichier va dans app/api/siteping/route.ts, ou src/app/api/siteping/route.ts si votre projet utilise une arborescence src/. Si app/ et src/app/ existent tous les deux, app/ l'emporte — Next.js ignore alors lui-même src/app/. Une route existante — route.ts, .tsx, .js ou .jsx — n'est jamais écrasée.

La route générée importe deux choses que vous devez fournir vous-même — le CLI n'installe rien :

• le package @siteping/adapter-prisma (npm i @siteping/adapter-prisma)
• un client Prisma exporté depuis @/lib/prisma

Si votre projet n'a pas de répertoire app/ (ni src/app/), init se termine en erreur : il ne génère que des routes Next.js App Router. Les autres frameworks branchent l'adapter manuellement — voir Adapters.

init est interactif par conception et ne fait rien en CI (il se termine silencieusement sans terminal). Pour l'automatisation, utilisez sync.

sync — fusion de schéma non interactive

npx @siteping/cli sync
npx @siteping/cli sync --schema prisma/schema.prisma

sync fusionne les modèles SitePing dans votre schéma Prisma sans poser de question, ce qui le rend sûr pour la CI et les scripts de mise à jour. Il travaille au niveau de l'AST :

• crée les modèles SitePing absents — dans le schéma de base de données des modèles SitePing existants (leur @@schema) quand votre datasource en déclare plusieurs (schemas),
• ajoute les champs et blocs @@index manquants,
• réécrit les champs SitePing dont le type ou les attributs ont dérivé de la forme attendue — en gardant ce qui vous appartient (noms de colonne @map, noms de relation, onUpdate d'une relation, commentaires) ; un @ignore compte comme une dérive, car l'adapter écrit toutes les colonnes SitePing,
• ne touche jamais aux champs que vous avez ajoutés vous-même.

Quand quelque chose a changé, il vous rappelle de lancer npx prisma db push et npx prisma generate (Prisma 7 ne génère plus le client depuis db push). Un schéma existant reçoit ainsi SitepingComment et la relation SitepingFeedback.comments : appliquez-les avant de déployer — voir les fils de discussion avec Prisma. Le lancer deux fois de suite ne fait rien.

Committez avant de le lancer. sync réimprime tout le fichier de schéma, donc le formatage (lignes vides après les commentaires //, alignement des colonnes) est normalisé y compris sur vos propres modèles — les commentaires de documentation /// restent attachés à ce qu'ils documentent. Un diff git propre rend les changements faciles à relire.

status — rapport de santé du projet

npx @siteping/cli status
npx @siteping/cli status --schema prisma/schema.prisma

status lance quatre vérifications et imprime un rapport :

La vérification de la route API ne connaît que l'App Router de Next.js. Si vous servez l'adapter depuis Express, Hono ou le Pages Router, cette ligne affichera « Not found » alors même que votre installation fonctionne.

doctor — vérification de l'endpoint en direct

npx @siteping/cli doctor --url http://localhost:3000 --endpoint /api/siteping
npx @siteping/cli doctor --url https://app.example.com --api-key "$SITEPING_API_KEY"

doctor envoie une requête GET à votre serveur en fonctionnement et vous dit si un handler SitePing a répondu (timeout de 10 secondes). Passez à la fois --url et --endpoint pour l'exécuter sans interaction — celle que vous omettez devient une question. Quand l'endpoint est configuré avec un apiKey et que GET n'est pas public, passez la clé avec --api-key ; sans elle, un 401 s'accompagne d'une indication.

--url est l'URL de base de votre site, pas celle de l'endpoint : un chemin qu'elle contient (un basePath Next.js, par exemple) se place devant --endpoint. Avec --url https://example.com/app --endpoint /api/siteping, doctor interroge https://example.com/app/api/siteping.

Il ne vérifie que la réponse HTTP — il ne lit jamais votre schéma. Pour vérifier le schéma, utilisez status.

Codes de sortie

Toutes les commandes sont scriptables. 0 signifie succès, 1 que quelque chose doit être corrigé :

Deux réserves pour les pipelines CI : status sort en 0 (avec une indication de lancer sync) quand les champs du schéma ont simplement dérivé, et doctor sort en 0 sur toute réponse 200 — y compris une qui ne vient pas d'un handler SitePing (il affiche un avertissement à la place). Ni l'un ni l'autre n'est un garde-fou strict.

Détection du schéma

Quand vous ne passez pas --schema, le CLI teste trois emplacements dans l'ordre :

1. prisma/schema.prisma
2. schema.prisma
3. prisma/schema/schema.prisma

Un fichier de schéma situé dans un dossier schema/ (comme prisma/schema/schema.prisma) est traité comme une partie d'un schéma multi-fichiers, comme le fait Prisma : chaque fichier .prisma de ce dossier et de ses sous-dossiers compte, sauf sous node_modules et dans les dossiers cachés. Les modèles SitePing sont trouvés et mis à jour dans le fichier qui les contient ; ceux qui manquent sont ajoutés au fichier indiqué. Un dossier qui contient un package.json est la racine d'un projet, jamais un dossier de schéma, même s'il s'appelle schema. Un dossier de schéma multi-fichiers portant un autre nom n'est pas détecté : le CLI ne voit alors que le fichier que vous lui indiquez.