Lemana VPN Agent Instructions

Scope

This repository builds a macOS Lemana VPN installer, CLI, DNS cleanup wrapper, and Swift menu-bar app. Work in Russian by default, unless the user asks otherwise.

Before changing behavior, read the relevant repo-local skills:

.agents/skills/lemana-vpn-operations/SKILL.md for install/update/connect/status/user-answer rules.
.agents/skills/lemana-vpn-testing/SKILL.md for verification strategy and live VPN safety.
.agents/skills/lemana-vpn-sso-autofill/SKILL.md for Bitwarden, Keychain, TOTP, SSO, and runtime autofill patches.

System Model

install.sh installs Homebrew/pipx dependencies, openconnect-lite, CLI scripts, config, DNS wrapper, sudoers rules, optional Touch ID helper, and optional ~/Applications/LemanaVPN.app.
bin/vpn-lemanapro.sh is the main runtime path. It reports module status, syncs Bitwarden credentials into macOS Keychain, verifies Keychain credentials, applies openconnect-lite runtime patches, starts SSO/openconnect, writes status JSON, and cleans VPN DNS on exit.
templates/openconnect-lite-config.toml defines the SSO profile and Keycloak auto-fill selectors.
libexec/lemana-vpn-dns-cleanup is the narrow root-owned DNS cleanup wrapper.
app/Sources/LemanaVPN/* is a menu-bar wrapper over ~/bin/vpn-lemanapro.sh --json; it does not implement a separate VPN client.
uninstall.sh restores patch backups when possible, removes installed files, stops a running LemanaVPN process when the app is removed, and optionally removes Keychain/Touch ID/openconnect-lite state.

Live VPN Safety

Always check current state before starting a live connection:

vpn --status
vpn --status --json

Use ~/bin/vpn-lemanapro.sh if aliases are not loaded. For repo-local code checks, bin/vpn-lemanapro.sh --status validates the source script, but it may not be the installed version used by the menu-bar app.

Do not run vpn, vpn-auto, vpn-debug, vpn --manual, vpn --manual-full, or the Swift app connect action repeatedly when a connection is already connected, connecting, reconnecting, or when a live connect attempt is still running. Inspect status and logs instead:

tail -f ~/Library/Logs/LemanaVPN-openconnect-lite.log
tail -f ~/Library/Logs/LemanaVPN.log

Use vpn --manual before vpn/vpn-auto when debugging SSO/autofill, because manual mode shows the browser, fills fields, and does not press submit. Use vpn --manual-full when the form itself must be filled entirely by hand with no auto-fill. Use vpn-debug only when raw logs and a visible browser are needed.

vpn-lemanapro.sh --patch-only is safe for applying runtime patches without starting a VPN session.

Testing

Prefer the non-live ladder first:

sh -n install.sh
sh -n uninstall.sh
bash -n bin/vpn-lemanapro.sh
sh -n tests/smoke.sh
tests/smoke.sh
swift build -c release --package-path app
git diff --check

Run a live VPN check only when the change affects real connection behavior, credential flow, SSO/autofill, status reporting, reconnect, or DNS cleanup, and only after checking current status. If VPN is already connected, do not start a second session; report that live reconnect was intentionally skipped unless the user explicitly asks for it.

Answer Contract

Every final answer for this repository must include:

What changed, with file references when useful.
How to run it.
How to check it.
How to update the installed local setup.
What verification was run, and what was intentionally not run.

For update instructions, prefer the exact current path:

sh install.sh
vpn --status
open ~/Applications/LemanaVPN.app

For remote user-facing update instructions, use:

curl -fsSL https://git.dokops.ru/dokril/lemana-vpn/raw/branch/main/install.sh | sh

If credentials are missing and Bitwarden is disabled or unavailable from the menu-bar app, point the user to:

vpn --configure-keychain

3.9 KiB Raw Blame History