@harry-kp/vortix 0.1.8 → 0.2.1

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-04-04
+
+### Fixed
+
+- Detect missing `resolvconf` before WireGuard connect on Linux ([#186](https://github.com/Harry-kp/vortix/issues/186), [#187](https://github.com/Harry-kp/vortix/pull/187)) — Vortix now shows clear install instructions instead of cryptic wg-quick errors when DNS is configured but resolvconf isn't available on Arch/Fedora
+- Add CLI dependency check to catch missing tools before connection attempts
+
+### Documentation
+
+- Add comprehensive Arch Linux troubleshooting FAQ and distribution-specific guidance in README
+- Add WireGuard configuration guide explaining AllowedIPs, cloud provider limitations, and routing best practices
+- Add quick error reference table for common connection issues
+
+
+
+## [0.2.0] - 2026-03-31
+
+### Added
+
+- Add a CLI-first headless mode with structured JSON output for scripting, automation, and AI-agent workflows, including `vortix status` for scriptable connection and kill-switch visibility ([#156](https://github.com/Harry-kp/vortix/issues/156), [#176](https://github.com/Harry-kp/vortix/pull/176)).
+- Add the new flip-panel dashboard interaction with animated card transitions ([#165](https://github.com/Harry-kp/vortix/pull/165)).
+
+### Changed
+
+- VPN sessions can now keep running after the TUI or CLI exits, so leaving the interface no longer tears down an active connection unexpectedly ([#155](https://github.com/Harry-kp/vortix/issues/155), [#176](https://github.com/Harry-kp/vortix/pull/176)).
+- Make `vortix down` wait for the OpenVPN daemon to fully exit before reporting success ([#176](https://github.com/Harry-kp/vortix/pull/176)).
+
+### Fixed
+
+- Remove the stale quit confirmation now that active connections can continue independently of the UI process ([#179](https://github.com/Harry-kp/vortix/issues/179), [#182](https://github.com/Harry-kp/vortix/pull/182)).
+- Fix help overlay scrolling edge cases, including opening before the first resize and clamping scroll correctly after keyboard and mouse input ([#180](https://github.com/Harry-kp/vortix/issues/180), [#182](https://github.com/Harry-kp/vortix/pull/182)).
+- Harden CLI lifecycle handling around disconnect flow, error paths, and config isolation ([#176](https://github.com/Harry-kp/vortix/pull/176)).
+
+### Documentation
+
+- Clarify current Linux support expectations and improve Linux bug-reporting guidance for distro-specific issues ([#185](https://github.com/Harry-kp/vortix/pull/185)).
+
+### CI
+
+- Add Fedora 41 CI coverage for `cargo check`, `cargo clippy`, `cargo test`, and `cargo doc`, including unprivileged test execution for Linux-specific validation ([#160](https://github.com/Harry-kp/vortix/issues/160), [#183](https://github.com/Harry-kp/vortix/pull/183)).
+
+
+
 ## [0.1.8] - 2026-03-19
 
 ### Features

package/README.md

@@ -49,6 +49,14 @@ Existing options (`wg show`, NetworkManager, Tunnelblick) either lack real-time
 - **Config Viewer** — Inspect profile configurations directly within the TUI
 - **Keyboard-driven** — No mouse required
 
+## Platform Support
+
+Vortix is actively developed and used primarily on macOS.
+
+Linux support is a current focus and is improving quickly, with CI coverage for Ubuntu and Fedora. Linux environments still vary a lot across distributions, firewall backends, DNS tooling, and privilege models, so distro-specific issues may still exist.
+
+If you use Vortix on Linux and hit a problem, please open an issue and include `vortix report` output when possible. Ubuntu, Fedora, and Arch users are especially helpful when testing release candidates and validating fixes before release. If you want to help test Linux support, join the [Linux tester discussion](https://github.com/Harry-kp/vortix/discussions/184).
+
 ## Requirements
 
 ### Runtime dependencies
@@ -58,11 +66,17 @@ Existing options (`wg show`, NetworkManager, Tunnelblick) either lack real-time
 | `curl` | Pre-installed | `apt install curl` | Telemetry and IP detection |
 | `openvpn` | `brew install openvpn` | `apt install openvpn` | OpenVPN sessions |
 | `wireguard-tools` | `brew install wireguard-tools` | `apt install wireguard-tools` | WireGuard sessions |
+| `resolvconf` / `systemd-resolved` | N/A (uses native DNS) | `systemd-resolvconf` or `openresolv` | WireGuard DNS management (optional, needed if DNS in config) |
 | `iptables` or `nftables` | N/A (uses `pfctl`) | Pre-installed | Kill switch |
 | `iproute2` | N/A (uses `ifconfig`) | Pre-installed | Interface detection |
 
 > Vortix checks for missing tools at startup and shows a warning toast with install instructions.
 
+**DNS tools note:** If your WireGuard profile includes a `DNS =` directive, Vortix will automatically detect and warn about missing DNS tools. Install accordingly:
+- **Arch/Fedora (systemd-based):** `sudo pacman -S systemd-resolvconf` or `sudo dnf install systemd-resolved`
+- **Debian/Ubuntu:** `sudo apt install systemd-resolved` (usually pre-installed)
+- **Alpine/Void (OpenRC):** Vortix falls back to `/etc/resolv.conf` editing automatically
+
 ### Build dependencies (source installs only)
 
 - Rust 1.75+
@@ -72,20 +86,20 @@ Existing options (`wg show`, NetworkManager, Tunnelblick) either lack real-time
 
 **Ubuntu/Debian:**
 ```bash
-sudo apt install curl wireguard-tools openvpn iptables iproute2
+sudo apt install curl wireguard-tools openvpn iptables iproute2 systemd-resolved
 ```
 
 **Fedora/RHEL:**
 ```bash
-sudo dnf install curl wireguard-tools openvpn iptables iproute
+sudo dnf install curl wireguard-tools openvpn iptables iproute systemd-resolved
 ```
 
 **Arch Linux** (only needed for source builds — `pacman -S vortix` handles deps automatically):
 ```bash
-sudo pacman -S curl wireguard-tools openvpn iptables iproute2
+sudo pacman -S curl wireguard-tools openvpn iptables iproute2 systemd-resolvconf
 ```
 
-> **DNS detection** uses `resolvectl` (systemd-resolved) as the primary method, with `nmcli` (NetworkManager) and `/etc/resolv.conf` as fallbacks. Non-systemd distros (Alpine, Void, Gentoo OpenRC) will use the `/etc/resolv.conf` fallback automatically.
+> **DNS management:** Vortix uses `resolvconf` (via `systemd-resolvconf` or `openresolv`) to manage DNS when your WireGuard profile contains `DNS =`. On systemd distros (most modern Linux), this is automatic via systemd-resolved. Non-systemd distros (Alpine, Void, Gentoo OpenRC) will use `/etc/resolv.conf` editing as a fallback.
 
 ## Installation
 
@@ -154,16 +168,88 @@ After this, `sudo vortix` works as expected.
 - Nix (`nix profile install`) — **no**, installs to Nix profile bin
 - macOS — **no**, sudo preserves user PATH
 
+### Linux support note
+
+Most day-to-day development happens on macOS. Linux support is continuously tested in CI, but real-world distro coverage is still growing. If something behaves differently on your Linux setup, please treat that as useful signal and report it rather than assuming it is expected.
+
 ## Usage
 
+Vortix has two modes: an interactive TUI dashboard (default) and a headless CLI for scripting, automation, and AI agents.
+
+```bash
+sudo vortix              # Launch TUI dashboard (default)
+```
+
+### CLI Commands
+
+Every subcommand supports `--json` for machine-readable output and `--quiet` for silent operation (exit code only).
+
+**Connection:**
+```bash
+sudo vortix up work-vpn         # Connect to a profile
+sudo vortix down                # Disconnect (graceful)
+sudo vortix down --force        # Force-disconnect (SIGKILL)
+sudo vortix reconnect           # Reconnect to last used profile
+vortix status                   # Show connection state + telemetry
+vortix status --brief           # One-line: "● Connected to work-vpn"
+vortix status --watch           # Live updates every 2s
+vortix status --watch --json    # NDJSON stream for monitoring
+```
+
+**Profile Management:**
 ```bash
-sudo vortix              # Launch TUI (requires root for VPN operations)
-vortix import <file>     # Import a .conf or .ovpn profile
-vortix info              # Show config directory and version
-vortix update            # Self-update to latest release
-vortix report            # Generate a bug report with system diagnostics
+vortix list                     # List all imported profiles
+vortix list --names-only        # Profile names for scripting
+vortix list --sort last-used    # Most recently used first
+vortix import ./work.conf       # Import a WireGuard profile
+vortix import ./configs/        # Bulk import from directory
+vortix show work-vpn            # Display profile configuration
+vortix show work-vpn --raw      # Raw config file contents
+vortix delete old-vpn --yes     # Delete without confirmation
+vortix rename old-vpn new-vpn   # Rename a profile
 ```
 
+**Security:**
+```bash
+sudo vortix killswitch auto     # Set kill switch to auto mode
+sudo vortix killswitch always   # Always-on kill switch
+vortix killswitch               # Show current mode
+sudo vortix release-killswitch  # Emergency firewall release
+```
+
+**System:**
+```bash
+vortix info                     # Config paths, versions, profile count
+vortix update                   # Self-update from crates.io
+vortix report                   # Generate bug report
+vortix completions bash >> ~/.bashrc      # Shell completions
+vortix completions zsh > ~/.zfunc/_vortix
+```
+
+**JSON output for AI agents / scripts:**
+```bash
+# Structured JSON envelope on every command
+vortix status --json
+# {"ok":true,"command":"status","data":{...},"next_actions":[...]}
+
+vortix list --json | jq '.data[].name'    # Extract profile names
+
+# NDJSON stream for monitoring
+vortix status --watch --json
+```
+
+**Exit codes** are semantic and scriptable:
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Permission denied (needs sudo) |
+| 3 | Not found (profile doesn't exist) |
+| 4 | State conflict (already connected) |
+| 5 | Missing dependency |
+| 6 | Timeout |
+
 ### Keybindings
 
 | Key | Action |
@@ -318,6 +404,18 @@ ip_api_fallbacks = ["https://api.ipify.org", "https://icanhazip.com", "https://i
 
 ## Troubleshooting
 
+### Quick Reference: Common Errors
+
+| Error Message | Cause | Solution |
+|---------------|-------|----------|
+| `Missing dependencies: resolvconf (systemd)` | WireGuard profile has DNS but `resolvconf` not installed | Run `sudo pacman -S systemd-resolvconf` (Arch) or `sudo dnf install systemd-resolved` (Fedora) |
+| `iptables-restore: unable to initialize table` | Cloud kernel doesn't support iptables; profile uses `AllowedIPs = 0.0.0.0/0` | Change `AllowedIPs` to `10.0.0.0/8` or disable kill switch |
+| `wg-quick: The config file must be a valid interface name` | Profile name > 15 characters | Rename: `vortix rename long-name short-name` |
+| `Connection succeeded but no internet` | `AllowedIPs` doesn't include your target | Add target IP to `AllowedIPs` in config |
+| `connection timed out` or `Connection refused` | Can't reach VPN endpoint | Check firewall/cloud provider port restrictions |
+
+### General Issues
+
 **Profiles missing after upgrade (Linux)**
 
 If you previously ran vortix with `sudo` and profiles were stored in `/root/.config/vortix/`, the app will offer a one-time migration prompt. Accept it to move your data to `~/.config/vortix/` under your real user account.
@@ -336,6 +434,222 @@ If config files are owned by root, fix ownership:
 sudo chown -R $(whoami) ~/.config/vortix/
 ```
 
+### Arch Linux & Distribution-Specific FAQ
+
+#### Q: Connection fails with "Missing dependencies: resolvconf (systemd)"
+
+**A:** This happens on Arch, Fedora, and NixOS when your WireGuard profile has DNS settings but `resolvconf` isn't installed. These distros don't include DNS management tools by default.
+
+**Fix:**
+```bash
+# Arch Linux (systemd-based)
+sudo pacman -S systemd-resolvconf
+
+# Fedora (systemd-based)
+sudo dnf install systemd-resolved
+
+# Debian/Ubuntu (should be pre-installed)
+sudo apt install systemd-resolved
+```
+
+Vortix will now automatically detect `resolvconf` and proceed with the connection. No restart needed.
+
+#### Q: Connection fails with "iptables-restore: unable to initialize table"
+
+**A:** Your system doesn't have the `ip_tables` kernel module. This typically happens on:
+- **Cloud providers** (DigitalOcean, AWS Lambda, Google Cloud Run, etc.) that intentionally disable netfilter
+- **Containers** with minimal kernel capabilities
+- **Custom kernels** built without netfilter support
+
+This is **not a Vortix issue** — it's a system limitation that affects all Linux VPN tools, specifically:
+- **Vortix's kill switch** (requires iptables/nftables for firewall rules)
+- **wg-quick's automatic routing** (when `AllowedIPs = 0.0.0.0/0` is set in the WireGuard config)
+
+**Workaround 1: Disable the kill switch (doesn't help on cloud providers):**
+```bash
+sudo vortix killswitch off
+sudo vortix up your-profile
+```
+
+This only works if your WireGuard profile doesn't use `AllowedIPs = 0.0.0.0/0`. If it does, wg-quick will still try to configure iptables.
+
+**Workaround 2: Modify your WireGuard profile for cloud providers:**
+
+If your profile has `AllowedIPs = 0.0.0.0/0` (route all traffic through VPN), wg-quick automatically configures firewall rules. On cloud providers, change it to a more restrictive setting:
+
+```ini
+# ❌ This requires iptables (will fail on cloud providers)
+AllowedIPs = 0.0.0.0/0
+
+# ✅ This only routes VPN subnet (no iptables needed)
+AllowedIPs = 10.0.0.0/8
+```
+
+Edit your profile with `vortix show <profile> --raw` to see the current `AllowedIPs` setting.
+
+**Verify if your system supports iptables:**
+```bash
+modprobe ip_tables && echo "✓ Supported" || echo "✗ Not available on this kernel"
+```
+
+**Best practice for cloud providers:**
+If you need to route all traffic through the VPN on a cloud provider, you'll need an instance with a standard kernel (not a restricted cloud kernel). Alternatively, use a home server, dedicated host, or bare metal with full kernel support.
+
+#### Q: How do I know what DNS resolver my system uses?
+
+**A:** Run this to check which method Vortix will use:
+
+```bash
+# Systemd (most modern Linux distros)
+resolvectl status 2>/dev/null && echo "✓ Using systemd-resolved"
+
+# NetworkManager
+nmcli dev show 2>/dev/null | grep DNS && echo "✓ Using NetworkManager"
+
+# Fallback check
+cat /etc/resolv.conf | head -3
+```
+
+Vortix automatically detects and respects your system's DNS setup.
+
+#### Q: Can I use Vortix on non-systemd distros?
+
+**A:** Yes, but with limitations on DNS management:
+- **Arch, Fedora, Ubuntu, Debian** → Full support (systemd or alternatives available)
+- **Alpine, Void, Gentoo (OpenRC)** → Vortix falls back to editing `/etc/resolv.conf` directly
+- **NixOS** → Works, but DNS may require custom configuration
+
+If you use a non-systemd distro and hit issues, please [open an issue](https://github.com/Harry-kp/vortix/issues) with `vortix report` output.
+
+#### Q: Why does the connection succeed but DNS doesn't work?
+
+**A:** If `vortix up` succeeds but you can't resolve domains, it means:
+
+1. **The VPN tunnel is active** (IP changing works)
+2. **DNS configuration failed** (resolvconf not working properly)
+
+**Debug steps:**
+```bash
+# Check if resolvconf is working
+resolvconf --version
+
+# Check active DNS servers
+resolvectl status | grep -A5 "DNS Servers"
+
+# Manually test DNS through the VPN
+dig @8.8.8.8 google.com
+
+# Check the system's resolv.conf symlink
+ls -la /etc/resolv.conf
+```
+
+If `/etc/resolv.conf` is not managed by systemd (not a symlink to `/run/systemd/`), you may need to install `systemd-resolvconf` or `openresolv`.
+
+#### Q: WireGuard interface name is too long
+
+**A:** Linux WireGuard interfaces have a 15-character name limit. If your profile name is longer, wg-quick will fail with "invalid interface name".
+
+**Fix:** Rename your profile to something shorter:
+```bash
+vortix rename my-very-long-profile-name work-vpn
+```
+
+WireGuard interface names should contain only alphanumeric characters, hyphens, and underscores.
+
+#### Q: How do I report a distro-specific issue?
+
+**A:** Include this information when opening an issue:
+
+```bash
+vortix report              # Generates a complete report
+uname -a                   # Kernel version
+cat /etc/os-release        # Distro info
+systemctl --version        # Init system
+```
+
+Tested and supported Linux distros in CI: **Ubuntu 20.04/22.04**, **Fedora 40+**, **Arch Linux**. If you use a different distro and hit issues, that's valuable signal for the project.
+
+### WireGuard Configuration Guide
+
+#### Understanding AllowedIPs
+
+The `AllowedIPs` setting in your WireGuard config determines what traffic goes through the VPN:
+
+```ini
+# Route ALL traffic through VPN (requires iptables/nftables for firewall rules)
+AllowedIPs = 0.0.0.0/0          # ⚠️ May fail on cloud providers, containers
+
+# Route only VPN subnet traffic (no special firewall rules needed)
+AllowedIPs = 10.0.0.0/8          # ✅ Works everywhere, even cloud providers
+
+# Route specific traffic only
+AllowedIPs = 192.168.1.0/24      # ✅ Route only corporate network
+```
+
+**Why this matters:**
+- When `AllowedIPs = 0.0.0.0/0`, wg-quick automatically configures firewall rules via iptables/nftables
+- Cloud providers (DigitalOcean, AWS Lambda, Google Cloud Run) disable iptables kernel modules
+- Restrictive `AllowedIPs` avoids firewall configuration entirely
+
+**Recommendation for cloud servers:**
+If you're running Vortix on a cloud provider and need to route traffic through the VPN, use `AllowedIPs = 10.0.0.0/8` or another private subnet instead of `0.0.0.0/0`.
+
+#### Common WireGuard Configuration Issues
+
+**Issue: Connection succeeds but no internet access**
+
+Check your `AllowedIPs` setting:
+```bash
+vortix show your-profile --raw | grep AllowedIPs
+```
+
+- If it's `10.0.0.0/8` or similar, only traffic to that subnet goes through VPN
+- Add your target IP/subnet to `AllowedIPs` to route it through the tunnel
+- Example: `AllowedIPs = 10.0.0.0/8, 192.168.0.0/16`
+
+**Issue: Can't reach VPN server from cloud provider**
+
+Some cloud providers block outbound UDP 51820 or other ports. Try:
+```bash
+# Check if you can reach the endpoint
+ping -c 1 138.197.3.155
+
+# Test specific port (replace with your endpoint)
+nc -zu 138.197.3.155 51820 && echo "✓ Port open" || echo "✗ Port blocked"
+```
+
+If blocked, contact your cloud provider to allow WireGuard ports.
+
+**Issue: DNS works but only for some domains**
+
+This usually means:
+1. VPN DNS servers are configured but not all traffic routes through VPN
+2. Your system's DNS fallback is resolving some queries locally
+
+Check if `DNS =` is in your config and matches your VPN provider's DNS servers.
+
+#### Testing Your WireGuard Profile
+
+After creating/importing a profile, test the configuration:
+
+```bash
+# View the profile
+vortix show my-profile --raw
+
+# Check required fields
+vortix show my-profile --raw | grep -E "^(PrivateKey|PublicKey|AllowedIPs|Endpoint|Address|DNS)"
+
+# Expected output:
+# PrivateKey = (base64)
+# Address = 10.0.0.2/24
+# Endpoint = 1.2.3.4:51820
+# AllowedIPs = 10.0.0.0/8 (or 0.0.0.0/0)
+# PublicKey = (base64)
+# DNS = 8.8.8.8, 8.8.4.4 (optional)
+```
+
+All fields above are required except `DNS` (optional).
+
 ## Roadmap
 
 See the [project board](https://github.com/users/Harry-kp/projects/6) for what's being explored. Have an idea? [Join the discussion](https://github.com/Harry-kp/vortix/discussions/34).

package/npm-shrinkwrap.json

@@ -23,7 +23,7 @@
       "hasInstallScript": true,
       "license": "MIT",
       "name": "@harry-kp/vortix",
-      "version": "0.1.8"
+      "version": "0.2.1"
     },
     "node_modules/@isaacs/balanced-match": {
       "engines": {
@@ -515,5 +515,5 @@
     }
   },
   "requires": true,
-  "version": "0.1.8"
+  "version": "0.2.1"
 }

package/package.json

@@ -1,5 +1,5 @@
 {
-  "artifactDownloadUrl": "https://github.com/Harry-kp/vortix/releases/download/v0.1.8",
+  "artifactDownloadUrl": "https://github.com/Harry-kp/vortix/releases/download/v0.2.1",
   "author": "Harry KP <harrykp@users.noreply.github.com>",
   "bin": {
     "vortix": "run-vortix.js"
@@ -100,7 +100,7 @@
       "zipExt": ".tar.xz"
     }
   },
-  "version": "0.1.8",
+  "version": "0.2.1",
   "volta": {
     "node": "18.14.1",
     "npm": "9.5.0"