xbp 10.17.1

# XBP


XBP (XYLEX Build Pack) is a deployment and operations CLI for single-service and multi-service projects.
It combines build/run workflows, PM2 process management, diagnostics, nginx helpers, secrets workflows, and project version synchronization in one tool.

## Features 

- `monitoring`
- `docker`
- `kubernetes` [exp]
- `kafka` [exp]
- `pm2` [wip]


current version: `10.17.1`
## TL;DR (30-Second Start)


```bash
# 1) Install

cargo install xbp

# 2) Check project/runtime state

xbp ports
xbp services

# 3) Run and inspect

xbp service build api
xbp service start api
xbp logs api

# 4) Keep versions aligned

xbp version
xbp version patch
```

## Why XBP


- One CLI for local service workflows and server-side operations.
- Supports Rust, Node.js, Next.js, Python, Express, and mixed repos.
- Handles PM2 lifecycle, logs, snapshots, and environment inspection.
- Includes version reconciliation across common manifest files and git tags.
- Adds operational helpers for ports, nginx, diagnostics, and secrets.

## Feature Overview


- Project and service orchestration: `services`, `service`, `redeploy`, `setup`.
- Process/runtime control: `list`, `start`, `stop`, `flush`, `snapshot`, `resurrect`, `env`, `logs`, `tail`.
- Network and infra helpers: `ports`, `nginx`, `diag`, `curl`.
- Configuration and security: `config`, `secrets`.
- Version workflows: `version` report, bump, explicit set, git-tag view.
- Optional monitoring command family (feature-gated build).
- Optional Kubernetes helper (feature-gated): `xbp kubernetes ...` for manifest generation, apply, readiness checks, and cert-manager issuer bootstrap. Build with `--features kubernetes`.
- Optional Docker helper (feature-gated): `xbp -l` / `xbp list` shows `docker ps` snapshot when built with `--features docker`.

## Installation


### Option 1: Build From Source


```bash
git clone https://github.com/xylex-group/xbp.git
cd xbp
cargo build --release
./target/release/xbp --help
```

### Option 2: Install From Cargo


```bash
cargo install xbp
```

### Verify Installation


```bash
xbp --version
xbp --help
```

## Quick Start


```bash
# Discover project/runtime state

xbp ports
xbp services

# Build or run a service from xbp config

xbp service build api
xbp service start api

# Deploy flow shortcut

xbp redeploy api

# PM2 snapshots for recovery

xbp snapshot
xbp resurrect

# Version report across manifests and tags

xbp version
```

## Configuration


XBP resolves project config in this order:

1. `.xbp/xbp.yaml`
2. `.xbp/xbp.yml`
3. `.xbp/xbp.json`
4. `xbp.yaml`
5. `xbp.yml`
6. `xbp.json`

Both YAML and JSON are supported. If no explicit project version is set, default is `0.1.0`.

### Minimal YAML


```yaml
project_name: my-app
version: 0.1.0
port: 3000
build_dir: /path/to/project
```

### Multi-Service Example


```yaml
project_name: my-stack
version: 0.1.0
port: 3000
build_dir: /srv/my-stack

services:
  - name: api
    target: rust
    branch: main
    port: 3000
    root_directory: apps/api
    url: https://api.example.com
    commands:
      install: cargo fetch
      build: cargo build --release
      start: ./target/release/api

  - name: web
    target: nextjs
    branch: main
    port: 3001
    root_directory: apps/web
    commands:
      install: pnpm install
      build: pnpm run build
      start: pnpm run start
```

### Core Fields

- `project_name`: logical project name.
- `version`: semantic version string for project-level versioning.
- `port`: primary project port.
- `build_dir`: absolute path to project root.
- `services`: optional service list.
- `environment`: optional environment variables.

### Service Fields

- `name`: service identifier.
- `target`: `rust`, `nextjs`, `nodejs`, `python`, or `expressjs`.
- `branch`: deploy branch.
- `port`: service port.
- `root_directory`: optional service-specific working directory.
- `url`: optional public URL.
- `healthcheck_path`: optional health route.
- `commands`: optional `pre`, `install`, `build`, `start`, `dev` commands.

## Command Cookbook

### Project and Service Commands

- `xbp services`: list services from config.
- `xbp service build <name>`: run service build command.
- `xbp service install <name>`: run service install command.
- `xbp service start <name>`: run service start command.
- `xbp service dev <name>`: run service dev command.
- `xbp redeploy <name>`: redeploy one service.

