# 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.15.4`
## 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, and readiness checks. 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 nginx list`: list discovered nginx sites.
- `xbp nginx show <domain>`: show nginx config.
- `xbp nginx update --domain <domain> --port <port>`: update upstream port.
- `xbp curl <url-or-domain>`: quick endpoint health/content check.
### 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 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.
### 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.
## 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