CLI dan deployment konfigurasi

Artefak CLI/config versi 0.3.1 yang dipublikasikan menerapkan kontrak konfigurasi/backend 0.3.0 dan menolak kunci yang tidak dikenal baik secara lokal maupun di backend.

CLI membuat, memvalidasi, melakukan deployment, mempromosikan, dan melakukan rollback versi konfigurasi ChattyBox yang immutable. Token deployment dibatasi untuk satu project dan environment yang dipilih, sehingga alur kerja yang sama cocok untuk pengembangan lokal dan CI.

Status Rilis dan Runtime

Paket publik @openstaticfish/chattybox-cli@0.3.1 dan @openstaticfish/chattybox-config@0.3.1, serta SDK JavaScript @openstaticfish/chattybox@0.1.4, mendukung skema yang diperluas dan kontrak backend 0.3.0. status menampilkan versi environment, sedangkan runtimeConfigVersionId adalah konfigurasi terakhir yang diterapkan ke runtime bersama dan dapat berbeda. mode yang dihilangkan memilih crawl tanpa mengubah maxDepth: 0 yang eksplisit. CLI adalah program ESM Node.js 20+; bunx mengikuti shebang Node secara default, atau pilih Bun secara eksplisit dengan bunx --bun @openstaticfish/chattybox-cli ....

Membuat konfigurasi

bunx @openstaticfish/chattybox-cli init

Perintah ini membuat chattybox.config.json:

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

Gunakan path khusus jika konfigurasi berada dalam subdirektori:

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

Memvalidasi secara lokal atau di CI

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

Validasi sumber saat ini memeriksa bentuk objek, nama asisten wajib, enum, URL HTTP(S), batas integer, kombinasi locale, dan warna hex enam digit. Validasi membaca JSON saja; tidak memuat TypeScript, JSONC, YAML, atau skema remote, tidak melakukan request jaringan, memeriksa token maupun entitlement, atau menerapkan default. Keberhasilan lokal tidak menjamin deployment.

Membuat token deployment

Buka tab Settings project, cari Config deployment tokens, lalu buat token untuk environment yang dapat diubah oleh alur kerja Anda. Segera salin token tersebut; ChattyBox hanya menyimpan hash-nya dan tidak dapat menampilkannya lagi.

Atur token dan URL API widget dari tab Embed project:

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

Jangan pernah commit token. Simpan token di secret store terenkripsi milik penyedia CI Anda.

Setelah memverifikasi alur deployment, Anda dapat mengaktifkan Config-as-code lock di bagian pengaturan yang sama. Lock ini tidak dapat dibuka melalui dasbor, CLI, atau API publik. Lock memblokir penulisan dashboard terhadap pengaturan proyek/widget yang dikelola config, unggahan ikon, serta operasi corpus manual seperti scraping, menghapus halaman, membersihkan konten, dan membangun ulang embedding. Lock tidak menghentikan pekerjaan terjadwal atau penghapusan proyek. Pembuatan/pencabutan token dan pengelolaan kunci publik tetap tersedia. Preferensi branding adalah pengecualian: kontrol branding dasbor tetap dapat diubah dalam entitlement paket.

Deploy konfigurasi

Deployment membuat versi immutable dan mempromosikannya ke environment yang dipilih:

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

development hanya mencatat versi/pointer (applied: false, indexingStatus: "not_required"). preview dan production menimpa pengaturan runtime project yang sama dan memakai corpus serta kunci widget publik yang sama; promosi runtime terbaru yang berlaku. Gunakan project terpisah untuk isolasi yang sebenarnya. Keduanya menerapkan konfigurasi secara atomik dan mengantrekan job scraping (applied: true, indexingStatus: "pending"), tetapi tidak menunggu scraping atau embedding selesai. Corpus bukan snapshot berversi dan refresh yang gagal tidak membatalkan konfigurasi yang telah diterapkan.

