From fe5b4659feff971ea53d9891c38e7f3df77f9733 Mon Sep 17 00:00:00 2001 From: Stefano Fiorini Date: Wed, 11 Mar 2026 22:02:49 -0500 Subject: [PATCH] docs: add nordvpn client plan --- .../plans/2026-03-11-nordvpn-client-design.md | 40 ++++++ docs/plans/2026-03-11-nordvpn-client.md | 127 ++++++++++++++++++ 2 files changed, 167 insertions(+) create mode 100644 docs/plans/2026-03-11-nordvpn-client-design.md create mode 100644 docs/plans/2026-03-11-nordvpn-client.md diff --git a/docs/plans/2026-03-11-nordvpn-client-design.md b/docs/plans/2026-03-11-nordvpn-client-design.md new file mode 100644 index 0000000..5531cb1 --- /dev/null +++ b/docs/plans/2026-03-11-nordvpn-client-design.md @@ -0,0 +1,40 @@ +# NordVPN Client Skill Design + +## Goal +Create a `nordvpn-client` skill that works on macOS and Linux gateway hosts. It should detect whether NordVPN is already installed, bootstrap it if missing, handle login/auth setup, connect to a requested country or city, verify the VPN state and public IP location, disconnect when requested, and then be usable alongside other skills like `web-automation`. + +## Architecture +The skill exposes one logical interface with platform-specific backends. Linux uses the official NordVPN CLI path. macOS probes for a usable CLI first, but falls back to the official app workflow when needed. The skill is responsible only for VPN lifecycle and verification, not for wrapping arbitrary commands inside a VPN session. + +## Interface +Single script entrypoint: +- `node scripts/nordvpn-client.js install` +- `node scripts/nordvpn-client.js login` +- `node scripts/nordvpn-client.js connect --country "Italy"` +- `node scripts/nordvpn-client.js connect --city "Milan"` +- `node scripts/nordvpn-client.js disconnect` +- `node scripts/nordvpn-client.js status` + +## Platform Model +### Linux +- Probe for `nordvpn` +- If missing, bootstrap official NordVPN package/CLI +- Prefer token-based login for non-interactive auth +- Connect/disconnect/status through official CLI + +### macOS +- Probe for `nordvpn` CLI if available +- Otherwise probe/install the official app +- Use CLI when present, otherwise automate the app/login flow +- Verify connection using app/CLI state plus external IP/geolocation + +## Auth and Safety +- Do not store raw NordVPN secrets in skill docs +- Read token/credentials from env vars or a local credential file path +- Keep the skill focused on install/login/connect/disconnect/status +- After `connect`, verify both local VPN state and external IP/location before the agent proceeds to tasks like `web-automation` + +## Verification +- `status` reports platform, install state, auth state, connection state, and public IP/location check +- `connect` verifies the requested target as closely as available data allows +- Local validation happens first in the OpenClaw workspace, then the proven skill is copied into `stef-openclaw-skills`, documented, committed, and pushed diff --git a/docs/plans/2026-03-11-nordvpn-client.md b/docs/plans/2026-03-11-nordvpn-client.md new file mode 100644 index 0000000..5e7bec8 --- /dev/null +++ b/docs/plans/2026-03-11-nordvpn-client.md @@ -0,0 +1,127 @@ +# NordVPN Client Skill Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Build a cross-platform `nordvpn-client` skill for macOS and Linux that can install/bootstrap NordVPN, log in, connect to a target country or city, verify the VPN session, disconnect, and report status. + +**Architecture:** Implement one skill with one script entrypoint and platform-specific backends. Linux uses the official NordVPN CLI. macOS uses a CLI path when present and otherwise falls back to the NordVPN app workflow. The skill manages VPN state only, leaving follow-up operations like `web-automation` to separate agent steps. + +**Tech Stack:** Node.js, shell/OS commands, NordVPN CLI/app integration, OpenClaw skills, git + +--- + +### Task 1: Create isolated worktree + +**Files:** +- Modify: repo git metadata only + +**Step 1: Create worktree** + +Run: +```bash +git -C /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills worktree add /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/nordvpn-client -b feature/nordvpn-client +``` + +**Step 2: Verify baseline** + +Run: +```bash +git -C /Users/stefano/.openclaw/workspace/projects/stef-openclaw-skills/.worktrees/nordvpn-client status --short --branch +``` +Expected: clean feature branch + +### Task 2: Create the local skill runtime + +**Files:** +- Create: `skills/nordvpn-client/SKILL.md` +- Create: `skills/nordvpn-client/scripts/nordvpn-client.js` +- Optional Create: helper files under `skills/nordvpn-client/scripts/` + +**Step 1: Write the failing checks** +- Missing command/action should fail with clear usage output +- Unsupported platform should fail clearly + +**Step 2: Implement platform detection and install probe** +- detect `darwin` vs `linux` +- detect whether NordVPN CLI/app is already present +- expose `status` with install/auth/connect fields + +### Task 3: Implement install and auth bootstrap + +**Files:** +- Modify: `skills/nordvpn-client/scripts/nordvpn-client.js` + +**Step 1: Linux install/login path** +- implement official CLI probe/install path +- implement token-based login path + +**Step 2: macOS install/login path** +- probe CLI first +- if absent, probe/install NordVPN app path +- implement login/bootstrap state verification for the app workflow + +**Step 3: Keep secrets external** +- env vars or local credential path only +- no raw secrets in docs or skill text + +### Task 4: Implement connect/disconnect/status/verification + +**Files:** +- Modify: `skills/nordvpn-client/scripts/nordvpn-client.js` + +**Step 1: Connect** +- support `--country` and `--city` +- normalize target handling per platform + +**Step 2: Verify** +- report local connection state +- run public IP / geolocation verification +- fail if connection target cannot be reasonably verified + +**Step 3: Disconnect and status** +- implement clean disconnect +- ensure `status` emits machine-readable output for agent use + +### Task 5: Validate locally in OpenClaw workspace + +**Files:** +- Test: local workspace copy of `nordvpn-client` + +**Step 1: Direct command validation** +- usage errors are correct +- install probe works on this host +- status output is coherent before login/connect + +**Step 2: One real connect flow** +- connect to a test country/city if credentials are available +- verify local state + external IP/location +- disconnect cleanly + +### Task 6: Promote to repo docs and publish + +**Files:** +- Modify: `README.md` +- Modify: `docs/README.md` +- Create: `docs/nordvpn-client.md` +- Create/Modify: `skills/nordvpn-client/...` + +**Step 1: Document the skill** +- install/bootstrap behavior +- auth expectations +- connect/disconnect/status commands +- macOS vs Linux notes + +**Step 2: Commit and push** + +Run: +```bash +git add skills/nordvpn-client docs README.md +git commit -m "feat: add nordvpn client skill" +git push -u origin feature/nordvpn-client +``` + +**Step 3: Merge and cleanup** +- fast-forward or merge to `main` +- push `main` +- remove the worktree +- delete the feature branch