Metadata-Version: 2.4
Name: bam-tool
Version: 0.9.1
Summary: The simplicity of just. The power of Bazel. bam is a build and workflow tool with smart caching, parallel execution, and a beautiful live UI.
Project-URL: Homepage, https://gitlab.com/cascascade/bam
Project-URL: Repository, https://gitlab.com/cascascade/bam
Project-URL: Issues, https://gitlab.com/cascascade/bam/-/issues
Project-URL: Documentation, https://gitlab.com/cascascade/bam/-/blob/main/README.md
Author-email: ladidadida <stefan@dalada.de>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: cascache-lib>=0.1.0
Requires-Dist: networkx>=3.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: watchdog>=3.0.0
Description-Content-Type: text/markdown

# bam

**The simplicity of just. The power of Bazel.**

bam is a build and workflow tool that stays out of your way. Drop a YAML file in your project, list your tasks, and bam handles the rest — parallel execution, smart caching, dependency graphs, and a beautiful live UI — without asking you to restructure anything.

It scales from a one-person side project to a multi-team monorepo, and feels native to every stack.

## Quick Start

### Installation

```bash
# Using uv (recommended)
uv pip install bam-tool

# Using pip
pip install bam-tool
```

### Your First Workflow

Run `bam --init` in any project directory. bam detects your stack and writes a ready-to-run `bam.yaml`:

![bam --init wizard](docs/demo/init.gif)

The generated config is plain YAML — inputs, outputs, caching, and dependencies all wired up. Here's what it produces for a Node.js project:

```yaml
version: 1

tasks:
  install:
    command: npm ci
    inputs: [package.json, package-lock.json]
    outputs: [node_modules/]

  lint:
    command: npm run lint
    inputs: ["src/**/*"]
    depends_on: [install]

  test:
    command: npm test
    inputs: ["src/**/*", "tests/**/*"]
    depends_on: [lint]

  build:
    command: npm run build
    inputs: ["src/**/*"]
    outputs: [dist/]
    depends_on: [test]
```

Use `bam --graph` to visualise the dependency tree before running anything:

![bam --graph](docs/demo/graph.gif)

Then run the pipeline. Independent tasks execute in parallel automatically — bam shows live progress as a dependency tree:

![parallel execution](docs/demo/parallel.gif)

Run it again. Nothing changed, so every task restores from cache instantly:

![cache hit](docs/demo/cache.gif)

For long-running processes like dev servers, mark the task `interactive: true`. bam restores all dependencies from cache first, then hands the terminal directly to your process:

![interactive dev server](docs/demo/serve.gif)

```yaml
tasks:
  serve:
    command: npm run dev
    interactive: true
    depends_on: [build]
```

## Features

**Simple by design**
- Clean YAML config — no DSL to learn, no project restructuring required
- `bam <task>` to run; flags for everything else
- Shell tab completion for task names
- Works with any language or toolchain

**Powerful where it counts**
- Parallel execution out of the box — auto-detects CPU cores
- Content-addressed caching: tasks only re-run when inputs actually change
- Topological dependency resolution with cycle detection
- Docker and inline Python runners for hermetic or scripted steps
- Distributed cache to share hits across your whole team
- CI pipeline generation for GitHub Actions and GitLab CI

**Beautiful**
- Live dependency tree with per-task progress bars
- Rich error context: shows the full dependency chain and which tasks were skipped
- ASCII and DOT graph output for dependency visualisation
- Plain-output mode for CI/CD

## Use Cases

### Python Project

```yaml
version: 1

tasks:
  lint:
    command: ruff check src/
    inputs: ["src/**/*.py", "pyproject.toml"]

  typecheck:
    command: pyright
    inputs: ["src/**/*.py"]

  test:
    command: pytest
    inputs: ["src/**/*.py", "tests/**/*.py"]
    depends_on: [lint, typecheck]

  build:
    command: python -m build
    inputs: ["src/**/*.py", "pyproject.toml"]
    outputs: ["dist/"]
    depends_on: [test]
```

