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.

GitHub Actions

- name: Deploy ChattyBox configuration
  env:
    CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
    CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
  run: 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.

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.