CLI et déploiement de configuration

Les artefacts CLI/config publiés en version 0.3.1 implémentent le contrat de configuration/backend 0.3.0 et rejettent les clés inconnues aussi bien localement que côté backend.

La CLI crée, valide, déploie, promeut et restaure des versions immuables de la configuration ChattyBox. Les jetons de déploiement sont limités à un projet et aux environnements sélectionnés, ce qui rend le même flux adapté au développement local et à la CI.

État de publication et d’exécution

Le registre public publie @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 et le SDK JavaScript distinct @openstaticfish/chattybox@0.1.4. Les commandes de base et les champs étendus (projet, découverte/planification, locales étendues, widget.icon, widget.showBranding) sont pris en charge par ces artefacts et le contrat backend 0.3.0. La CLI est ESM et demande Node 20+ ; utilisez bunx --bun explicitement si vous choisissez Bun.

Créer une configuration

bunx @openstaticfish/chattybox-cli init

Cette commande crée chattybox.config.json :

{
  "schemaVersion": "1",
  "assistant": {
    "name": "Support"
  },
  "knowledge": {
    "sources": [
      {
        "type": "website",
        "url": "https://example.com"
      }
    ]
  },
  "widget": {
    "enabled": true
  }
}

Utilisez un chemin personnalisé lorsque la configuration doit se trouver dans un sous-répertoire :

bunx @openstaticfish/chattybox-cli init config/chattybox.config.json

Valider localement ou dans la CI

bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json

La validation du contrat 0.3.0 partagé avec le backend rejette les clés inconnues, vérifie le schéma, le nom obligatoire de l'assistant, les types de sources pris en charge, les URL HTTP des sources, les limites de pages positives et les couleurs du widget. Une validation réussie ne déploie ni ne modifie aucun état distant. Si mode est omis, crawl est sélectionné et un maxDepth: 0 explicite est conservé.

Créer un jeton de déploiement

Ouvrez l'onglet Settings du projet, recherchez Config deployment tokens et créez un jeton pour les environnements que votre flux de travail peut modifier. Copiez-le immédiatement ; ChattyBox ne stocke que son hash et ne peut plus l'afficher.

Définissez le jeton et l'URL d'API du widget depuis l'onglet Embed du projet :

export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'

Ne commitez jamais le jeton. Stockez-le dans le gestionnaire de secrets chiffrés de votre fournisseur CI.

Après avoir vérifié le flux, activez éventuellement Config-as-code lock. Il est irréversible dans le tableau de bord, la CLI et l’API actuels. Il bloque les écritures de configuration et les opérations manuelles de corpus depuis le dashboard (scraping, suppression, reconstruction), mais pas les opérations planifiées, la suppression du projet, les clés publiques ou les jetons. Le branding est l’exception : le réglage de branding reste modifiable, selon la formule.

Déployer la configuration

Le déploiement crée une version immuable et la promeut dans l'environnement sélectionné :

bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production

development enregistre seulement une version/pointeur, sans l’appliquer. preview et production partagent le même runtime, corpus et clés publiques : la dernière promotion gagne, sans isolation par environnement. Utilisez des projets et jetons distincts pour une vraie séparation. Une promotion runtime applique la configuration et met un scraping en file, sans attendre scraping ni embeddings. Elle ne supprime pas les anciennes URL omises et le corpus n’est pas un instantané versionné ; une mise à jour partielle peut subsister après échec.

Utilisez --json dans les automatisations pour recevoir la version, l'environnement, l'état de l'application et l'ID du job de scraping sous forme structurée.

État, promotion et restauration

bunx @openstaticfish/chattybox-cli status --environment production

bunx @openstaticfish/chattybox-cli promote \
  --version '<config-version-id>' \
  --environment production

bunx @openstaticfish/chattybox-cli rollback \
  --version '<known-good-config-version-id>' \
  --environment production

--version attend l'identifiant opaque de version de configuration, et non le numéro affiché. status montre la version de l’environnement sélectionné, tandis que runtimeConfigVersionId désigne la dernière configuration appliquée au runtime partagé : ils peuvent différer après la promotion d’un autre environnement. La restauration utilise la même opération backend que la promotion, ne doit pas cibler une version antérieure et écrase le pointeur ainsi que les métadonnées de promotion de l'environnement sélectionné ; il n'existe pas d'historique de promotions append-only. Pour preview ou production, elle réapplique la configuration avec les droits actuels et met une nouvelle actualisation en file, plutôt que de restaurer le contenu historique.

