devforge 0.1.0

# devforge

Config-driven dev environment orchestrator for Rust workspaces. Define your Docker services, health checks, hooks, and process manager in a single TOML file.

## Quick Start

### 1. Add the xtask crate to your workspace

```toml
# xtask/Cargo.toml
[package]
name = "xtask"
version = "0.1.0"
edition = "2021"
publish = false

[dependencies]
devforge = "0.1"
```

```rust
// xtask/src/main.rs
fn main() {
    devforge::run();
}
```

### 2. Add the cargo alias

```toml
# .cargo/config.toml
[alias]
xtask = "run --package xtask --"
```

### 3. Create `devforge.toml` at your workspace root

```toml
env_files = [".env"]
required_tools = ["docker", "cargo", "mprocs"]

[docker]
compose_file = "docker-compose.yml"

[[docker.health_checks]]
name = "postgres"
cmd = ["docker", "compose", "exec", "-T", "postgres", "pg_isready", "-U", "myuser"]
timeout = 30

[[docker.health_checks]]
name = "redis"
url = "http://localhost:6379"
timeout = 15

[dev]
mprocs_config = "mprocs.yaml"

[[dev.hooks]]
cmd = "npm install"
cwd = "web"

[dev.hooks.condition]
missing = "web/node_modules"
```

### 4. Run it

```bash
cargo xtask dev     # Start everything
cargo xtask infra   # Docker only (Ctrl+C to stop)
```

## Commands

| Command | Description |
|---------|-------------|
| `dev` | Preflight checks, docker compose up, health checks, pre-launch hooks, mprocs TUI. Docker tears down automatically on exit. |
| `infra` | Docker compose up + health checks. Blocks until Ctrl+C, then tears down. |
| Custom | Any `[[commands]]` entry defined in your TOML. |

## Configuration Reference

### Top-level

```toml
# Files that must exist before starting (checked in order)
env_files = [".env", "web/.env.local"]

# Commands that must be in PATH
required_tools = ["docker", "cargo", "node", "npm", "mprocs"]
```

Files listed in `env_files` are loaded into the process environment if they have no extension or a `.env` extension (e.g. `.env`, `.env.local`).

### `[docker]`

```toml
[docker]
compose_file = "docker-compose.yml"  # default
```

### `[[docker.health_checks]]`

Two types of health checks:

**Command-based** -- runs a command, success = exit code 0:
```toml
[[docker.health_checks]]
name = "postgres"
cmd = ["docker", "compose", "exec", "-T", "postgres", "pg_isready", "-U", "myuser"]
timeout = 30  # seconds, default 30
```

**URL-based** -- HTTP GET, success = 2xx response:
```toml
[[docker.health_checks]]
name = "minio"
url = "http://localhost:9000/minio/health/live"
timeout = 30
```

Health checks poll every 1 second until success or timeout.

### `[dev]`

```toml
[dev]
mprocs_config = "mprocs.yaml"  # default
```

### `[[dev.hooks]]`

Hooks run before mprocs launches. They execute via `sh -c`.

```toml
[[dev.hooks]]
cmd = "npm install"
cwd = "web"              # optional, relative to workspace root

[dev.hooks.condition]
missing = "web/node_modules"  # only run if this path doesn't exist
```

### `[[commands]]`

Define custom commands accessible via `cargo xtask <name>`:

```toml
[[commands]]
name = "migrate"
cmd = ["cargo", "run", "--release", "--package", "my-api", "--", "migrate"]
description = "Run database migrations"
docker = true  # start docker infra first (default: false)
```

## How It Works

```
cargo xtask dev
    |
    v
Preflight: check env files, load .env, verify tools
    |
    v
docker compose up -d
    |
    v
Health checks (poll until ready or timeout)
    |
    v
Pre-launch hooks (conditional)
    |
    v
mprocs --config mprocs.yaml  (interactive TUI)
    |
    v  (on exit / Ctrl+q)
docker compose down
```

## License

MIT