Metadata-Version: 2.4
Name: bluefox-yml
Version: 0.1.0
Summary: Parser and validator for bluefox.yml app manifests
Project-URL: Homepage, https://bluefox-yml.bluefox.software
Project-URL: Documentation, https://bluefox-yml.bluefox.software/docs/
Project-URL: Repository, https://github.com/blue-fox-software/bluefox-yml
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Description-Content-Type: text/markdown

# bluefox-yml

Parser and validator for `bluefox.yml` app manifests.

Define your application's compute, data, and in-memory primitives in a single YAML file. `bluefox-yml` validates the manifest and provides typed access to every field.

Part of the [Bluefox Stack](https://bluefox-stack.bluefox.software).

[Documentation](https://bluefox-yml.bluefox.software/docs/) &middot; [PyPI](https://pypi.org/project/bluefox-yml/)

---

## Install

```bash
uv add bluefox-yml
```

---

## Quick start

Create a `bluefox.yml` in your project root:

```yaml
version: 1
name: my-saas

compute:
  app:
    port: 8000
  worker: {}

data:
  engine: postgres
  version: 17
  migrate: "uv run alembic upgrade head"
```

Load and validate it:

```python
from bluefox_yml import load_manifest

manifest = load_manifest("bluefox.yml")

print(manifest.name)                    # "my-saas"
print(manifest.compute["app"].port)     # 8000
print(manifest.data.engine)             # "postgres"
print(manifest.routable_process())      # ("app", ComputeProcess(...))
```

---

## What it does

- **Schema validation** — catches invalid manifests early with clear error messages.
- **DNS-safe names** — enforces lowercase, alphanumeric, hyphenated names (3-63 chars).
- **Engine constraints** — only allows supported engines (`postgres`, `redis` in v1).
- **Single routable process** — ensures at most one compute process declares a port.
- **Healthcheck defaults** — auto-injects `/health` for processes with a port.
- **Helper methods** — `service_name()`, `image_tag()`, `db_image()`, `env_vars()`, and more.
- **Reserved name guard** — prevents `bluefox-*` prefixed names (reserved for platform services).

---

## Error handling

```python
from bluefox_yml import load_manifest, format_error, ManifestError

try:
    manifest = load_manifest("bluefox.yml")
except ManifestError as e:
    print(format_error(e))
```

---

## Documentation

Full docs at [bluefox-yml.bluefox.software/docs/](https://bluefox-yml.bluefox.software/docs/)

- [Getting started](https://bluefox-yml.bluefox.software/docs/getting-started/) — install and write your first manifest
- [Reference](https://bluefox-yml.bluefox.software/docs/reference/manifest/) — full API documentation
