# {{APP_NAME}}

A Statum + Spry application, scaffolded by `spry new`.

## Development

```bash
spry dev
```

Builds, runs the app on port 8080 (`--port N` to change) and watches
`src/`, `meson.build` and `web-config.json`: saving a file rebuilds
incrementally — page HTML and resources recompile via the meson codegen
targets — and restarts the app when the build succeeds. A failed build
keeps the previous process running while the compiler errors are shown.
Restarts are cheap: Statum state is client-carried (the browser recovers
transparently) and the static keys in `web-config.json` keep sessions
alive — just refresh. `--fresh` starts from an empty database;
`--no-run` builds once and exits.

The environment below is required for the underlying meson builds (the
`spry dev` child processes set it for you; export it in shells where you
build or run manually):

```bash
export WS_PREFIX="$HOME/.local"
export PKG_CONFIG_PATH="$WS_PREFIX/lib64/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
export XDG_DATA_DIRS="$WS_PREFIX/share${XDG_DATA_DIRS:+:$XDG_DATA_DIRS}"
export LD_LIBRARY_PATH="$WS_PREFIX/lib64${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}"

meson setup builddir
ninja -C builddir
./builddir/{{APP_NAME}}
```

The server listens on port 8080 (pass another port as the first argument).
Static signing/encryption keys live in `web-config.json` (written by `spry
keys`; gitignored and mode 0600 — never commit it or bake it into images),
so sessions survive a restart. The SQLite store is `./{{APP_NAME}}.sqlite`,
or `SPRY_DB_PATH` when that variable is set.

An admin account is seeded on boot only when BOTH `SPRY_SEED_ADMIN_USERNAME`
and `SPRY_SEED_ADMIN_PASSWORD` are set (the password is never logged);
seeding is skipped silently otherwise:

```bash
export SPRY_SEED_ADMIN_USERNAME=admin
export SPRY_SEED_ADMIN_PASSWORD=change-me
```

## Layout

| Path | Purpose |
|---|---|
| `src/main.vala` | application wiring: modules, database, pages, actions |
| `src/pages/*.html` | Statum pages, compiled to Vala by `statum-mkpstm` at build time |
| `src/entrypoints/` | one `StatumEntrypoint` per page |
| `src/actions/` | `StatumAction` subclasses |
| `src/resources/` | static resources embedded by `statum-mkres` |
| `web-config.json` | static keys and other configuration (gitignored, 0600) |

Registrations live between `// spry:*-begin/end` markers in `src/main.vala`,
`# spry:*-begin/end` markers in `meson.build` and `<!-- spry:nav-begin/end -->`
markers in `src/pages/main.html` (the layout's nav, plus the logged-in-only
`<!-- spry:nav-auth-begin/end -->` block); the `spry add` commands edit only
those blocks and are idempotent.

## Growing the app

```
spry dev
spry add page <name> [--route /path]
spry add action <name>
spry add resource <file>
spry add login
spry add register
spry add user-management
spry keys
spry docker
```

`add login`, `add register` and `add user-management` also grow the layout
nav (a Login/Register link when logged out, a Log-out button once login is
added, a Users link for admins) inside the nav markers.

## Docker

`spry docker [--stack-dir <path>] [--tag <tag>]` generates the multi-stage
`Dockerfile` and `.dockerignore`. The Web-Stack trees carry fixes not on
their remotes, so the image build COPYs every stack library from the local
Web-Stack checkout: `spry docker` assembles the context itself (default
stack dir: the app's sibling directory; override with `--stack-dir`). Only
inversion is cloned inside the image, pinned to a reviewed commit. The
context layout the Dockerfile expects is:

```
<context>/invercargill                ← Web-Stack/Invercargill
<context>/invercargill-json           ← Web-Stack/Invercargill-Json
<context>/astralis                    ← Web-Stack/astralis
<context>/invercargill-sql            ← Web-Stack/Invercargill-Sql
<context>/invercargill-sql-inversion  ← Web-Stack/Invercargill-Sql-Inversion
<context>/statum                      ← Web-Stack/Statum
<context>/spry                        ← Web-Stack/Spry
<context>/app                         ← this application
```

The base image is pinned by digest; refresh it with
`skopeo inspect docker://docker.io/library/fedora:43` and update both
`FROM` lines. The inversion commit is pinned too — bump it in lockstep with
the local checkout when it changes.

`web-config.json` is excluded from the build context (`.dockerignore`), so
keys are never baked into the image: mount the config read-only at runtime
and keep the SQLite store in the declared volume:

```bash
podman run -p 8080:8080 \
    -v $PWD/web-config.json:/app/web-config.json:ro \
    -v {{APP_NAME}}-data:/var/lib/{{APP_NAME}} \
    {{APP_NAME}}
```

To build by hand, recreate the layout above and run
`podman build -f Dockerfile -t {{APP_NAME}} <context>`.