docs: add nordvpn client plan
This commit is contained in:
Stefano Fiorini
40
docs/plans/2026-03-11-nordvpn-client-design.md
Normal file
40
docs/plans/2026-03-11-nordvpn-client-design.md
Normal file
@@ -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
|
||||||
127
docs/plans/2026-03-11-nordvpn-client.md
Normal file
127
docs/plans/2026-03-11-nordvpn-client.md
Normal file
@@ -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
|
||||||
Reference in New Issue
Block a user