@rafay99/cvx 0.30.0 → 0.35.0

package/README.md

@@ -117,6 +117,14 @@ cd ~/Code/project-b && cvx link work
 cd ~/Code/project-c && cvx link personal   # one account → many projects
 ```
 
+## Safety net: the wrong-account guard
+
+The Convex CLI stamps a `# team: …` note on the `CONVEX_DEPLOYMENT` line of
+`.env.local`. On every activation (including the automatic cd-hook), cvx
+cross-checks that team against the linked account's teams and warns loudly on
+a mismatch — catching "about to deploy with the wrong account" *before* it
+happens. `cvx status` shows the same warning.
+
 ## Daily use
 
 ```bash
@@ -134,21 +142,24 @@ bun run dev             # runs as work — both live simultaneously
 | --- | --- |
 | `cvx add [name]` | Store the current `~/.convex` login as an account |
 | `cvx login <name>` | `npx convex login`, then store it as `<name>` |
-| `cvx refresh <account>` | Re-authenticate an account (refresh its token) |
+| `cvx refresh <account>` / `--all` | Re-authenticate one account — or every account in one sitting |
 | `cvx link <account> [path]` | Link a project dir (default cwd) to an account |
 | `cvx unlink [path]` | Remove a link |
 | `cvx rename <old> <new>` | Rename an account, keeping its links |
 | `cvx rm <account>` | Forget an account and its links |
-| `cvx use` | Activate this dir's account — or pick one interactively if unlinked |
+| `cvx use [account]` | Activate by name from anywhere — or this dir's account / an interactive pick |
 | `cvx run <account> -- <cmd>` | Run one command as `<account>` without changing the global login |
 | `cvx open` | Open the Convex dashboard for this project's deployment |
 | `cvx activate [-q]` | Activate this dir's account (the hook calls this) |
 | `cvx status [--json]` | Show the active account and this dir's link |
-| `cvx accounts` | List stored accounts |
+| `cvx accounts` | List stored accounts (with when each token was last verified) |
 | `cvx ls` | List linked projects |
 | `cvx which [path]` | Print the account name for a dir (scripting) |
 | `cvx prompt` | Print the active account name (for a shell prompt segment) |
 | `cvx keychain <status\|enable\|disable>` | Store tokens in the OS keychain instead of a file |
+| `cvx vault <status\|encrypt\|decrypt\|unlock\|lock>` | Passphrase-encrypt stored tokens (unlock once per session) |
+| `cvx export [file]` / `cvx import <file>` | Encrypted vault backup / restore — new-machine setup in one command |
+| `cvx upgrade` | Check for a newer release and print the exact upgrade command |
 | `cvx doctor` | Check setup + per-account token health |
 | `cvx completions <shell>` | Print a completion script (zsh/bash/fish/powershell) |
 | `cvx hook [--install] [--shell …]` | Install the cd-hook (zsh/bash/fish/nu/powershell) |
@@ -199,11 +210,17 @@ a single binary, so the split costs nothing at build time.
 
 ```
 bin/cvx.ts        entry point + command dispatch
-src/store.ts      data layer: vault I/O, the config swap, token verify, paths
+src/paths.ts      the ONE place HOME is resolved (CVX_HOME sandbox support)
+src/store.ts      data layer: vault I/O, the config swap, token verify
 src/ui.ts         the logo banner, first-run welcome, help
 src/colors.ts     the palette (edit here to re-theme)
 src/commands.ts   one function per subcommand
 src/hooks.ts      zsh / bash / PowerShell shell-hook snippets
+src/keychain.ts   OS keychain / DPAPI token backends
+src/crypto.ts     scrypt + AES-256-GCM (vault encryption, export files)
+src/vault.ts      passphrase-encrypted vault + session unlock
+src/transfer.ts   cvx export / import (encrypted backups)
+src/upgrade.ts    cvx upgrade (release check)
 src/system.ts     external-tool checks (node/npx)
 src/args.ts       flag parsing
 man/cvx.1         man page (installed by Homebrew/npm → `man cvx`)
@@ -212,6 +229,39 @@ man/cvx.1         man page (installed by Homebrew/npm → `man cvx`)
 First run of a bare `cvx` shows a welcome screen; `cvx welcome` shows it again,
 and `man cvx` opens the manual.
 
+## Testing
+
+```sh
+bun test          # full suite: parser + store units, and an e2e matrix that
+                  # drives every command against a throwaway CVX_HOME
+```
+
+The suite runs in ~2s, needs no setup, and never touches your real vault —
+CI (`.github/workflows/test.yml`) runs it on every PR. Three flows can't run
+headless and stay manual (use the sandbox below): real `cvx login` (browser),
+the interactive migration prompt (needs a PTY), and `cvx keychain enable`
+(the OS keychain is per-user).
+
+## Testing safely (sandbox)
+
+Never test a build against your real vault. Everything cvx touches — the vault,
+the global `~/.convex/config.json` it swaps, the rc files `hook --install`
+edits — resolves from one base directory, and setting `CVX_HOME` relocates all
+of it:
+
+```sh
+scripts/sandbox.sh                # build + drop into a shell with an EMPTY sandbox vault
+scripts/sandbox.sh --copy-vault   # same, but seeded with a COPY of your real vault
+```
+
+Inside that shell `cvx` is the fresh build and every command — `link`,
+`activate`, `rm`, even the migration prompt and `hook --install` — reads and
+writes only the sandbox. `exit` to leave; your real setup is never touched.
+Works without the script too: `CVX_HOME=/tmp/try cvx status`.
+
+One exception can't be sandboxed: the OS keychain is per-user, so skip
+`cvx keychain enable` in a sandbox (the default file backend is used anyway).
+
 ## Releasing
 
 Pushing to `main` (touching `bin/**` or `package.json`) triggers