Workflows CI/CD

Ajoutez CHATTYBOX_DEPLOY_TOKEN en tant que secret chiffré limité à la production chez votre fournisseur CI. Ajoutez CHATTYBOX_API_URL comme secret ou variable en utilisant l'URL d'API du widget de l'onglet Embed du projet. Exécutez la validation sur les pull requests, mais limitez le déploiement en production à votre branche par défaut protégée ou à un environnement de déploiement approuvé.

GitHub Actions

name: Deploy ChattyBox configuration

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - run: bunx @openstaticfish/chattybox-cli validate

  deploy:
    if: github.event_name == 'push'
    needs: validate
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - name: Validate and deploy
        env:
          CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
          CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
        run: |
          bunx @openstaticfish/chattybox-cli validate
          bunx @openstaticfish/chattybox-cli deploy --environment production --json

Utilisez un secret de production limité à l'environnement et exigez une approbation de déploiement lorsque votre dépôt le permet. La CLI enregistre les variables CI courantes du commit et de la branche avec la version immuable.

GitLab CI/CD

Stockez les deux valeurs sous Settings → CI/CD → Variables. Protégez le token de déploiement, masquez-le et limitez sa portée à l'environnement production.

.gitlab-ci.yml

image: oven/bun:1

validate_chattybox:
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - bunx --bun @openstaticfish/chattybox-cli validate

deploy_chattybox:
  stage: deploy
  environment: production
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - bunx --bun @openstaticfish/chattybox-cli validate
    - bunx --bun @openstaticfish/chattybox-cli deploy --environment production --json

GitLab expose automatiquement CHATTYBOX_DEPLOY_TOKEN et CHATTYBOX_API_URL au job en utilisant leurs noms de variables. Utilisez une branche par défaut protégée afin que les variables protégées ne soient pas disponibles pour les branches non fiables.

Bitbucket Pipelines

Ajoutez les deux valeurs en tant que variables de déploiement sous Repository settings → Pipelines → Deployments → Production. Marquez le token de déploiement comme sécurisé.

bitbucket-pipelines.yml

image: oven/bun:1

pipelines:
  pull-requests:
    '**':
      - step:
          name: Validate ChattyBox configuration
          script:
            - bunx --bun @openstaticfish/chattybox-cli validate
  branches:
    main:
      - step:
          name: Deploy ChattyBox configuration
          deployment: Production
          script:
            - bunx --bun @openstaticfish/chattybox-cli validate
            - bunx --bun @openstaticfish/chattybox-cli deploy --environment production --json

Remplacez main si votre branche par défaut porte un autre nom. Bitbucket injecte les variables de déploiement uniquement dans les étapes associées à cet environnement de déploiement.

Sections de configuration

Section	Objectif
schemaVersion	Sélectionne le contrat de configuration public. La version 1 est actuellement prise en charge.
assistant	Nomme l'assistant et définit facultativement son profil de prompt et son prompt système.
knowledge.sources	Déclare les sources de sites web et les modèles facultatifs d'inclusion ou d'exclusion.
runtime	Contient les valeurs par défaut d'exécution, telles que la locale.
widget	Décrit les paramètres de présentation facultatifs du widget hébergé.

Utilitaire de configuration typé

Installez le package de configuration pour créer des outils TypeScript distincts autour du schéma :

bun add -d @openstaticfish/chattybox-config

import { defineConfig } from '@openstaticfish/chattybox-config';

const config = defineConfig({
  schemaVersion: '1',
  assistant: { name: 'Support' },
  knowledge: {
    sources: [{ type: 'website', url: 'https://docs.example.com' }],
  },
  widget: { enabled: true },
});

La CLI elle-même lit des fichiers JSON. defineConfig() est destiné aux applications typées ou aux outils de build ; il ne permet pas à la CLI de charger directement des fichiers TypeScript.

Pour une intégration fonctionnelle en production dès aujourd'hui, utilisez le widget hébergé ou créez une interface personnalisée avec le SDK JavaScript.