wireguard-scripts/AGENTS.md

AGENTS.md

Scope

• These rules apply to the entire repository.
• Build a local WireGuard management tool for Linux servers.
• Keep wg-manager.sh as the primary entry point.
• The project is copied as a directory and is not installed into PATH.
• Do not add installer or uninstaller scripts unless explicitly requested.
• Treat MVP.md as the product scope and acceptance reference.
• Treat PLANS.md as the required milestone sequence for MVP implementation.
• Complete and verify one milestone before starting the next one.
• Update the PLANS.md progress and execution log as milestones are completed.
• Run milestones under the Sol coordinator and Luna worker/reviewer loop defined in PLANS.md and .codex/.
• The coordinator must independently review Luna's changes and delegate explicit Luna repairs until verification passes or a genuine blocker remains.
• Use the existing add-user.sh only as a behavioral reference.
• New code must improve its safety rather than copy its weaknesses.

General priorities

• Preserve a working WireGuard configuration above all else.
• Prefer correctness and recoverability over cleverness.
• Keep CLI behavior independent from the TUI.
• Make every mutating operation explicit and auditable.
• Keep secrets out of output, logs, tests, and error messages.
• Minimize required dependencies.
• Support operation over SSH and ordinary terminal emulators.
• Write user-facing text in Russian unless the surrounding interface uses another language.
• Keep identifiers, functions, CLI command names, and code comments in English.
• Avoid unrelated refactors while implementing a focused change.

Bash baseline

• Use Bash, not POSIX sh.
• Start executable scripts with #!/usr/bin/env bash.
• Enable set -Eeuo pipefail in production entry points.
• Understand strict-mode exceptions before suppressing them.
• Use if command; then when a nonzero status is expected.
• Do not append || true unless the ignored failure is intentional and documented.
• Set umask 077 before creating configs, keys, metadata, logs, or backups.
• Require a supported Bash version at startup when using version-specific features.
• Prefer Bash builtins over unnecessary subprocesses.
• Use printf rather than echo -e.
• Use [[ ... ]] for Bash conditionals.
• Use (( ... )) for arithmetic conditions.
• Use case for command dispatch and finite state handling.
• Use local for function-local variables.
• Declare variables close to first use.
• Use readonly for constants after configuration is loaded.
• Use uppercase names only for exported variables and true constants.
• Use lowercase snake_case for local variables and functions.
• Give functions verb-based names such as load_config or add_client.
• Keep functions focused and normally below about 60 lines.
• Return statuses from functions; print data only when output is the contract.
• Do not mix machine-readable results with progress messages.
• Send errors and diagnostics to stderr.
• Use explicit exit codes for expected CLI failure categories.

Quoting and data handling

• Double-quote parameter expansions unless splitting is deliberately required.
• Use "${array[@]}" when forwarding array elements.
• Use arrays to build commands; never construct commands as strings.
• Never use eval.
• Never pass user-controlled text to bash -c.
• Avoid command substitution for multiline or NUL-sensitive data.
• Use mapfile -t for line-oriented command output when appropriate.
• Use IFS= read -r to read literal lines.
• Use read -r -d '' or NUL delimiters for arbitrary file names.
• Use -- before user-derived positional arguments where supported.
• Do not rely on locale-sensitive parsing.
• Set LC_ALL=C locally for command output that must be parsed predictably.
• Do not parse human-formatted output when a stable dump format exists.
• Prefer wg show <interface> dump for WireGuard state parsing.
• Treat names, endpoints, addresses, paths, and config values as untrusted input.
• Validate input with allowlists and semantic checks.
• Reject control characters and embedded newlines in user input.
• Never derive a filesystem path from an unchecked client name.
• Canonicalize or constrain paths before reading or writing them.

Configuration

• Keep server-specific values in wg-manager.conf.
• Resolve the project directory from ${BASH_SOURCE[0]}.
• Do not depend on the caller's current working directory.
• Do not silently overwrite administrator configuration.
• Validate every required setting at startup.
• Reject unknown enum values such as unsupported tunnel modes.
• Validate numeric ranges before arithmetic use.
• Validate IPv4, IPv6, CIDR, port, and hostname values before use.
• Do not source a configuration file that may be writable by untrusted users.
• If sourcing is retained, require root ownership and non-group/world-writable permissions.
• Prefer a restricted KEY=VALUE parser for long-term safety.
• Environment overrides must be documented and narrowly scoped.
• Never accept key material through command-line arguments.
• Avoid exporting secrets into the process environment.

