ahab/README.md

# ahab

A wrapper around `docker compose` for our dockerized Django projects, so the
same commands work in every repository.

It reads `docker compose config` to work out which service runs Django and
which one is the database, so nothing here takes a service name or a `-f`.
Everything it does, it does by running `docker`, `git` and the Postgres tools.

## Installing

You will need Rust installed. Clone the repo and run:

```bash
cargo install --path .
```

## Django

Each of these runs `docker compose run --rm` against the Django service, so it
goes through the image's own entrypoint:

```bash
ahab django run <cmd>                # anything, in a fresh container
ahab django bash                     # a shell in a fresh container
ahab django manage <args>            # manage.py
ahab django makemigrations
ahab django migrate <args>
ahab django shell
ahab django make-command <app> <name>
```

There is no `ahab django test`. Which runner a project uses is the project's
choice, and `manage.py test` exits 0 having collected nothing when the tests
are written for pytest, so a wrong guess reads as a pass. Name the runner
instead:

```bash
ahab django run pytest -x tests/
```

## Postgres

```bash
ahab postgres dump <path>             # pg_dump, custom format
ahab postgres dump -F plain <path>    # pg_dump, plain SQL
ahab postgres dump -F tar <path>      # pg_dump, tar
ahab postgres dump -F directory <d>   # pg_dump, a directory of files
ahab postgres dump -F cluster <path>  # pg_dumpall, roles and all databases
ahab postgres dump -F plain -z <path> # any of them, gzipped
ahab postgres import <path>           # drop, create, then restore
ahab postgres psql <args>             # psql in the database container
```

Dumps are written `0600`, under a name of their own until they are complete and
then renamed over the target. A cluster dump carries every role's password
hash, so the default `0644` would hand it to anyone else with an account.

Arguments reach `psql` untouched, and Docker is only asked for a terminal when
there is one to hand over, so both of these work:

```bash
ahab postgres psql                          # interactive
ahab postgres psql -tAc 'select count(*) from auth_user' | wc -l
```

### What an import makes of a dump

The shape is read from the file rather than from its name:

- a `PGDMP` or `toc.dat` header — an archive, restored with `pg_restore`, as is
  a directory produced by `pg_dump -Fd`
- a `pg_dumpall` header — a whole cluster, which creates its own databases and
  carries role statements, so the database is dropped but not recreated and the
  dump goes to `psql` connected to `postgres`
- gzip magic — decompressed on the way in, whichever of the three is inside
- anything else — SQL, fed to `psql` with `ON_ERROR_STOP` and
  `--single-transaction`, so a bad file rolls back instead of half applying

A cluster restore is the one that runs without `ON_ERROR_STOP`, because roles
that already exist report errors which are expected. Any other error fails the
import, since psql would otherwise exit 0 having applied part of the dump.
Importing into a cluster that has never held the database works either way.

Containers are stopped before an import starts, so one that fails leaves the
project stopped and says so.

## Link

A sandbox that mounts the repository can read anything untracked sitting in it
— a `.env`, a dump, a key. Those paths can be moved out to a store of ahab's
own and symlinked back, so the host resolves the link as before while the
sandbox is left with a symlink into somewhere it was never given.

```bash
ahab link add .env secrets/         # move out, leave symlinks behind
ahab link restore .env              # move it back into the repository
ahab link restore --all             # everything this repo has linked
ahab link list                      # what the store holds for this repository
ahab link check                     # what a sandbox can still read
ahab link check --porcelain         # `<code> <path>`, for scripts
ahab link check --exit-code         # exit 4 when anything is outside the store
```

Restoring is the inverse of adding: the file comes back to where it was and the
store keeps nothing. A second checkout linking the same path is left with a
dangling symlink, there being only ever one stored copy.

Every stored path is in one of three states, which `list` reads from the store
rather than from git:

```
$ ahab link list
store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik
	linked:    .env
	shadowed:  config.local.py
	missing:   secrets/token
```

- `linked` — the symlink is there and points at the store, which is the point
- `shadowed` — a real file took the path back, so nothing reads the stored copy
- `missing` — the symlink is gone, and nothing reads the stored copy either

Only a linked path can be moved back, so `restore --all` says how many it left
alone.

Two things adding will not do:

