CLI y despliegue de configuración

La CLI crea, valida, despliega, promociona y revierte versiones inmutables de la configuración de ChattyBox. Los tokens de despliegue están limitados a un proyecto y a los entornos seleccionados, por lo que el mismo flujo sirve para el desarrollo local y CI.

Crear una configuración

bunx @openstaticfish/chattybox-cli init

Esto crea chattybox.config.json:

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

Utiliza una ruta personalizada si la configuración debe estar en un subdirectorio:

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

Validar localmente o en CI

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

La validación comprueba el esquema, el nombre obligatorio del asistente, los tipos de fuentes admitidos, las URL HTTP de las fuentes, los límites de páginas positivos y los colores del widget. Una validación correcta no despliega ni modifica el estado remoto.

Crear un token de despliegue

Abre la pestaña Settings del proyecto, busca Config deployment tokens y crea un token para los entornos que tu flujo de trabajo pueda modificar. Cópialo inmediatamente; ChattyBox solo almacena su hash y no puede volver a mostrarlo.

Establece el token y la URL de la API del widget desde la pestaña Embed del proyecto:

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

No hagas commit del token. Guárdalo en el almacén de secretos cifrados de tu proveedor de CI.

Después de verificar el flujo de despliegue, activa Config-as-code lock en la misma sección de ajustes. El bloqueo desactiva los cambios de configuración y del corpus desde el dashboard, de modo que solo los tokens de despliegue con el alcance correspondiente puedan modificar el runtime. La creación y revocación de tokens sigue disponible si es necesario rotar una credencial de CI.

Desplegar la configuración

El despliegue crea una versión inmutable y la promociona al entorno seleccionado:

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

Las promociones a development y preview se registran para su revisión. Las promociones a production aplican atómicamente el prompt del asistente, la respuesta alternativa, los ajustes del widget, la configuración regional y la fuente del sitio web al proyecto activo. La configuración de producción debe contener exactamente una fuente de sitio web. Un despliegue pone en cola un scraping vinculado a la versión para ejecutarlo después de que terminen los trabajos anteriores. Después, el despliegue sustituye el corpus anterior y regenera los embeddings. El runtime actual rechaza las configuraciones con varias fuentes.

Usa --json en las automatizaciones para recibir la versión, el entorno, el estado de la aplicación y el ID del trabajo de scraping como salida estructurada.

Estado, promoción y reversión

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

La reversión promociona y vuelve a aplicar una versión inmutable anterior; nunca reescribe el historial de despliegues. Restaura la configuración de inmediato, mientras que cualquier actualización de contenido necesaria continúa de forma asíncrona.

Flujos de trabajo de CI/CD

Añade CHATTYBOX_DEPLOY_TOKEN como secreto cifrado con alcance de producción en tu proveedor de CI. Añade CHATTYBOX_API_URL como secreto o variable usando la URL de la API del widget de la pestaña Embed del proyecto. Ejecuta la validación en los pull requests, pero restringe el despliegue de producción a tu rama predeterminada protegida o a un entorno de despliegue aprobado.

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

Usa un secreto de producción limitado al entorno y exige aprobación para el despliegue cuando tu repositorio lo admita. La CLI registra las variables habituales de CI relacionadas con el commit y la rama junto con la versión inmutable.

GitLab CI/CD

Guarda ambos valores en Settings → CI/CD → Variables. Protege el token de despliegue, enmascáralo y limita su alcance al entorno 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

GitLab expone automáticamente CHATTYBOX_DEPLOY_TOKEN y CHATTYBOX_API_URL al trabajo usando sus nombres de variable. Usa una rama predeterminada protegida para que las variables protegidas no estén disponibles para ramas que no sean de confianza.

Bitbucket Pipelines

Añade ambos valores como variables de despliegue en Repository settings → Pipelines → Deployments → Production. Marca el token de despliegue 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

Sustituye main si tu rama predeterminada tiene otro nombre. Bitbucket inyecta las variables de despliegue únicamente en los pasos asociados a ese entorno de despliegue.

Secciones de configuración

Sección	Finalidad
schemaVersion	Selecciona el contrato público de configuración. Actualmente se admite la versión 1.
assistant	Asigna un nombre al asistente y, de forma opcional, define su perfil de instrucciones y su instrucción del sistema.
knowledge.sources	Declara fuentes de sitios web y patrones opcionales de inclusión o exclusión.
runtime	Contiene valores predeterminados de ejecución, como la configuración regional.
widget	Describe ajustes opcionales de presentación del widget alojado.

Función auxiliar de configuración tipada

Instala el paquete de configuración si vas a crear herramientas TypeScript independientes basadas en el 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 },
});

La propia CLI lee archivos JSON. defineConfig() está destinada a aplicaciones tipadas o herramientas de compilación; no permite que la CLI cargue directamente archivos TypeScript.

Para una integración funcional en producción hoy, utiliza el widget alojado o crea una interfaz personalizada con el SDK de JavaScript.