Temporary files and cleanup

• Create temporary files with mktemp.
• Create mutation staging files on the same filesystem as the target.
• Never use predictable temporary filenames.
• Register cleanup immediately after creating temporary resources.
• Use a cleanup function with trap for EXIT, INT, and TERM.
• Quote trap bodies safely; avoid premature expansion.
• Preserve the original exit status during cleanup.
• Do not remove a path unless this process created it or validated it exactly.
• Apply restrictive permissions before writing secret content.
• Do not leave key material in world-readable temporary directories.

WireGuard safety

• Require root only for commands that need privileged access or mutation.
• Allow safe read-only commands without root when system permissions permit it.
• Check that the configured interface and config file agree.
• Identify peers by public key, not only by display name.
• Treat comments such as ### Client NAME as metadata, not identity.
• Detect duplicate public keys and overlapping AllowedIPs.
• Detect address collisions before generating any persistent file.
• Distinguish managed peers from unmanaged peers.
• Never modify an unmanaged peer implicitly.
• Do not regenerate server keys automatically.
• Do not rotate or replace client keys without explicit confirmation.
• Never print private or preshared keys in routine output.
• Never include key values in traces or debug logs.
• Disable shell tracing around all secret-handling code.
• Store client files with mode 0600.
• Keep directories containing client material at mode 0700.

Mutating operations

• Serialize mutations with flock.
• Acquire the lock before re-reading mutable state.
• Revalidate assumptions after the lock is acquired.
• Create a backup before every persistent change.
• Write the complete proposed config to a staging file.
• Validate the staged config before replacing the live config.
• Preserve the target owner, group, and restrictive mode.
• Replace files atomically with a same-filesystem rename.
• Apply the new configuration only after durable storage succeeds.
• Verify active state after applying the change.
• Roll back both disk and runtime state on failure.
• Report rollback failure as a critical error.
• Never append directly to the live WireGuard config.
• Never use broad text deletion to remove a peer block.
• Match an exact managed block and its public key.
• Default to archiving client files instead of permanent deletion.
• Require explicit confirmation before destructive or restorative actions.
• Make repeated operations fail safely or behave idempotently.

Backups and audit log

• Timestamp backups in an unambiguous UTC format.
• Include the interface name in backup metadata or filenames.
• Keep a bounded number of automatic backups.
• Never prune the only known-good backup.
• Validate a backup before offering restoration.
• Back up the current state before restoring an older state.
• Record who initiated a mutation when that information is available.
• Log the operation, target, timestamp, outcome, and concise error.
• Do not log private keys, preshared keys, or full client configs.
• Avoid logging full environment dumps or command lines with secrets.
• Make logs readable only by root by default.
• Log failed mutations and rollback outcomes.

CLI design

• TUI actions must call the same backend functions as CLI commands.
• Keep CLI commands usable when gum is unavailable.
• Provide help and useful usage errors.
• Reject unknown commands and extra positional arguments.
• Keep command names stable once documented.
• Use stdout for requested data and stderr for warnings or progress.
• Do not add decorative ANSI output when stdout is not a terminal.
• Honor NO_COLOR for CLI colors where colors are used.
• Return zero only when the requested operation succeeded.
• Use distinct nonzero statuses for usage, validation, dependency, and runtime errors.
• Avoid interactive prompts when a CLI command is explicitly noninteractive.
• Require a confirmation flag for destructive noninteractive commands.
• Never let localization change machine-parsed values or exit codes.

TUI with gum

