feat: witryna 0.2.0HEADv0.2.0main

Switch, cleanup, and status CLI commands. Persistent build state via
state.json. Post-deploy hooks on success and failure with
WITRYNA_BUILD_STATUS. Dependency diet (axum→tiny_http, clap→argh,
tracing→log). Drop built-in rate limiting. Nix flake with NixOS module.
Arch Linux PKGBUILD. Centralized version management.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2 files changed, 142 insertions, 13 deletions

diff --git a/man/witryna.1 b/man/witryna.1
new file mode 100644
index 0000000..473d395
--- /dev/null
+++ b/man/witryna.1
@@ -0,0 +1,131 @@
+.TH witryna 1 2026-02-15 "witryna 0.2.0"
+.SH NAME
+witryna \- Minimalist Git\-based static site deployment orchestrator
+.SH SYNOPSIS
+\fBwitryna\fR <\fIcommand\fR> [\fB\-\-config\fR \fIFILE\fR] [\fIargs\fR]
+.SH DESCRIPTION
+Minimalist Git\-based static site deployment orchestrator.
+.PP
+Witryna listens for webhook HTTP requests, pulls the corresponding Git
+repository (with automatic Git LFS fetch and submodule initialization),
+runs a user\-defined build command inside an ephemeral container and
+publishes the resulting assets via atomic symlink switching.
+.PP
+A health\-check endpoint is available at GET /health (returns 200 OK).
+.PP
+Witryna does not serve files, terminate TLS, or manage DNS.
+It is designed to sit behind a reverse proxy (Nginx, Caddy, etc.).
+.SH "SUBCOMMANDS"
+.TP
+\fBserve\fR [\fB\-\-config\fR \fIFILE\fR]
+Start the deployment server (foreground).
+.TP
+\fBvalidate\fR [\fB\-\-config\fR \fIFILE\fR]
+Validate configuration file and print summary.
+.TP
+\fBrun\fR [\fB\-v\fR|\fB\-\-verbose\fR] [\fB\-\-config\fR \fIFILE\fR] \fIsite\fR
+Trigger a one\-off build for a site (synchronous, no server).
+Use \fB\-v\fR to stream full build output to stderr in real\-time.
+.TP
+\fBstatus\fR [\fB\-\-json\fR] [\fB\-\-config\fR \fIFILE\fR] [\fIsite\fR]
+Show deployment status for configured sites.
+If \fIsite\fR is given, show the last 10 deployments for that site.
+Use \fB\-\-json\fR for machine\-readable JSON output.
+A \fB+\fR marker indicates the active deployment (the build the \fBcurrent\fR symlink points to).
+.TP
+\fBswitch\fR [\fB\-\-config\fR \fIFILE\fR] \fIsite\fR \fIbuild\fR
+Switch the active build for a site. Atomically updates the \fBcurrent\fR symlink
+to point to the specified build timestamp. Use \fBwitryna status\fR \fIsite\fR to
+list available builds with their timestamps. Does not run post\-deploy hooks.
+.TP
+\fBcleanup\fR [\fB\-\-keep\fR \fIN\fR] [\fB\-\-config\fR \fIFILE\fR] [\fIsite\fR]
+Remove old builds and logs.
+If \fIsite\fR is given, clean only that site; otherwise clean all.
+\fB\-\-keep\fR \fIN\fR overrides the \fBmax_builds_to_keep\fR config value.
+.SH OPTIONS
+.TP
+\fB\-\-config\fR \fIFILE\fR
+Path to the configuration file (available on every subcommand).
+If not specified, searches: ./witryna.toml, $XDG_CONFIG_HOME/witryna/witryna.toml,
+/etc/witryna/witryna.toml.
+.TP
+\fB\-\-help\fR
+Print help information.
+.SH "SIGNALS"
+.TP
+\fBSIGHUP\fR
+Reload configuration from \fIwitryna.toml\fR without restarting the server.
+Sites can be added, removed, or modified on the fly.
+Changes to \fBlisten_address\fR, \fBbase_dir\fR, \fBlog_dir\fR,
+and \fBlog_level\fR are detected but require a full restart to take effect;
+a warning is logged when these fields differ.
+.TP
+\fBSIGTERM\fR, \fBSIGINT\fR
+Initiate graceful shutdown.
+In\-progress builds are allowed to finish before the process exits.
+.SH "EXIT STATUS"
+.TP
+\fB0\fR
+Clean shutdown after SIGTERM/SIGINT (\fBserve\fR), configuration valid (\fBvalidate\fR),
+build succeeded (\fBrun\fR), status displayed (\fBstatus\fR), or build switched (\fBswitch\fR).
+Post\-deploy hook failure is non\-fatal and still exits 0.
+Hooks run on both successful and failed builds.
+.TP
+\fB1\fR
+Startup failure, validation error, build failure, site not found, configuration error,
+or command\-line usage error (unknown flag, missing subcommand, etc.).
+.SH "INSTALLATION"
+When installed via deb or rpm packages, the post\-install script automatically
+detects the available container runtime and configures system\-level access:
+.TP
+\fBDocker\fR
+The \fBwitryna\fR user is added to the \fBdocker\fR group and a systemd
+override is installed at
+\fI/etc/systemd/system/witryna.service.d/10\-runtime.conf\fR
+granting access to the Docker socket.
+.TP
+\fBPodman\fR
+Subordinate UID/GID ranges are allocated (100000\-165535), user lingering is
+enabled, and a systemd override is installed that disables
+\fBRestrictNamespaces\fR and sets \fBXDG_RUNTIME_DIR\fR.
+.PP
+If neither runtime is found at install time, a warning is printed.
+Install a runtime and reinstall the package, or manually copy the appropriate
+override template from \fI/usr/share/doc/witryna/examples/systemd/\fR to
+\fI/etc/systemd/system/witryna.service.d/10\-runtime.conf\fR.
+.SH "FILES"
+.TP
+\fI/etc/witryna/witryna.toml\fR
+Conventional configuration path for system\-wide installs.
+The shipped systemd unit passes \fB\-\-config /etc/witryna/witryna.toml\fR
+explicitly; without \fB\-\-config\fR the CLI defaults to \fIwitryna.toml\fR
+in the current working directory.
+.TP
+\fI/var/lib/witryna/clones/<site>/\fR
+Git repository clones.
+.TP
+\fI/var/lib/witryna/builds/<site>/<timestamp>/\fR
+Timestamped build outputs.
+.TP
+\fI/var/lib/witryna/builds/<site>/current\fR
+Symlink to the latest successful build.
+.TP
+\fI/var/lib/witryna/builds/<site>/state.json\fR
+Current build state (building, success, failed, hook\ failed).
+Written atomically at each pipeline phase; read by \fBwitryna status\fR
+to show in\-progress builds with elapsed time.
+.TP
+\fI/var/lib/witryna/cache/<site>/\fR
+Persistent build cache volumes.
+.TP
+\fI/var/log/witryna/<site>/<timestamp>.log\fR
+Per\-build log files (site, timestamp, git commit, image, duration, status, stdout, stderr).
+.TP
+\fI/var/log/witryna/<site>/<timestamp>\-hook.log\fR
+Post\-deploy hook output (if configured).
+.SH "SEE ALSO"
+\fBwitryna.toml\fR(5)
+.SH VERSION
+v0.2.0
+.SH AUTHORS
+Dawid Rycerz
diff --git a/man/witryna.toml.5 b/man/witryna.toml.5
index 29c0331..78a6ece 100644
--- a/man/witryna.toml.5
+++ b/man/witryna.toml.5
@@ -1,11 +1,11 @@
-.TH WITRYNA.TOML 5 "2026-02-10" "witryna 0.1.0" "Witryna Configuration"
+.TH WITRYNA.TOML 5 "2026-02-15" "witryna 0.2.0" "Witryna Configuration"
 .SH NAME
 witryna.toml \- configuration file for \fBwitryna\fR(1)
 .SH DESCRIPTION
 \fBwitryna.toml\fR is a TOML file that configures the \fBwitryna\fR static site
 deployment orchestrator.
 It defines the HTTP listen address, container runtime, directory layout,