package/cvx.1

@@ -52,10 +52,12 @@ PowerShell \fB$PROFILE\fR). The shell is auto-detected when \fB--shell\fR is omi
 Print a shell completion script (completes commands and account names).
 .SS Everyday
 .TP
-.B cvx use \fR[\fIpath\fR]
-Activate the account linked to a directory. If the directory isn't linked and
-the terminal is interactive, pick an account from a list (uses \fBfzf\fR if
-installed) and optionally link the directory.
+.B cvx use \fR[\fIaccount\fR|\fIpath\fR]
+With an account name: activate that account globally, from anywhere. With a
+path (or nothing): activate the directory's linked account; if unlinked and
+the terminal is interactive, pick from a list (uses \fBfzf\fR if installed)
+and optionally link the directory. A name wins over a same-named directory
+\(em use \fI./dir\fR to force the path meaning.
 .TP
 .B cvx run \fIaccount\fR \fR[\fB--\fR] \fIcommand\fR ...
 Run \fIcommand\fR with the given account active for that process only, by
@@ -97,6 +99,24 @@ Show or change where account tokens are stored. \fBenable\fR moves them into the
 OS keychain (macOS Keychain, libsecret on Linux, DPAPI on Windows); \fBdisable\fR
 moves them back to the chmod-600 file vault.
 .TP
+.B cvx vault \fR<\fBstatus\fR|\fBencrypt\fR|\fBdecrypt\fR|\fBunlock\fR|\fBlock\fR>
+Passphrase-encrypt the stored tokens (AES-256-GCM, scrypt-derived key).
+\fBunlock\fR caches the key for the session (cleared by \fBlock\fR or a
+reboot); while locked, tokens are unreadable and commands point at
+\fBcvx vault unlock\fR. Scripts can set \fBCVX_PASSPHRASE\fR instead.
+.TP
+.B cvx export \fR[\fIfile\fR] / \fBcvx import \fR\fIfile\fR [\fB--force\fR]
+Write a passphrase-encrypted backup of the vault (accounts + links), and
+restore it on another machine. Import merges; existing names are kept unless
+\fB--force\fR.
+.TP
+.B cvx refresh --all
+Re-authenticate every stored account in one sitting (a browser sign-in each).
+.TP
+.B cvx upgrade
+Check for a newer cvx release and print the exact upgrade command for how it
+was installed (Homebrew, npm/bun, or GitHub tarball).
+.TP
 .B cvx doctor \fR[\fB--no-tokens\fR]
 Check your setup and report problems: Node/npx availability, whether you have a
 Convex login, vault integrity, the token storage backend, the active account,
@@ -125,6 +145,13 @@ The Convex CLI's global login, which \fBcvx\fR rewrites.
 .TP
 .B NO_COLOR
 Disable colored output.
+.TP
+.B CVX_HOME
+Relocate everything cvx touches (vault, global Convex config, hook rc files)
+under this directory \(em a fully isolated sandbox for testing.
+.TP
+.B CVX_PASSPHRASE
+Non-interactive passphrase for \fBcvx vault\fR and \fBcvx export\fR/\fBimport\fR.
 .SH EXAMPLES
 .PP
 Add two accounts and wire up projects:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rafay99/cvx",
-  "version": "0.30.0",
+  "version": "0.35.0",
   "description": "Switch Convex accounts per project automatically — run many Convex accounts across projects at once, no login/logout churn, no deploy keys, no tokens in your repos",
   "keywords": [
     "convex", "convex-dev", "convex-cli", "cli", "command-line",
@@ -19,10 +19,10 @@
   "files": ["launcher.cjs", "cvx.1", "README.md", "LICENSE"],
   "engines": { "node": ">=16" },
   "optionalDependencies": {
-    "@rafay99/cvx-darwin-arm64": "0.30.0",
-    "@rafay99/cvx-darwin-x64": "0.30.0",
-    "@rafay99/cvx-linux-x64": "0.30.0",
-    "@rafay99/cvx-linux-arm64": "0.30.0",
-    "@rafay99/cvx-win32-x64": "0.30.0"
+    "@rafay99/cvx-darwin-arm64": "0.35.0",
+    "@rafay99/cvx-darwin-x64": "0.35.0",
+    "@rafay99/cvx-linux-x64": "0.35.0",
+    "@rafay99/cvx-linux-arm64": "0.35.0",
+    "@rafay99/cvx-win32-x64": "0.35.0"
   }
 }