CLI e implantação de configurações

Os artefatos CLI/config publicados na versão 0.3.1 implementam o contrato de configuração/backend 0.3.0 e rejeitam chaves desconhecidas tanto localmente como no backend.

Estado de release e runtime

Os artefatos publicados são @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 e o SDK JavaScript @openstaticfish/chattybox@0.1.4. Eles suportam os campos ampliados junto com o contrato do backend 0.3.0; status mostra a versão do ambiente, enquanto runtimeConfigVersionId é a última configuração aplicada ao runtime partilhado e pode diferir. Omitir mode escolhe crawl e preserva maxDepth: 0 explícito. development só regista uma versão; preview e produção partilham runtime, corpus e chaves. O último deploy vence; use projetos separados para isolamento.

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

development apenas registra uma versão/ponteiro (applied: false, indexingStatus: "not_required"). preview e production substituem as definições de runtime do mesmo projeto e usam o mesmo corpus e as mesmas chaves públicas do widget; a promoção de runtime mais recente prevalece. Use projetos separados para isolamento real. Ambos aplicam a configuração atomicamente e enfileiram um trabalho de scraping (applied: true, indexingStatus: "pending"), mas não esperam pelo scraping nem pelos embeddings. O corpus não é um snapshot versionado e uma atualização falhada não reverte a configuração aplicada.

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

--version usa o ID opaco da versão de configuração, não o número visível. A reversão usa a mesma operação de backend que a promoção, não precisa de visar uma versão anterior e substitui o ponteiro e os metadados de promoção do ambiente selecionado; não existe histórico de promoções append-only. Para preview ou production, reaplica a configuração com os direitos atuais e enfileira uma nova atualização, em vez de restaurar o corpus histórico.

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

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

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

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.