CLI e distribuzione della configurazione

Gli artefatti CLI/config pubblicati nella versione 0.3.1 implementano il contratto di configurazione/backend 0.3.0 e rifiutano le chiavi sconosciute sia in locale sia nel backend.

La CLI crea, convalida, distribuisce, promuove ed esegue il rollback di versioni immutabili della configurazione ChattyBox. I token di deployment sono limitati a un singolo progetto e agli ambienti selezionati, quindi lo stesso flusso è adatto allo sviluppo locale e alla CI.

Stato di release e runtime

Il registro pubblico offre @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 e l’SDK JavaScript @openstaticfish/chattybox@0.1.4. Questi artefatti supportano i campi ampliati insieme al contratto backend 0.3.0; status mostra la versione dell’ambiente, mentre runtimeConfigVersionId identifica l’ultima configurazione applicata al runtime condiviso e può differire. Se mode è omesso, viene scelto crawl e un maxDepth: 0 esplicito resta invariato. schemaVersion: "1" è un sistema di versione distinto.

Creare una configurazione

bunx @openstaticfish/chattybox-cli init

Questo comando crea chattybox.config.json:

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

Utilizza un percorso personalizzato quando la configurazione deve trovarsi in una sottodirectory:

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

Convalidare in locale o nella CI

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

La convalida verifica lo schema, il nome obbligatorio dell'assistente, i tipi di fonti supportati, gli URL HTTP delle fonti, i limiti di pagina positivi e i colori del widget. Una convalida riuscita non esegue il deployment e non modifica lo stato remoto.

Creare un token di deployment

Apri la scheda Settings del progetto, cerca Config deployment tokens e crea un token per gli ambienti che il tuo flusso di lavoro può modificare. Copialo subito: ChattyBox memorizza solo il suo hash e non può mostrarlo nuovamente.

Imposta il token e l'URL API del widget dalla scheda Embed del progetto:

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

Non eseguire mai il commit del token. Conservalo nel gestore di secret crittografati del tuo provider CI.

Config-as-code lock è irreversibile: non esiste unlock da dashboard, CLI o API. Blocca configurazione, upload icone e operazioni manuali sul corpus; token e chiavi pubbliche restano gestibili. Branding è l’eccezione, soggetta al piano.

Distribuire la configurazione

Il deployment crea una versione immutabile e la promuove nell'ambiente selezionato:

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

development registra soltanto una versione. preview e production condividono runtime, corpus e chiavi: l’ultima promozione vince; usa progetti separati per isolamento. L’applicazione accoda scrape/embedding ma non li attende, non crea snapshot del corpus e un fallimento non annulla la configurazione.

Usa --json nelle automazioni per ricevere versione, ambiente, stato dell'applicazione e ID del job di scraping in un output strutturato.

Stato, promozione e rollback

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 usa l’ID opaco, non il numero visibile. Il rollback riapplica con entitlement attuali e non ripristina un contenuto storico esatto.

Workflow CI/CD

Aggiungi CHATTYBOX_DEPLOY_TOKEN come secret crittografato con ambito production nel tuo provider CI. Aggiungi CHATTYBOX_API_URL come secret o variabile usando l'URL API del widget dalla scheda Embed del progetto. Esegui la validazione sulle pull request, ma limita il deployment in produzione al branch predefinito protetto o a un ambiente di deployment approvato.

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

Usa un secret di produzione con ambito limitato all'ambiente e richiedi l'approvazione del deployment quando il tuo repository lo supporta. La CLI registra le variabili CI comuni relative al commit e al branch insieme alla versione immutabile.

GitLab CI/CD

Archivia entrambi i valori in Settings → CI/CD → Variables. Proteggi il token di deployment, mascheralo e limita il suo ambito all'ambiente 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 espone automaticamente al job CHATTYBOX_DEPLOY_TOKEN e CHATTYBOX_API_URL usando i rispettivi nomi di variabile. Usa un branch predefinito protetto, in modo che le variabili protette non siano disponibili per branch non attendibili.

Bitbucket Pipelines

Aggiungi entrambi i valori come variabili di deployment in Repository settings → Pipelines → Deployments → Production. Contrassegna il token di deployment come protetto.

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

Sostituisci main se il tuo branch predefinito ha un altro nome. Bitbucket inserisce le variabili di deployment solo nei passaggi associati a quell'ambiente di deployment.

Sezioni di configurazione

Sezione	Scopo
schemaVersion	Seleziona il contratto pubblico di configurazione. Attualmente è supportata la versione 1.
assistant	Assegna un nome all'assistente e, facoltativamente, ne definisce il profilo delle istruzioni e l'istruzione di sistema.
knowledge.sources	Dichiara le fonti dei siti web ed eventuali pattern di inclusione o esclusione.
runtime	Contiene i valori predefiniti di runtime, come le impostazioni locali.
widget	Descrive le impostazioni facoltative di presentazione del widget ospitato.

Funzione di supporto per la configurazione tipizzata

Installa il pacchetto di configurazione se crei strumenti TypeScript separati basati sullo schema:

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 legge direttamente file JSON. defineConfig() è destinata ad applicazioni tipizzate o strumenti di build; non rende i file TypeScript direttamente caricabili dalla CLI.

Per un'integrazione funzionante in produzione oggi, utilizza il widget ospitato oppure crea un'interfaccia personalizzata con l'SDK JavaScript.