Bleu

Bleu is a Bun/TypeScript workspace for community operations and native community services.

• CMMC is the administrative control plane for accounts, communities, policy, membership, cases, privacy, audit, product provisioning, and fleet management.
• BleuBridge imports external community state and applies CMMC-owned actions through versioned service APIs.
• BleuSocial owns native channels, threads, messages, reactions, events, engagement, notifications, news, profiles, and media-room metadata; its live WebSocket gateway has polling fallback.
• Bleu Client is the member-facing web app and same-origin HTTP/WebSocket gateway to community BleuSocial services. Sign-in delegates to CMMC, which remains authoritative for identity and authorization.
• BleuAgent is the outbound-only deployment agent used by CMMC-managed targets.

Release scope and known pre-release risks are tracked in docs/release-readiness.md. Planning material is directional and is not a release claim.

Quick start

Requirements: Bun 1.3.13 and Git. The optional pinned Nix shell (Linux only) supplies Bun, Chromium, Node, Docker CLI/Compose/Buildx, SQLite, jq, curl, and common POSIX tools. The Chromium browser tests look for chromium, chromium-browser, or google-chrome on PATH and are skipped when none is found.

git clone <repository-url>
cd bleu
nix develop # optional
bun install --frozen-lockfile
bun run dev:cmmc

CMMC listens on http://127.0.0.1:3000. Root dev:* scripts run each app from its own directory, so relative data paths resolve there: CMMC stores development data in apps/cmmc/data/cmmc.sqlite (BleuSocial in apps/bleusocial/data/). On first start, / serves the setup wizard; use the one-time setup token printed in the service log. The wizard's first step requires SMTP settings. In the Instance step, enter browser-facing CMMC and Bleu Client origins; single-label container hosts such as http://cmmc:3000 are not prefilled and produce a warning because members' browsers may not resolve them. Loopback origins remain supported for local development. After setup, / serves the branded landing page, or redirects to the member app when a community has a member-app URL. Only a clean database is supported: nightly and prototype CMMC databases are not migrated. Back up any data that must be retained, then run bun run dev:cmmc:reset only for disposable local state (the command is destructive). CMMC creates schema version 26; BleuSocial creates its clean migration sequence (versions 1–3).

Start another component in a separate terminal when needed:

# Bridge requires a Bridge-scoped CMMC service credential.
BLEUBRIDGE_CMMC_BASE_URL=http://127.0.0.1:3000 \
BLEUBRIDGE_SERVICE_TOKEN=cmmc_svc_... \
BLEUBRIDGE_ADMIN_TOKEN=bridge_admin_local_dev_token \
bun run dev:bleubridge

# Social may start unconfigured; these values enable CMMC bootstrap.
BLEUSOCIAL_CMMC_BASE_URL=http://127.0.0.1:3000 \
BLEUSOCIAL_SERVICE_TOKEN=cmmc_svc_... \
bun run dev:bleusocial

# Client needs a generic token with communities:read and memberships:read.
BLEU_CLIENT_CMMC_BASE_URL=http://127.0.0.1:3000 \
BLEU_CLIENT_CMMC_PUBLIC_URL=http://127.0.0.1:3000 \
BLEU_CLIENT_SERVICE_TOKEN=cmmc_svc_... \
bun run dev:bleuclient

# Agent credentials are generated by CMMC Fleet Management. The token must
# be in an owner-only file; BLEUAGENT_TOKEN is intentionally rejected.
# Use an absolute path: the agent runs from apps/bleuagent.
umask 077
mkdir -p data
printf '%s' 'cmmc_agent_...' > data/bleuagent-token
BLEUAGENT_CMMC_BASE_URL=http://127.0.0.1:3000 \
BLEUAGENT_TARGET_ID=<deployment-target-id> \
BLEUAGENT_TOKEN_FILE="$PWD/data/bleuagent-token" \
bun run dev:bleuagent

Default local ports are CMMC 3000, BleuBridge 3001, BleuSocial 3002, and Bleu Client 3003. BLEU_CLIENT_CMMC_BASE_URL is the internal server-to-server origin. Optional BLEU_CLIENT_CMMC_PUBLIC_URL is an origin-only browser-facing override; without it, Bleu Client uses the public CMMC origin advertised by gateway metadata, then falls back to the internal origin. Bleu Client /login redirects to CMMC's /login flow; after authentication, the member shell provides sign-out and community switching. Social message, thread, and profile reads are cursor-paginated, message pages carry reaction summaries, and the browser consumes live message/reaction/notification deltas through the same-origin /api/gateway WebSocket with polling fallback.

Validate a change

bun run ci:pr       # repo health, sensitive scan, tracked artifacts, check, test, build
bun run ci:release  # ci:pr + coverage gate, dependency audit, backup drill, infrastructure tests

Each step is also a root script (check:repo-health, check:sensitive, check:tracked-artifacts, check, test, build, test:coverage, audit, backup:drill, test:infra). Run one workspace suite with bun run --cwd apps/<name> test, where <name> is cmmc, bleubridge, bleusocial, bleuclient, or bleuagent.

Docker development

docker compose -f infra/docker/compose.yml up --build

The base stack starts CMMC and Bleu Client. Optional profiles start internal product services:

COMPOSE_PROFILES=bridge BLEUBRIDGE_SERVICE_TOKEN=cmmc_svc_... \
docker compose -f infra/docker/compose.yml up --build

COMPOSE_PROFILES=social BLEUSOCIAL_SERVICE_TOKEN=cmmc_svc_... \
docker compose -f infra/docker/compose.yml up --build