### Runtime and Operations

- `xbp list`: PM2 process list.
- `xbp logs [project]`: view PM2 logs.
- `xbp logs --ssh-host <host> --ssh-username <user> --ssh-password <pw>`: remote logs.
- `xbp ports`: active listening ports.
- `xbp ports --kill --port 3000`: kill process(es) on a port.
- `xbp ports --nginx`: include nginx mapping view.
- `xbp ports --full`: include reconciled XBP project port data.
- `xbp diag`: run environment diagnostics.
- `xbp ports --exposure`: diagnose service bind + firewall exposure per port.
- `xbp nginx setup --domain <domain> --port <port> --email <email>`: provision HTTPS reverse proxy with Certbot.
- `xbp nginx list`: list discovered nginx sites.
- `xbp nginx show <domain>`: show nginx config.
- `xbp nginx update --domain <domain> --port <port>`: update upstream port.
- `xbp network floating-ip add --ip <IP>`: write persistent floating IP config on detected backend.
- `xbp network floating-ip add --ip <IP> --apply`: write and apply/reload network config.
- `xbp network floating-ip list`: list floating IPs from runtime + config.
- `xbp network config list`: list discovered network config files and backend detection.
- `xbp curl <url-or-domain>`: quick endpoint health/content check.
- `xbp kubernetes addons list`: show full MicroK8s addon status (enabled/disabled).
- `xbp kubernetes addons enable <name>`: enable a MicroK8s addon.
- `xbp kubernetes addons disable <name>`: disable a MicroK8s addon.
- `xbp kubernetes dashboard-token`: extract the dashboard JWT token from `describe secret`.
- `xbp kubernetes observability-creds`: print decoded Grafana admin credentials from observability secret.
- `xbp kubernetes issuer --email <email>`: create/update a cert-manager Let's Encrypt issuer (feature-gated build).

### PM2 Shortcuts

- `xbp snapshot`: save PM2 process snapshot.
- `xbp resurrect`: restore PM2 state.
- `xbp stop <target>`: stop one process or all.
- `xbp flush [target]`: flush logs globally or for a process.
- `xbp monitor check`: one-shot monitor check.
- `xbp monitor start`: monitor daemon.
- `xbp env <pm2-name-or-id>`: show PM2 env.

### Config, Setup, and Secrets

- `xbp setup`: guided local setup helpers.
- `xbp config`: show/open global XBP config paths.
- `xbp config --project`: show current project config.
- `xbp config openrouter set-key [KEY]`: store OpenRouter API key globally.
- `xbp config openrouter show [--raw]`: inspect stored OpenRouter key.
- `xbp config openrouter delete-key`: remove stored OpenRouter key.
- `xbp config github set-key [TOKEN]`: store GitHub OAuth2 token globally.
- `xbp config github show [--raw]`: inspect stored GitHub token.
- `xbp config github delete-key`: remove stored GitHub token.
- `xbp secrets list`: list required/local env keys.
- `xbp secrets push --file .env.local`: push secrets to provider.
- `xbp secrets pull --output .env.local`: pull secrets from provider.
- `xbp secrets verify`: validate required env key availability.

## Nginx HTTPS Setup

`xbp nginx setup` now covers the full native Certbot + Nginx wiring flow for both regular and wildcard domains.

```bash
# Standard domain (HTTP-01)
xbp nginx setup --domain api.example.com --port 3000 --email ops@example.com

# Wildcard domain with manual DNS-01 prompts
xbp nginx setup \
  --domain '*.example.com' \
  --port 3000 \
  --email ops@example.com \
  --dns-mode manual \
  --include-base true

# Wildcard domain with DNS plugin automation
xbp nginx setup \
  --domain '*.example.com' \
  --port 3000 \
  --email ops@example.com \
  --dns-mode plugin \
  --dns-plugin cloudflare \
  --dns-creds /root/.secrets/certbot/cloudflare.ini
```

Setup behavior:

- Ensures `nginx` and `certbot` are installed.
- Ensures `/etc/letsencrypt/options-ssl-nginx.conf` and `/etc/letsencrypt/ssl-dhparams.pem` exist.
- Writes a temporary HTTP ACME config for regular domains, then final HTTPS config with redirect.
- Uses DNS-01 for wildcard domains (`manual` or `plugin` mode).
- Reuses existing certificates when present.
- Validates config with `nginx -t` and restarts nginx on success.

