Metadata-Version: 2.3
Name: punix
Version: 0.1.1
Summary: Punix v2 — a typed, order-independent declarative build & multi-backend service deployer on the inheritance-calculus model
Author: Stefane Fermigier
Author-email: Stefane Fermigier <sf@abilian.com>
License: Apache 2.0
Requires-Dist: mixinv2
Requires-Dist: cyclopts>=3.24.0
Requires-Dist: tabulate>=0.10.0
Requires-Python: >=3.13
Description-Content-Type: text/markdown

# Punix

**Install tools, set up machines, deploy apps — without breaking anything.**

Punix is a package manager and service deployer for macOS and Linux. Every install is reversible, every deploy can be rolled back in one second, and the same workflow runs on your laptop, your VPS, or any host you can reach over SSH.

## What you get

- **Reproducible, from-source builds.** Each package builds into its own hash-named directory in a content-addressed store. The same recipe and sources produce a bit-for-bit identical result — the build you run today and the one you run in two years match, even if the upstream tarball server is long gone.
- **Atomic installs and updates.** Your active profile is a directory of symlinks on your `$PATH`. Installing, updating, or switching to "the set I had last week" flips the live state in a single syscall. Uninstall is exact — no leftover files, no broken links. Two versions of the same tool can coexist.
- **One-second rollback.** Every deploy is a complete numbered snapshot; the previous one stays whole on disk. Rollback just repoints a symlink — no rebuild, no reconfigure, no replay. There is no half-deployed state, even after a power loss mid-deploy.
- **Deploy anywhere, one command.** Describe your stack once — config files, binaries, and service units — and target `systemd`, `launchd`, `supervisord`, `docker-compose`, or a remote host over plain SSH. SSH deploys use real `ssh`/`rsync` with no agent or daemon on the target; only content that's actually new is transferred.
- **A configuration language that catches mistakes early.** Recipes and stacks are written in PCL and type-checked end-to-end *before any build runs*. A typo, a missing dependency, a bad URL shows up instantly with a `file:line:col` location — not at minute 11 of a 12-minute build.

## Install

```sh
curl -fsSL https://punix.lab.abilian.com/install.sh | sh
```

The installer prints what it will do and pauses before doing it. It only writes under `~/.punix/`, and it plays nicely with an existing Homebrew setup. Prefer Python packaging? `pip install punix` works too (Python 3.13+). See the [install guide](https://punix.lab.abilian.com/getting-started/install/) for other paths.

## A quick taste

Install a few tools into your profile:

```sh
punix install ripgrep fd wget
```

Or describe a package or stack in PCL:

```pcl
module curl {
  version = "8.20.0"
  recipe  = "std.autotools"
  source  = {
    type = "url"
    url  = "https://curl.se/download/curl-8.20.0.tar.xz"
    hash = "63fe2dc1...e2b896"
  }
  deps = [openssl.pname, zlib.pname]
}
```

…then check it, deploy it, and roll back if you need to:

```sh
punix check stack.pcl                          # type-check, no build
punix service deploy MyStack --file stack.pcl  # → gen-002
punix service rollback MyStack                 # → gen-001, instantly
```

Deploy to a server instead — same file, same command, just add a target:

```sh
punix service deploy MyStack --file stack.pcl --target ssh://you@server
```

## Why not just use…?

- **Homebrew** — great for installing tools, but not a service deployer, and `brew update` can move installed paths underneath you. Punix coexists with it.
- **Nix** — the same content-addressed store and correctness model, with a typed, lighter configuration language.
- **Ansible** — built to mutate existing hosts step by step; Punix replaces a host's app stack atomically and rolls the whole thing back in one move.
- **Docker Compose** — Punix can drive a Compose stack as one of its backends.

There's a [fuller comparison](https://punix.lab.abilian.com/concepts/why-punix/) in the docs.

## Documentation

Full docs live at **[punix.lab.abilian.com](https://punix.lab.abilian.com)**:

- [Install → first build → first deploy](https://punix.lab.abilian.com/getting-started/install/)
- [The PCL configuration language](https://punix.lab.abilian.com/language/overview/)
- [Deploy, rollback, and SSH](https://punix.lab.abilian.com/deploy/ssh/)
- [CLI reference](https://punix.lab.abilian.com/cli/overview/)
- [What works today and the roadmap](https://punix.lab.abilian.com/status/what-works/)

Runnable demos live in [`examples/`](examples/) — start with [`examples/hello`](examples/hello) for a first build, or [`examples/tangled-deploy`](examples/tangled-deploy) for a real server built from source with HTTPS, secrets, and reboot-persistence.

## Contributing

```sh
uv sync            # set up the environment (needs uv + Python 3.13+)
make test          # run the test suite
make lint          # ruff + type checkers
```

Every advertised property is backed by a conformance test that gates each release. Punix is under active development — contributions and issues are welcome.

## License

MIT.
