CLI y despliegue de configuración

Los artefactos CLI/config publicados en la versión 0.3.1 implementan el contrato de configuración/backend 0.3.0 y rechazan las claves desconocidas tanto localmente como en el backend.

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.

Estado de versión y runtime

El registro público ofrece @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 y el SDK JavaScript @openstaticfish/chattybox@0.1.4. Estos artefactos admiten los campos ampliados junto con el contrato del backend 0.3.0; status muestra la versión del entorno, mientras que runtimeConfigVersionId identifica la última configuración aplicada al runtime compartido y puede diferir. Si se omite mode, se elige crawl y se conserva un maxDepth: 0 explícito. schemaVersion: "1" es independiente de las versiones de paquete.

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 actual comprueba formas, enums, URL HTTP(S), límites y combinaciones de idioma, pero solo lee JSON: no hace red, no comprueba token/plan ni aplica defaults. La validación local y la del backend rechazan las claves desconocidas; el éxito local no garantiza el despliegue.

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.

El Config-as-code lock es irreversible: no hay unlock por dashboard, CLI ni API. Bloquea configuración, cargas de icono y operaciones manuales del corpus; tokens y claves públicas siguen gestionables. Branding es la excepción: el control de dashboard permanece sujeto al plan.

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

development solo registra una versión sin aplicarla. preview y production comparten el mismo runtime, corpus y claves: la última promoción gana; use proyectos separados para aislamiento real. Aplican configuración y ponen el scrape en cola, sin esperar scrape/embeddings ni crear un snapshot de corpus. Las URL antiguas no se eliminan por omitirlas y un fallo no revierte la configuración.

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

--version usa el ID opaco de versión, no el número visible. Rollback usa la misma promoción, puede apuntar a cualquier versión y reaplica con límites/entitlements actuales; no restaura contenido histórico exacto.

maxPages guarda la solicitud sin ajustarla; la ejecución usa la capacidad efectiva descrita en las reglas de scraping. Daily auto-refresh y showBranding: false requieren Starter+. Los presupuestos y enfriamientos de scraping se revisan aparte.

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

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

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

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.