-logging, rate limiting, and zero or more site definitions with optional build
+logging, and zero or more site definitions with optional build
 overrides, polling intervals, cache volumes, and post\-deploy hooks.
 .PP
 The file is read at startup and can be reloaded at runtime by sending
@@ -38,13 +38,9 @@ Directory for per\-build log files.
 Layout: \fI<log_dir>/<site>/<timestamp>.log\fR
 .TP
 \fBlog_level\fR = "\fIlevel\fR" (required)
-Tracing verbosity.
+Log verbosity.
 Valid values: "trace", "debug", "info", "warn", "error" (case\-insensitive).
 Can be overridden at runtime with the \fBRUST_LOG\fR environment variable.
-.TP
-\fBrate_limit_per_minute\fR = \fIn\fR (optional, default: 10)
-Maximum webhook requests per token per minute.
-Exceeding this limit returns HTTP 429.
 .PP
 \fBNote:\fR The server enforces a hard 1\ MB request body size limit.
 This is not configurable and applies to all endpoints.
@@ -54,6 +50,7 @@ Number of timestamped build directories to retain per site.
 Older builds and their corresponding log files are removed after each
 successful publish.
 Set to 0 to disable cleanup (keep all builds).
+See also: \fBwitryna cleanup\fR for manual pruning.
 .TP
 \fBgit_timeout\fR = "\fIduration\fR" (optional, default: "1m")
 Maximum time allowed for each git operation (clone, fetch, reset, submodule update).
@@ -309,7 +306,7 @@ Witryna\-internal values.
 .SH POST-DEPLOY HOOKS
 .TP
 \fBpost_deploy\fR = ["\fIcmd\fR", "\fIarg\fR", ...] (optional)
-Command to execute after a successful symlink switch.
+Command to execute after every build completion (success or failure).
 Uses array form (no shell interpolation) for safety.
 .RS
 The hook receives context exclusively via environment variables:
@@ -327,6 +324,9 @@ Use this as the web server document root.
 .TP
 \fBWITRYNA_BUILD_TIMESTAMP\fR
 Build timestamp (YYYYmmdd-HHMMSS-ffffff).
+.TP
+\fBWITRYNA_BUILD_STATUS\fR
+Build outcome: "success" or "failed".
 .PP
 The hook runs with a minimal environment: any user\-defined variables
 from \fB[sites.env]\fR, followed by PATH, HOME, LANG,
@@ -336,8 +336,9 @@ It is subject to a 30\-second timeout and killed if exceeded.
 Output is streamed to disk and logged to
 \fI<log_dir>/<site>/<timestamp>\-hook.log\fR.
 .PP
-Hook failure is \fBnon\-fatal\fR: the deployment is already live,
-and a warning is logged.
+Hook failure is \fBnon\-fatal\fR and a warning is logged.
+On successful builds the deployment is already live; on failed builds
+the hook still runs but no assets were published.
 The exit code is recorded in the hook log.
 A log file is written for every hook invocation (success, failure,
 timeout, or spawn error).
@@ -393,9 +394,6 @@ log_dir = "/var/log/witryna"
 # Tracing verbosity
 log_level = "info"
 
-# Webhook rate limit (per token, per minute)
-rate_limit_per_minute = 10
-
 # Keep the 5 most recent builds per site
 max_builds_to_keep = 5