# wireguard-scripts

## M1 runtime foundation

The current entry point provides dependency-free `help` and `version` commands. The
planned operational commands are recognized but remain unavailable until later
milestones.

Runtime locations default to the project directory and can be redirected for an
isolated run with absolute paths using these environment variables:

`WG_MANAGER_CONFIG`, `WG_MANAGER_BACKUP_DIR`, `WG_MANAGER_LOG_DIR`,
`WG_MANAGER_METADATA_DIR`, `WG_MANAGER_ARCHIVE_DIR`, and `WG_MANAGER_LOCK_FILE`.

`WG_MANAGER_GUM` selects an executable `gum` explicitly; otherwise the bundled
`bin/gum` and then `PATH` are checked in that order. Configuration is parsed as
restricted `KEY=VALUE` data and is never executed as shell code. Blank lines and
full-line `#` comments are ignored; spaces around the key, `=`, and value are
trimmed. Values are either one unquoted token or a double-quoted value without
escapes, and only documented keys are accepted.

For deterministic read-only tests, `WG_MANAGER_NOW` may override the current
epoch when set to decimal seconds; invalid values are rejected.

M2 adds read-only `status` and `list`. They parse the configured WireGuard file
and, when available, `wg show <interface> dump`; a stopped or unavailable
runtime is reported as unavailable and disk-only peers remain visible. `list`
uses stable tab-separated output with English machine fields `state` and
`origin` (`managed`, `legacy`, or `unmanaged`) and never prints private or
preshared keys.

The explicit peer comment marker is `# wg-manager-client: NAME`; it is only a
display candidate. A peer is considered managed only when its exact public key
and configured addresses match a valid metadata record with `MANAGED=1`.

## M3 transaction foundation

The internal `run_transaction OPERATION TARGET BUILDER [METADATA_FILE...]`
primitive acquires `WG_MANAGER_LOCK_FILE`, then
reloads and validates the live configuration before calling its builder. It
creates a restrictive, timestamped backup, validates a same-filesystem staged
configuration with `wg-quick strip`, replaces the live file atomically, applies
it with `wg syncconf`, and verifies the active peer set. Apply or verification
failures restore both disk and runtime; a failed restoration is reported as a
critical rollback error. No M3 mutation command is exposed yet.

M3 tests use only isolated overrides and deny-by-default command mocks; they do
not inspect or modify host WireGuard state.