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.

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

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.

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.