xbp 10.12.2

# XBP

XBP is the XYLEX Build Pack: a build, deployment, and operations toolkit for modern applications and multi-service projects.

current version: `10.12.2`
## What It Does

- Builds and deploys Rust, Node.js, Next.js, Python, Express, and mixed-service projects
- Manages PM2 processes, snapshots, resurrection, logs, and runtime inspection
- Works with nginx, ports, secrets, diagnostics, and deployment configuration
- Tracks versions across manifests and git tags
- Supports local workflows and server-side operations from one CLI

## Install

Release binaries can be used directly, or build from source with Rust.

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

To install from Cargo:

```bash
cargo install xbp-cli
```

## Quick Start

```bash
xbp ports
xbp services
xbp service build api
xbp redeploy api
xbp snapshot
xbp version
```

## Configuration

XBP looks for configuration 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 JSON and YAML are supported. A project version defaults to `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`: project name
- `version`: semantic version for the project
- `port`: primary project port
- `build_dir`: absolute project path
- `services`: optional service list for multi-service projects
- `environment`: optional environment variables

### Service Fields

- `name`: service name
- `target`: `rust`, `nextjs`, `nodejs`, `python`, or `expressjs`
- `branch`: deployment branch
- `port`: service port
- `root_directory`: optional service working directory
- `url`: optional public URL
- `healthcheck_path`: optional health path
- `commands`: optional `pre`, `install`, `build`, `start`, and `dev` commands

## Common Commands

### Project And Services

- `xbp services`
- `xbp service build <name>`
- `xbp service install <name>`
- `xbp service start <name>`
- `xbp service dev <name>`
- `xbp redeploy <name>`

### Runtime And Operations

- `xbp list`
- `xbp logs [project]`
- `xbp ports`
- `xbp ports --nginx`
- `xbp ports --full`
- `xbp diag`
- `xbp nginx list`
- `xbp nginx show <domain>`
- `xbp nginx edit <domain>`
- `xbp curl <domain>`

### PM2 Shortcuts

- `xbp snapshot`
- `xbp resurrect`
- `xbp stop <target>`
- `xbp flush [target]`
- `xbp monitor`
- `xbp env <pm2-name>`

### Config, Setup, And Secrets

- `xbp setup`
- `xbp config`
- `xbp config --project`
- `xbp secrets pull`
- `xbp secrets verify`

### Versioning

- `xbp version`
- `xbp version --git`
- `xbp version major`
- `xbp version minor`
- `xbp version patch`
- `xbp version <x.y.z>`

## Version Management

`xbp version` reads and writes versions across common project files and git tags. It normalizes `v1.2.3` and `1.2.3` as the same version and can bump or set versions across supported manifests from one command.

Default tracked files include:

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

The tracked file registry is synced into the global XBP config directory through `versioning-files.yaml`. Missing defaults are restored automatically without removing user-added entries.

## PM2 Behavior

XBP uses PM2 as an execution layer for many runtime workflows.

- Deployments can start or restart services under PM2
- `xbp snapshot` stores PM2 state for later restore
- `xbp resurrect` first tries native PM2 restore, then falls back to the latest XBP snapshot
- `xbp env <name>` resolves a PM2 name to its PM2 id and prints the PM2 environment

## Ports And Diagnostics

`xbp ports` reconciles listening ports, nginx upstreams, and configured XBP project ports. `xbp diag` checks known service ports and highlights ports owned by recognized XBP projects.

## Repository Layout

- `src/main.rs`: CLI entrypoint
- `src/lib.rs`: library exports
- `src/cli/`: argument parsing and command dispatch
- `src/commands/`: command implementations
- `src/strategies/`: deployment and project strategy logic
- `src/sdk/`: integrations such as PM2 and nginx
- `src/utils/`: shared helpers

## Development

```bash
cargo fmt
cargo test
```

## License

MIT