CLI a nasazování konfigurace

Publikované CLI/config artefakty verze 0.3.1 implementují konfigurační/backendový kontrakt 0.3.0 a lokálně i na backendu odmítají neznámé klíče.

CLI vytváří, ověřuje, nasazuje, propaguje a vrací neměnné verze konfigurace ChattyBoxu. Nasazovací tokeny jsou omezené na jeden projekt a vybraná prostředí, takže stejný postup je vhodný pro místní vývoj i CI.

Stav vydání a runtime

Publikované jsou @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 a JavaScriptový SDK @openstaticfish/chattybox@0.1.4. Tyto artefakty podporují rozšířený kontrakt společně s backendem 0.3.0; schemaVersion: "1" není verze balíčku. status ukazuje verzi prostředí, kdežto runtimeConfigVersionId je poslední konfigurace použitá pro sdílený runtime a může se lišit. Vynechané mode zvolí crawl a zachová explicitní maxDepth: 0. CLI vyžaduje Node 20+ (nebo výslovné bunx --bun).

Vytvoření konfigurace

bunx @openstaticfish/chattybox-cli init

Tím se vytvoří soubor chattybox.config.json:

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

Pokud konfigurace patří do podadresáře, použijte vlastní cestu:

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

Místní ověření nebo ověření v CI

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

Validace čte jen JSON, nepouští síť, nekontroluje token či tarif a nenastavuje defaults. Lokální úspěch není záruka nasazení; lokální validátor i backend však neznámá pole odmítnou.

Vytvoření nasazovacího tokenu

Otevřete kartu projektu Settings, vyhledejte Config deployment tokens a vytvořte token pro prostředí, která může váš pracovní postup měnit. Ihned ho zkopírujte; ChattyBox ukládá pouze jeho hash a znovu ho nemůže zobrazit.

Nastavte token a URL API widgetu z karty projektu Embed:

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

Token nikdy necommitujte. Uložte ho do šifrovaného úložiště tajných údajů poskytovatele CI.

Po ověření můžete povolit Config-as-code lock. Je nevratný v aktuálním dashboardu, CLI i veřejném API; blokuje dashboardová nastavení, upload ikon i ruční scrape/mazání/rebuild. Tokeny a veřejné klíče zůstávají spravovatelné. Výjimkou je tarifem povolená volba brandingu v dashboardu.

Nasazení konfigurace

Nasazení vytvoří neměnnou verzi a propaguje ji do vybraného prostředí:

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

development jen zaznamená ukazatel (applied: false). Preview a production sdílejí stejný runtime, korpus i veřejné klíče; vyhraje poslední propagace. Pro skutečnou izolaci použijte samostatné projekty. Preview/production aplikují config a zařadí scrape, ale nečekají na indexaci, nemažou staré URL vynechané z nového zdroje a při chybě obnovy config nevracejí.

V automatizaci použijte --json, abyste jako strukturovaný výstup získali verzi, prostředí, stav aplikace a ID úlohy scrapingu.

Stav, propagace a návrat

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 přijímá neprůhledné version._id, ne číslo, SHA ani hash. Rollback používá stejnou propagaci, nemusí mířit na starší verzi a zařadí novou obnovu; neobnovuje historický korpus.

Úplná konfigurace a limity

Propagujte úplnou konfiguraci, ne patch: vynechaná config-owned pole se resetují, kromě widget.showBranding, které zachová stávající preferenci. maxPages ukládá požadavek bez oříznutí; běh používá efektivní kapacitu popsanou v pravidlech scrapingu. Daily auto-refresh a showBranding:false vyžadují Starter+. Rozsah preview/production tokenu runtime neizoluje.

CI/CD workflow

Přidejte CHATTYBOX_DEPLOY_TOKEN jako šifrovaný tajný údaj s rozsahem na produkci u svého poskytovatele CI. Přidejte CHATTYBOX_API_URL jako tajný údaj nebo proměnnou s URL API widgetu z karty Embed projektu. Spouštějte validaci v pull requestech, ale nasazení do produkce omezte na chráněnou výchozí větev nebo schválené nasazovací prostředí.

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

Použijte produkční tajný údaj omezený na prostředí a vyžadujte schválení nasazení, pokud to váš repozitář podporuje. CLI zaznamenává běžné CI proměnné commitu a větve spolu s neměnnou verzí.

GitLab CI/CD

Obě hodnoty uložte v Settings → CI/CD → Variables. Token nasazení chraňte, zamaskujte a omezte jeho rozsah na prostředí 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 automaticky zpřístupňuje CHATTYBOX_DEPLOY_TOKEN a CHATTYBOX_API_URL úloze pod jejich názvy proměnných. Použijte chráněnou výchozí větev, aby chráněné proměnné nebyly dostupné nedůvěryhodným větvím.

Bitbucket Pipelines

Přidejte obě hodnoty jako proměnné nasazení v Repository settings → Pipelines → Deployments → Production. Označte token nasazení jako zabezpečený.

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

Nahraďte main, pokud má vaše výchozí větev jiný název. Bitbucket vkládá proměnné nasazení pouze do kroků přidružených k danému nasazovacímu prostředí.

Části konfigurace

Část	Účel
schemaVersion	Vybírá veřejný konfigurační kontrakt. V současnosti je podporována verze 1.
assistant	Pojmenovává asistenta a volitelně definuje jeho profil pokynů a systémový pokyn.
knowledge.sources	Deklaruje zdroje webových stránek a volitelné vzory pro zahrnutí či vyloučení.
runtime	Obsahuje výchozí hodnoty běhového prostředí, například locale.
widget	Popisuje volitelná nastavení vzhledu hostovaného widgetu.

Pomocná funkce pro typovanou konfiguraci

Při vytváření samostatných nástrojů TypeScript nad schématem nainstalujte konfigurační balíček:

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 },
});

Samotné CLI čte soubory JSON. defineConfig() je určené pro typované aplikační nebo sestavovací nástroje; neumožňuje CLI přímo načítat soubory TypeScript.

Pro funkční produkční integraci dnes použijte hostovaný widget nebo vytvořte vlastní rozhraní pomocí JavaScript SDK.