CLI e implantação de configurações

A CLI cria, valida, implanta, promove e reverte versões imutáveis da configuração do ChattyBox. Os tokens de implantação são vinculados a um único projeto e aos ambientes selecionados, tornando o mesmo fluxo adequado para desenvolvimento local e CI.

Criar uma configuração

bunx @openstaticfish/chattybox-cli init

Esse comando cria chattybox.config.json:

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

Use um caminho personalizado quando a configuração pertencer a um subdiretório:

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

Validar localmente ou na CI

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

A validação verifica o esquema, o nome obrigatório do assistente, os tipos de origem compatíveis, as URLs HTTP das origens, os limites positivos de páginas e as cores do widget. Uma validação bem-sucedida não implanta nem modifica o estado remoto.

Criar um token de implantação

Abra a guia Settings do projeto, encontre Config deployment tokens e crie um token para os ambientes que seu fluxo de trabalho poderá alterar. Copie-o imediatamente; o ChattyBox armazena apenas o hash e não pode exibi-lo novamente.

Defina o token e a URL da API do widget na guia Embed do projeto:

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

Nunca faça commit do token. Armazene-o no armazenamento criptografado de secrets do seu provedor de CI.

Após verificar o fluxo de implantação, ative o Config-as-code lock na mesma seção de configurações. O bloqueio desativa alterações de configuração e do corpus pelo dashboard, de modo que apenas tokens de implantação com o escopo adequado possam alterar o runtime. A criação e a revogação de tokens continuam disponíveis caso seja necessário fazer a rotação de uma credencial de CI.

Implantar a configuração

A implantação cria uma versão imutável e a promove ao ambiente selecionado:

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

As promoções de desenvolvimento e de pré-visualização são registradas para revisão. As promoções de produção aplicam atomicamente o prompt do assistente, a resposta de fallback, as configurações do widget, a localidade e a fonte do site ao projeto ativo. A configuração de produção deve conter exatamente uma fonte de site. Uma implantação enfileira um scraping vinculado à versão para execução após a conclusão dos jobs anteriores; depois, substitui o corpus antigo e regenera os embeddings. O runtime atual rejeita configurações com várias fontes.

Use --json na automação para receber a versão, o ambiente, o status da aplicação e o ID do job de scraping como saída estruturada.

Status, promoção e reversão

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

A reversão promove e reaplica uma versão imutável anterior; ela nunca reescreve o histórico de implantações. A configuração é restaurada imediatamente, enquanto qualquer atualização de conteúdo necessária continua de forma assíncrona.

Fluxos de trabalho de CI/CD

Adicione CHATTYBOX_DEPLOY_TOKEN como um secret criptografado com escopo de produção no provedor de CI. Adicione CHATTYBOX_API_URL como um secret ou variável usando a URL da API do widget na aba Embed do projeto. Execute a validação em pull requests, mas restrinja a implantação de produção à branch padrão protegida ou a um ambiente de implantação aprovado.

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

Use um secret de produção vinculado ao ambiente e exija aprovação para a implantação quando o seu repositório oferecer suporte a isso. A CLI registra as variáveis comuns de commit e branch da CI junto à versão imutável.

GitLab CI/CD

Armazene os dois valores em Settings → CI/CD → Variables. Proteja o token de implantação, mascare-o e limite-o ao ambiente production.

.gitlab-ci.yml

image: oven/bun:1

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

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

O GitLab expõe automaticamente CHATTYBOX_DEPLOY_TOKEN e CHATTYBOX_API_URL ao job usando os nomes das variáveis. Use uma branch padrão protegida para que as variáveis protegidas não fiquem disponíveis para branches não confiáveis.

Bitbucket Pipelines

Adicione os dois valores como variáveis de implantação em Repository settings → Pipelines → Deployments → Production. Marque o token de implantação como protegido.

bitbucket-pipelines.yml

image: oven/bun:1

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

Substitua main se sua branch padrão tiver outro nome. O Bitbucket injeta variáveis de implantação somente nas etapas associadas a esse ambiente de implantação.

Seções da configuração

Seção	Finalidade
schemaVersion	Seleciona o contrato público de configuração. Atualmente, há suporte para a versão 1.
assistant	Define o nome do assistente e, opcionalmente, seu perfil de prompt e prompt do sistema.
knowledge.sources	Declara origens de sites e padrões opcionais de inclusão e exclusão.
runtime	Contém padrões de execução, como a localidade.
widget	Descreve configurações opcionais de apresentação do widget hospedado.

Auxiliar de configuração tipada

Instale o pacote de configuração ao criar ferramentas TypeScript separadas em torno do esquema:

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 },
});

A própria CLI lê arquivos JSON. defineConfig() serve para aplicativos tipados ou ferramentas de build; ela não permite que arquivos TypeScript sejam carregados diretamente pela CLI.

Para uma integração funcional em produção hoje, use o widget hospedado ou crie uma interface personalizada com o SDK JavaScript.