### Multi-Stage Build

```yaml
version: 1

tasks:
  generate:
    command: protoc --python_out=. schema.proto
    inputs: ["schema.proto"]
    outputs: ["schema_pb2.py"]

  build-backend:
    command: go build -o backend cmd/server/main.go
    inputs: ["cmd/**/*.go", "*.proto"]
    outputs: ["backend"]
    depends_on: [generate]

  build-frontend:
    command: npm run build
    inputs: ["src/**/*.ts"]
    outputs: ["dist/"]
    depends_on: [generate]

  package:
    command: docker build -t myapp .
    inputs: ["backend", "dist/", "Dockerfile"]
    depends_on: [build-backend, build-frontend]
```

## CLI Reference

bam uses a **flat command interface** — tasks run as `bam <task>`, management operations are flags.

### Running Tasks

```bash
bam build                  # Run a task (and all its dependencies)
bam build --jobs 8         # Use 8 parallel workers
bam build --jobs auto      # Auto-detect CPUs (default)
bam build --jobs 1         # Sequential
bam build --dry-run        # Show execution plan without running
bam build --no-cache       # Disable caching for this run
bam build --plain          # Plain output for CI/CD
```

**Live dependency tree:**

```
📦 Tasks
├── ✓ lint               ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
├── ✓ typecheck          ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
│   └── ✓ test           ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%
│       └── ✓ build      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100%

✓ Successfully executed 4 task(s)
```

**Error context:**

```
✗ Task failed: test
  Dependency chain:
    ├─ lint
    ├─ typecheck
    └─ test

⊘ Skipped 1 task(s) due to failure:
  • build
```

### Management Flags

```bash
bam --list              # List all configured tasks
bam --validate          # Validate config (YAML, deps, cycles)
bam --graph             # Show ASCII dependency graph
bam --graph-dot         # Output DOT format (pipe to Graphviz)
bam --clean             # Clean cache (prompts for confirmation)
bam --clean-force       # Clean cache without confirmation
bam --version           # Show version
```

### CI Pipeline Generation

```bash
bam --ci                # Generate CI pipeline (writes file)
bam --ci-dry-run        # Preview CI YAML without writing
bam --ci-output FILE    # Write to custom path
```

### Distributed Cache

Share cache across your team with a remote CAS server:

```yaml
cache:
  local:
    enabled: true
    path: .bam/cache
  remote:
    enabled: true
    url: grpc://cas.example.com:50051
    token_file: ~/.bam/cas-token
    timeout: 30.0
    max_retries: 3
```

Local cache is checked first; remote is a transparent fallback. Gracefully degrades on network errors. See [examples/remote-cache/](examples/remote-cache/) for a complete setup guide.

## Development

```bash
git clone https://gitlab.com/cascascade/bam.git
cd bam
uv sync
```

```bash
uv run ruff check src tests     # Lint
uv run pyright                  # Type checking
uv run pytest                   # Tests
bam build                       # Full build via bam
```

## Documentation

- [CLI Reference](https://gitlab.com/cascascade/bam/-/blob/main/docs/cli.md) — complete command documentation
- [Configuration Guide](https://gitlab.com/cascascade/bam/-/blob/main/docs/configuration.md) — full bam.yaml reference
- [Concept Document](https://gitlab.com/cascascade/bam/-/blob/main/docs/concept.md) — core concepts and design philosophy
- [Architecture](https://gitlab.com/cascascade/bam/-/blob/main/spec/architecture.md) — system design
- [Examples](https://gitlab.com/cascascade/bam/-/tree/main/examples/) — sample projects

## Contributing

Contributions welcome. Add tests for new functionality, follow PEP 8 and project code style, and run `bam build` before submitting.

## License

MIT — see [LICENSE](https://gitlab.com/cascascade/bam/-/blob/main/LICENSE).

---

**Built with:** Python 3.14+ · uv · Typer · Rich · NetworkX · Pydantic · Claude