## Floating IP Persistence

XBP can persist Floating IP configuration for Linux hosts by auto-detecting the active backend in this order:
1. Netplan
2. NetworkManager keyfiles
3. ifupdown
4. RHEL ifcfg scripts

```bash
# Hetzner-style IPv4 floating IP persistence (write-only)
xbp network floating-ip add --ip 203.0.113.10

# IPv6 floating IP with explicit CIDR and apply
xbp network floating-ip add --ip 2a01:4f9:0:2a1::2 --cidr 64 --interface eth0 --apply

# Inspect persisted + runtime addresses
xbp network floating-ip list
xbp network config list
```

### Versioning


- `xbp version`: full version report (manifests + tags + registry when configured).
- `xbp version --git`: show normalized git tag versions.
- `xbp version major`: bump major in tracked files.
- `xbp version minor`: bump minor in tracked files.
- `xbp version patch`: bump patch in tracked files.
- `xbp version <x.y.z>`: set tracked files to an explicit semver.
- `xbp version <package>=<x.y.z>`: update package assignment versions in tracked TOML files.
- `xbp version release`: create/push `v<version>` git tag and publish GitHub release.
- `xbp version release --version <x.y.z>`: release an explicit version.
- `xbp version release --notes-file <PATH>`: use custom Markdown release notes.

## Version Management Details


`xbp version` resolves versions from configured files, local/remote git tags, and configured package registries.
It normalizes prefixed tags (`v1.2.3`) and plain semver (`1.2.3`) into one comparison space.

### Package Assignment Updates In TOML


`xbp version <package>=<x.y.z>` updates both forms in tracked TOML files:

- `<package> = "x.y.z"`
- `<package> = { version = "x.y.z", ... }`

Example:

```bash
xbp version tokio=1.45.1
```

### Default Tracked Version Files


- `README.md`
- `openapi.yaml`
- `openapi.yml`
- `Cargo.toml`
- `Cargo.lock`
- `package.json`
- `package-lock.json`
- `pyproject.toml`
- `xbp.yaml`
- `xbp.json`
- `.xbp/xbp.yaml`
- `.xbp/xbp.json`

The registry is synchronized into global XBP config as `versioning-files.yaml`.
Missing defaults are re-added without removing custom entries.

## PM2 Behavior


XBP uses PM2 as an execution/runtime layer for many commands.

- Deploy and start flows can (re)start services under PM2.
- `snapshot` stores recoverable process state.
- `resurrect` first tries native PM2 restore, then falls back to latest XBP snapshot.
- `env` maps PM2 names to IDs and prints effective runtime environment.

## Ports and Diagnostics


- `xbp ports` reconciles active listeners with detected project and nginx metadata.
- `xbp diag` validates common system dependencies and service expectations.

## MCP Server


XBP includes an MCP stdio server at `scripts/xbp_mcp_server.py`.
It exposes tools for all current `xbp` commands and includes `xbp_raw` for raw arg passthrough.

### Run MCP Server


```bash
python3 scripts/xbp_mcp_server.py
```

### What It Returns


Each tool call returns:

- Executed command array.
- Working directory.
- Exit code.
- Captured stdout/stderr.

### Server Tests


```bash
python3 -m unittest scripts/test_xbp_mcp_server.py
```

## Repository Layout


- `src/main.rs`: binary entrypoint.
- `src/lib.rs`: library exports.
- `src/cli/`: clap command definitions and dispatch.
- `src/commands/`: command implementations.
- `src/strategies/`: deployment strategy and project detection.
- `src/sdk/`: PM2 and nginx integrations.
- `src/utils/`: shared helpers.
- `scripts/`: support scripts including MCP server.

## Development


```bash
cargo fmt
cargo test
python3 -m unittest scripts/test_xbp_mcp_server.py
```

## Troubleshooting


- If `xbp` is not found, ensure Cargo bin path is on `PATH`.
- If PM2 commands fail, verify PM2 is installed and reachable in your shell env.
- If nginx commands fail, run with elevated permissions where required.
- If `xbp version` cannot update package assignments, confirm the target file is TOML and listed in versioning registry.
- If MCP command calls fail, confirm `xbp` is installed on the same environment where `xbp_mcp_server.py` is running.

## License


MIT