• Use gum as the only planned TUI framework.
• Do not add dialog, whiptail, or a second TUI framework.
• Do not download or install gum from the application.
• Resolve gum in this order: WG_MANAGER_GUM, local bin/gum, then PATH.
• Validate that the resolved path is executable.
• Check required gum subcommands or minimum version at startup.
• Fail with a clear message when TUI is requested without usable gum.
• Keep all gum invocation details in small UI wrapper functions.
• Backend functions must never call gum directly.
• Use gum choose for short finite menus.
• Use gum filter for searchable client selection.
• Use gum input for short validated text fields.
• Use gum confirm before deletion, restoration, or key rotation.
• Use gum table only for display or selection, not as a data store.
• Use gum pager for logs, diagnostics, and long text.
• Use gum spin only when the wrapped operation can safely hide routine output.
• Preserve stderr from failed commands behind a spinner.
• Never show secret content inside a spinner command line.
• Keep stable internal values separate from translated display labels.
• Treat cancellation and Escape as normal control flow, not an error.
• Return to the previous screen after cancellation.
• Do not trap users in an endless menu loop after repeated failures.
• Keep the main menu shallow and task-oriented.
• Show interface name and current status on the main screen.
• Use consistent verbs: view, add, remove, diagnose, restore, exit.
• Show the exact target before asking for destructive confirmation.
• Require stronger confirmation for restoring backups or deleting client material.
• Keep colors readable on light and dark terminals.
• Do not communicate status by color alone.
• Keep layouts usable at 80 columns.
• Avoid assumptions about mouse support.
• Do not clear valuable terminal output after an error.
• Detect noninteractive stdin or stdout before starting TUI.
• Never emit TUI control output into pipelines or redirected files.

Error handling

• Provide one concise user-facing error plus actionable context.
• Preserve the failing command's status where meaningful.
• Do not expose secret variable values in error messages.
• Distinguish validation errors from system failures.
• Distinguish skipped diagnostic checks from successful checks.
• Diagnostic results use OK, WARN, FAIL, or SKIP.
• A critical diagnostic failure must produce a nonzero status.
• Include remediation guidance when it is reliable and specific.
• Avoid guessing firewall fixes across distributions.
• Continue independent diagnostic checks after a nonfatal failure.

Dependencies and portability

• Assume a Linux server with Bash and WireGuard tools.
• Keep required dependencies listed in MVP.md and README.
• Treat qrencode, systemd, nft, and iptables as optional capabilities.
• Detect optional commands before using them.
• Do not fail the entire diagnostic run because one optional tool is absent.
• Prefer feature detection over distribution detection.
• Do not assume systemd is PID 1 on every supported server.
• Support at least Linux x86_64; document additional tested architectures.
• Do not assume the bundled gum binary matches the current architecture.
• Report architecture mismatch clearly.

Tests

• Add regression tests for every fixed bug.
• Tests must not modify the host's real /etc/wireguard.
• Use fixtures for server configs, peer blocks, and metadata.
• Mock external commands through a controlled test PATH.
• Cover wg, wg-quick, ip, systemctl, journalctl, nft, and iptables as needed.
• Test success, expected failure, rollback, and interruption paths.
• Test client names containing spaces, newlines, glob characters, and option prefixes.
• Test duplicate keys, duplicate IPs, and overlapping networks.
• Test empty peer lists and unmanaged peers.
• Test CLI behavior without gum.
• Test local binary, environment override, and PATH resolution for gum.
• Test that logs do not contain generated secrets.
• Test concurrent mutation attempts.
• Test restoration failure and failed rollback reporting.
• Keep tests deterministic; do not depend on external network access.
• Use temporary test directories and remove them safely.

Quality gates

• Run bash -n on every changed shell script.
• Run ShellCheck on every changed shell script when available.
• Run the relevant automated tests.
• Format consistently; use shfmt when the project adopts a fixed style.
• Do not silence ShellCheck globally to hide local problems.
• Add a narrow inline suppression only with an explanatory comment.
• Review diffs for accidental key material before finishing.
• Review file permissions in tests that create secrets.
• Verify that failure paths preserve the original config.
• Verify CLI output with stdout redirected.
• Verify TUI entry and cancellation in an interactive terminal.

Documentation

• Update MVP.md only when product scope or architecture changes.
• Keep operational usage in README once implementation begins.
• Document every CLI command and its exit behavior.
• Document required and optional dependencies separately.
• Include examples that use placeholder keys and addresses only.
• Never commit real endpoints, private keys, preshared keys, or client configs.
• Explain backup and restore behavior before users rely on it.
• Document limitations of handshake history and traffic visibility.

Definition of done

• The requested behavior is implemented through shared backend functions.
• Mutations are locked, validated, backed up, atomic, and reversible.
• CLI operation remains available independently of the TUI.
• TUI uses the configured gum resolution order.
• Errors are actionable and do not reveal secrets.
• Relevant tests pass.
• bash -n passes.
• ShellCheck has no unexplained findings.
• Documentation matches observable behavior.
• No unrelated files or user changes are overwritten.