Bridge and Social bind to host loopback; CMMC and Bleu Client are published on ports 3000 and 3003. Data is held in separate cmmc-data and bleusocial-data volumes; CMMC provisions Bleu Client's token onto the shared bleuclient-credential volume, and the agent profile uses bleuagent-deployments. Compose passes BLEU_BUILD_VERSION and BLEU_BUILD_COMMIT as build arguments to all five images; runtime status and rendered build footnotes therefore identify the built version and commit. This is development topology, not an internet-facing deployment. Production must combine the base file with the security overlay, use immutable image digests and mounted secret files, terminate TLS at a trusted reverse proxy, and keep internal services and Docker authority off public networks. Follow the deployment guide, security guide, and backup/restore guide.

Every service logs only to stdout/stderr through log() in packages/http/src/logger.ts. Each entry is one JSON line, {ts, level, service, event, ...fields}. event is a stable dotted name such as http.request.completed or cmmc.scheduled_task.failed, and errors are written inline as error: {type, message, code?, stack?, cause?}. The one plain-text exception is the CMMC setup-token banner. No service or self-update helper writes a log file. The CMMC and BleuAgent self-update helper containers are kept after they exit, so their output stays in docker logs until the next update removes them. Indev images (BLEU_BUILD_VERSION=indev, which is also the default for local docker compose ... --build images) automatically emit debug logs, including HTTP methods, paths, response statuses and durations, error stacks, plus BleuAgent connection attempts and transitions. This remains enabled with NODE_ENV=production. Other builds can opt in with BLEU_LOG_LEVEL=debug. Capture container output with docker compose logs --timestamps cmmc bleuagent (add -p bleu-cmmc-indev -f infra/docker/compose.indev.yml for the indev sandbox) when reporting setup or connection bugs. Request diagnostics exclude query strings, headers and bodies.

For the published :indev sandbox, use bun run indev:launch (preserves the existing volume), bun run indev:console (Docker Console on http://127.0.0.1:3010), or bun run indev:cleanup --dry-run. bun run indev:test and bun run indev:fresh are the same destructive operation: pull, delete the sandbox volumes, and start fresh, without a prompt. See the incident runbooks before destructive cleanup.

Repository layout

• apps/cmmc: control plane, REST API, WebUI, SQLite store, and tests.
  • src/server/: server composition plus implemented route-family modules such as agent-routes.ts, audit-routes.ts, deployment-routes.ts, and privacy-routes.ts.
  • src/store/repositories/: domain persistence implementations behind src/store/sqlite-store.ts and the store contracts.
  • src/ui/views/: bounded server-rendered layouts, pages, and primitives composed through src/ui/views.ts.
  • src/static/app/: bounded browser runtime, route, tab, form, and incremental-rendering modules; src/static/styles.css is the served entry point for the consolidated src/static/styles/ layer set.
• apps/bleubridge: synchronization service and generic/Discord adapters.
• apps/bleusocial: native community API, route-family modules, /api/gateway WebSocket transport, and independent SQLite store.
• apps/bleuclient: member web app and CMMC-routed same-origin HTTP/WebSocket Social gateway.
• apps/bleuagent: outbound deployment agent.
• packages/http, shared, social-web, ssr, ui, db: shared runtime and UI packages. SQLite remains the supported store adapter; experimental PostgreSQL is isolated behind @bleu/db/experimental-postgres.
• infra/docker: image, Compose (development, indev, production overlay), indev tooling, Docker Console, and log export.
• infra/ci: CI helpers: Docker/release-tool installers, image smoke qualification, signing/promotion library, and failure reporter.
• scripts: repository gates (repo health, module budgets, coverage, sensitive scan, tracked artifacts) and the SQLite backup/restore helper.

Documentation

The current documentation contract is v1:

• Documentation index
• Architecture
• API guide
• Security guide
• Backup and restore
• Incident runbooks
• Release readiness
• Container deployment

Versioning applies to the documentation contract, not to every browser route. Service integrations should use /api/service/v1/*; unversioned administrative and member routes may evolve with the application release.

Export diagnostic logs for a bug report

After reproducing a bug on indev, run bun run logs:export (or nix develop -c bun run logs:export). It writes a single timestamped bleu-diagnostics-*.log file in the current directory. The file starts with a # header that explains the format and lists each container with its image, status, exit code and restart count. Log lines from all containers follow, merged and sorted by time: <utc-timestamp> <container> <out|err> <message>. The layout is designed so an LLM or a person can follow one request across services. You can choose a filename with bun run logs:export -- ./bug-report.log. Existing files are never overwritten.

The export includes retained stdout/stderr from every container in the indev Compose project, local BleuAgent/updater containers, and managed BleuSocial/BleuBridge projects. It includes timestamps, container image identities, restart counts, HTTP diagnostics, startup messages, API rejection codes, agent command outcomes, and error stacks. Logs continue to appear in Docker Compose normally. Set BLEU_INDEV_PROJECT_NAME for a different project. BLEU_LOG_EXTRA_PROJECTS is a comma-separated list of managed projects; it replaces the default bleu-bleusocial,bleu-bleubridge list.

Known token formats and credential fields are redacted in the exported file, which is created with owner-only permissions. Redaction is best effort; review the file before sharing. The export contains only logs Docker still retains, and cannot recover logs from deleted containers. Browser-only errors are not included. Rebuild/redeploy the updated images before reproducing the issue to get the new diagnostics.