CLI

Le CLI InstaFix 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.

InstaFix n'est pas publié sur le registre npm — c'est un choix délibéré, donc npx @instafix/cli ne se résoudra pas. Lancez-le directement depuis la branche cli-dist de ce dépôt :

npx github:gnoopy/instafix#cli-dist --help

La commande complète compte. Lancez toujours npx github:gnoopy/instafix#cli-dist <commande> — en entier, à chaque fois. Il n'existe pas de package instafix sur npm pour la raccourcir.

init — installation interactive

npx github:gnoopy/instafix#cli-dist init

init vous guide à travers jusqu'à quatre 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 InstaFixFeedback et InstaFixAnnotation.
2. Pousser le schéma — si un schéma a été trouvé, il propose d'exécuter npx prisma db push immédiatement, en relayant directement dans votre terminal la sortie de Prisma (et toute confirmation qu'il demande).
3. 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/instafix/route.ts, ou src/app/api/instafix/route.ts si votre projet utilise une arborescence src/. Une route existante n'est jamais écrasée.
   • Un schéma a été trouvé : génère une route basée sur @instafix/adapter-prisma.
   • Aucun schéma trouvé : demande plutôt quel backend utiliser — SQLite (@instafix/adapter-sqlite, zéro service externe) ou passer et brancher le stockage vous-même. init ne suppose plus Prisma en l'absence de schéma Prisma à synchroniser.
4. Générer le composant du widget — propose de créer un composant "use client" dans components/instafix-widget.tsx (ou src/components/... avec une arborescence src/) qui appelle initInstaFix() pour vous, en utilisant le nom de votre package.json comme projectName. Un composant existant n'est jamais écrasé.

La route au format Prisma importe deux choses que vous devez fournir vous-même — le CLI n'installe rien :

• le package @instafix/adapter-prisma (npm install github:gnoopy/instafix#adapter-prisma-dist)
• un client Prisma exporté depuis @/lib/prisma

La route au format SQLite n'a besoin que de @instafix/adapter-sqlite installé (npm install github:gnoopy/instafix#adapter-sqlite-dist) — aucun client à brancher, aucun schéma à pousser ; voir l'adapter SQLite.

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.

Tout ce qui n'a pas été fait automatiquement — refusé, ou schéma/route non détecté — est listé dans une note Prochaines étapes à la fin, pour que rien ne soit oublié en silence.

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 github:gnoopy/instafix#cli-dist sync
npx github:gnoopy/instafix#cli-dist sync --schema prisma/schema.prisma

sync fusionne les modèles InstaFix 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 deux modèles s'ils sont absents,
• ajoute les champs et blocs @@index manquants,
• réécrit les champs InstaFix dont le type ou les attributs ont dérivé de la forme attendue,
• 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. 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. Un diff git propre rend les changements faciles à relire.

status — rapport de santé du projet

npx github:gnoopy/instafix#cli-dist status
npx github:gnoopy/instafix#cli-dist 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 github:gnoopy/instafix#cli-dist doctor --url http://localhost:3000 --endpoint /api/instafix

doctor envoie une requête GET à votre serveur en fonctionnement et vous dit si un handler InstaFix a répondu (timeout de 10 secondes). Passez les deux options pour l'exécuter sans interaction — toute option omise devient une question.

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 InstaFix (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