89 lines
3.9 KiB
Markdown
89 lines
3.9 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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
|
|
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
|
|
sh install.sh
|
|
vpn --status
|
|
open ~/Applications/LemanaVPN.app
|
|
```
|
|
|
|
For remote user-facing update instructions, use:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
vpn --configure-keychain
|
|
```
|