Deploy konfigurasi lengkap yang diinginkan, bukan patch. Promosi runtime menghapus atau mereset nilai config-owned yang dihilangkan. maxPages menyimpan permintaan tanpa dipangkas; proses memakai kapasitas efektif yang dijelaskan dalam aturan scraping. Scraping secara terpisah memeriksa kuota halaman/opsi PAYG dan batas refresh bulanan saat ini, sehingga nilai ini bukan janji setiap halaman akan diindeks. Refresh otomatis daily dan showBranding: false memerlukan Starter atau lebih tinggi; entitlement diperiksa saat promosi preview/production, termasuk rollback, bukan saat validasi lokal atau pencatatan development.

Gunakan --json dalam otomatisasi untuk menerima versi, environment, status aplikasi, dan ID job scraping sebagai output terstruktur.

Status, promosi, dan rollback

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 menggunakan ID versi konfigurasi yang opak, bukan nomor yang terlihat. Rollback memakai operasi backend yang sama dengan promote, tidak harus menargetkan versi yang lebih lama, dan menimpa pointer serta metadata promosi environment terpilih; tidak ada riwayat promosi append-only. Rollback preview atau production menerapkan kembali konfigurasi dengan entitlement saat ini dan mengantrekan refresh baru, bukan memulihkan corpus historis. status mengembalikan pointer environment yang dipilih dan ringkasan versi, bukan konfigurasi runtime efektif atau progres scraping/embedding.

Workflow CI/CD

Tambahkan CHATTYBOX_DEPLOY_TOKEN sebagai secret terenkripsi yang dicakup untuk production di penyedia CI Anda. Tambahkan CHATTYBOX_API_URL sebagai secret atau variabel menggunakan URL API widget dari tab Embed project. Jalankan validasi pada pull request, tetapi batasi deployment production ke branch default yang dilindungi atau environment deployment yang disetujui.

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

Gunakan secret production yang dicakup oleh environment dan wajibkan persetujuan deployment jika repositori Anda mendukungnya. CLI mencatat variabel commit dan branch CI umum bersama versi immutable.

GitLab CI/CD

Simpan kedua nilai di Settings → CI/CD → Variables. Lindungi token deployment, mask token tersebut, dan cakup ke environment 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 secara otomatis mengekspos CHATTYBOX_DEPLOY_TOKEN dan CHATTYBOX_API_URL ke job menggunakan nama variabelnya. Gunakan branch default yang dilindungi agar variabel yang dilindungi tidak tersedia untuk branch yang tidak tepercaya.

Bitbucket Pipelines

Tambahkan kedua nilai sebagai variabel deployment di Repository settings → Pipelines → Deployments → Production. Tandai token deployment sebagai secured.

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

Ganti main jika branch default Anda memiliki nama lain. Bitbucket hanya menyuntikkan variabel deployment ke langkah yang terkait dengan environment deployment tersebut.

Bagian konfigurasi

Bagian	Tujuan
schemaVersion	Memilih kontrak konfigurasi publik. Versi 1 saat ini didukung.
assistant	Memberi nama asisten dan secara opsional menentukan profil prompt serta prompt sistemnya.
knowledge.sources	Mendeklarasikan sumber situs web serta pola penyertaan dan pengecualian opsional.
runtime	Mengontrol locale otomatis/tetap, locale default, dan override locale tingkat halaman.
widget	Mengontrol enablement, posisi, teks, warna, dan presentasi ikon widget ter-host.

Helper konfigurasi bertipe

Instal paket konfigurasi saat membangun tooling TypeScript terpisah di sekitar skema:

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

CLI itu sendiri membaca file JSON. defineConfig() ditujukan untuk aplikasi bertipe atau tooling build; fungsi ini tidak membuat file TypeScript dapat langsung dimuat oleh CLI.

Untuk integrasi produksi yang berfungsi saat ini, gunakan widget yang dihosting atau bangun antarmuka khusus dengan SDK JavaScript.