- **a tracked path**, which git would restore into the repository anyway. Where
  one is a symlink leading out, `check` reports it under the code `T>`, and
  saying so is all it can do
- **a symlink already leading out of the repository**, because moving the link
  would move the pointer and leave the contents where they are. The store would
  then hold a way back out, while `check` saw a link into the store and called
  the repository clean

For scripts there is `--porcelain`, and `-z` for filenames that need it:
entries end with a NUL, and the two paths of a symlink leading elsewhere are
separated by one as well, the way `git status -z` reports a rename.

The store lives under
`${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/`, derived
from the Git `origin` remote, or `_local/<checkout>` when there is no remote to
name it after. Two details of that:

- its directories are created `0700`, since it holds what should not be
  readable from the repository and `0755` would leave that to whoever else has
  an account on the machine
- a remote or checkout name that needed characters replacing carries a short
  fingerprint of the original, so two of them cannot land on one directory

## What ahab makes of your project

Running `ahab status` prints the services it picked, the containers behind
them, the credentials it would use and what the store holds. It reports
whatever it cannot work out rather than stopping at the first thing:

```
$ ahab status
services: db, django
django: django (built from the project)
	container: 0a8b19e27634
postgres: db (postgres:18-alpine)
	container: 189d4d395d62
	user:      myproject
	database:  myproject_db
store: /home/you/.local/share/ahab/git.aflabs.org/urnik/afurnik
	linked:    2
	`ahab link check` lists what a sandbox can still read
```

## Seeing what it runs

- `-v` — print each Docker command as it runs
- `--dry-run` — print the commands it would run, without running them
- `-q` — print only what was asked for, dropping the progress along the way,
  Compose's own included

All three work before or after the subcommand:

```bash
ahab -v django migrate
ahab --dry-run postgres import ./dump
ahab -q postgres dump ./dump
```

Nothing is written under `--dry-run`, the filesystem included: `link add` and
`django make-command` say what they would do and leave the tree alone.

## Service detection

Services can be named anything, since ahab looks at what they are rather than
what they are called:

- **postgres** — the service whose image is a Postgres flavour, matching
  `postg`, `timescale`, `pgvector` or `citus`
- **django** — the service that both builds an image and sets
  `DJANGO_SETTINGS_MODULE`. Where more than one does, a worker beside the web
  service say, the one publishing ports wins

If nothing matches, or two candidates cannot be told apart, ahab says so and
lists the services it looked at rather than guessing.

The role and database come from `POSTGRES_USER` and `POSTGRES_DB` on the
detected service, falling back to `db` when neither is set. Both have to be
names: libpq reads a database name holding an `=` or a URL as a whole
connection string, which would send a dump to whatever server that names, so a
value which could be read as anything but a name is refused.

## The compose file

Compose finds its own file and ahab does not pass `-f`, so set Docker's own
`COMPOSE_FILE` when the file is not in the working directory, including its
`base.yaml:override.yaml` form. A project's `.env` is a good place for it,
since Docker reads that too:

```
COMPOSE_FILE=docker/docker-compose.yaml
```

## Shell completion

Completion scripts are written to stdout, for Bash, Elvish, Fish, PowerShell
or Zsh:

```bash
ahab completions zsh > ~/.local/share/zsh/completions/_ahab
eval "$(ahab completions zsh)"      # or one line in .zshrc, never goes stale
```

They are generated during the build as well, landing in
`target/*/build/*/out/`. To install a single shell's file straight into place:

```bash
SHELL_COMPLETIONS_DIR_ZSH=~/.local/share/zsh/completions \
SHELL_COMPLETIONS_DIR_FISH=~/.config/fish/completions \
  cargo install --path .
```

Set `SHELL_COMPLETIONS_DIR` to write every shell into one directory instead.
Either way the path has to be absolute, since a build script runs from wherever
cargo happens to be building.

## Exit codes

- `0` — it ran and had nothing to report
- `1` — it could not finish
- `2` — the arguments were wrong
- `4` — it ran fine and found something worth reporting, which today means
  `link check --exit-code` with anything outside the store

## Environment variables

- `AHAB_LINK_ROOT` — where `ahab link` keeps its store, the same as `--store`,
  which takes precedence. Defaults to
  `${XDG_DATA_HOME:-$HOME/.local/share}/ahab`. Read by `ahab status` too, so it
  reports the store the link commands actually use