call-baxter monorepo¶

Monorepo layout:

• packages/call-baxter:
• generic callback/runtime scaffold
• webhook ingress, pollers, schedules, rules, and actions
• Telegram integrated as a plugin
• packages/tg-agent-cli:
• Telegram projection/index database and CLI
• browse chats, messages, callbacks, media, and action history from tg.db
• packages/wordpress-plugin:
• WordPress bridge plugin for mirroring Telegram events into WordPress posts
• idempotent media upload, hashtag routing, and gallery support
• packages/social-plugin:
• Bluesky, Mastodon, and X publishing plugins
• native provider actions plus durable Telegram mirror/album-flush actions
• infra:
• Docker/Compose and Caddy deployment assets
• rules.d:
• operator rule files
• services/rust-baxter:
• Rust service/docs kept in the same repository

Runtime split¶

Telegram webhook or poll
  -> call-baxter telegram plugin
  -> persist into tg-agent-cli projection db
  -> emit telegram.* events
  -> call-baxter rules/actions
  -> tg-agent-cli operates directly on tg.db for browse/operator commands

Quickstart from monorepo root¶

Run the canonical verification gate before changing or releasing the repository:

./scripts/verify.sh

This root gate runs lockfile validation, all package tests, ruff, mypy, coordinated release-version validation, package builds, installation tests for the built wheels, Compose validation, Docker hardening checks, infra todo checks, repository hygiene checks, documentation command checks, quality/architecture todo checks, and coverage floors.

After the wheels have been built, their focused installed-artifact smoke test is:

./scripts/smoke-packages.sh

The complete release gate additionally starts both shipped container configurations:

./scripts/verify-release.sh v0.8.0

Focused infra todo verification is also available with:

./scripts/verify-infra-todos.sh

Focused quality/architecture todo verification is available with:

./scripts/verify-qual-arch-todos.sh

Deploy from the monorepo¶

For the complete Telegram-to-WordPress example, use the self-contained docker/ bundle and start in polling mode:

cd docker
cp .env.example .env
# Edit .env with the Telegram token and database passwords.
mkdir -p state/{run,data,caddy_data,caddy_config,mysql,wordpress}
sudo chown -R 10001:10001 state/run state/data
sudo chmod 0770 state/run state/data
docker compose up -d --build

Then follow docker/TELEGRAM_WORDPRESS_TUTORIAL.md to install WordPress, create the integration user and application password, verify the REST API, publish a real #blog message, and optionally switch to HTTPS webhook mode.

Use infra/ only for the minimal Call Baxter + Caddy layout. That image includes the social publishing plugins, but does not contain the WordPress plugin and does not run WordPress or MariaDB.

Coordinated release¶

Release v0.8.0 ships call-baxter, tg-agent-cli, cb-wordpress-plugin, and cb-social-plugin as one coordinated package set. The first three remain the TGEX/telegras2 replacement surface; the social package adds independently configurable Bluesky, Mastodon, and X publishing actions.

This minor release adds the social publishing plugin family and per-provider documentation while retaining the modular cb CLI, Telegram reingestion, redacted runtime configuration, and the operational acceptance metadata established by the 0.7 release line.

The call-baxter package installs compatible telegras and telegras2 launchers. Existing webhook and polling deployments can retain the legacy command names, environment aliases, webhook path, /healthz, and /internal/introspection/* clients while the process runs the Call Baxter runtime.

Install the coordinated release artifacts into the same environment, preserve the existing TGEX environment, and initialize compatibility state:

telegras2 db-init
telegras2 doctor
telegras2 migrate-history --dry-run
telegras2 migrate-history
telegras2 routes
telegras2 start

The full compatibility matrix, cutover checklist, limitations, and rollback procedure are documented in packages/call-baxter/docs/tgex-migration.md and in the MkDocs page call-baxter → Replace TGEX.

Documentation¶

The repository includes a root mkdocs.yml configured for Material for MkDocs. The site is built from docs/ wrapper pages that include the package-local markdown, so the package docs remain the canonical source. The published site provides client-side search with suggestions, highlighting, and shareable result URLs.

The documentation toolchain is pinned in tools/docs/uv.lock. Use the repository scripts instead of an unpinned global MkDocs installation:

# Live local preview
uv run --project tools/docs --locked mkdocs serve

# Strict HTML/search-index build into site/
./scripts/build-docs.sh

# Strict HTML validation plus the combined A4 PDF
./scripts/build-docs-pdf.sh

The PDF is written to site/assets/call-baxter-documentation.pdf. CI uploads it as a workflow artifact, and the Pages workflow publishes the same file beside the HTML site.

Automation¶

• .github/workflows/ci.yml runs package tests, linting, type checks, package builds, the reproducible HTML/PDF docs build, and the existing full scripts/verify.sh gate.
• .github/workflows/docs.yml deploys the searchable MkDocs site and generated PDF to GitHub Pages from main or master.
• .github/workflows/release.yml runs the complete release gate for tags matching v*, then publishes all wheels, source archives, the verified documentation PDF, and a SHA256SUMS manifest. Publishing is idempotent, so a failed or interrupted run can be rerun without recreating the tag.

Operator access and zrok command allowlist¶

Set CALL_BAXTER_API_KEY for non-ingress /v1/* operator routes such as reload, action execution, event publishing, poller runs, and query endpoints.

Set CALL_BAXTER_INGRESS_TOKEN separately for webhook/ingress execution routes so webhook callers do not gain operator privileges.

The zrok.run action is constrained by allowed_subcommands in the call_baxter.plugins.zrok plugin config. The default allowlist is share, status, and version; add more commands only when an operator rule genuinely needs them.

plugins:
  - module: call_baxter.plugins.zrok
    config:
      allowed_subcommands:
        - share
        - status
        - version

Docker deployment layouts¶

The docker/ example uses Telegram polling by default so the first deployment needs no public domain. Caddy starts only with docker compose --profile webhook ... after webhook mode is configured.