@muthuishere/vsync 0.5.0 → 0.5.1

package/README.md

@@ -1,8 +1,8 @@
 # vsync
 
-**Your `.env` files — kept as simple, made as safe as a vault.**
+**One encrypted vault for your environment secrets, shared across your team, mirrored to GitHub & GCP, audited every time someone touches it.**
 
-![vsync flow](docs/vsync-flow.png)
+![vsync flow](https://raw.githubusercontent.com/muthuishere/vsync/main/docs/public/vsync-flow.png)
 
 A `.env` file is the friendliest thing in your repo: one line per secret, edited by hand, loaded by every framework. It's also the worst thing in your repo — passed around on Slack, copy-pasted into the wrong window, never the same on any two laptops, **never encrypted, never versioned, never auditable**. The moment one teammate's secrets drift from another's, you stop trusting `.env` and start emailing JSON files.
 
@@ -16,10 +16,11 @@ vsync keeps the `.env` you already write, and turns it into a real vault:
 - **Per-machine key in the OS keychain.** `Bun.secrets` — macOS Keychain, Linux libsecret, Windows Credential Manager. The S3 bucket alone is useless; the key alone is useless. Both halves required to decrypt.
 
 ```bash
-bunx @muthuishere/vsync --help
+bun  install -g @muthuishere/vsync     # or:  npm install -g @muthuishere/vsync
+vsync --help
 ```
 
-Run via `bunx`. No install, no shell-rc edits, no giant base64 blob in `~/.zshrc`.
+One global install, then `vsync` is on PATH. No shell-rc edits, no giant base64 blob in `~/.zshrc`. (Allergic to global installs? `bunx @muthuishere/vsync <subcommand>` works too — same code path, slower invocation.)
 
 ---
 
@@ -103,13 +104,16 @@ A `.share` file bundles **both halves** under one passphrase. Sent on a differen
 
 ## Install
 
-You don't. Run via `bunx`:
-
 ```bash
-bunx @muthuishere/vsync <subcommand>
+bun install -g @muthuishere/vsync     # or:  npm install -g @muthuishere/vsync
+vsync --help
 ```
 
-Requires Bun ≥ 1.2.21 (for `Bun.secrets`). For local development of vsync itself:
+Requires Bun ≥ 1.2.21 on PATH (for `Bun.secrets`) — the shebang is `#!/usr/bin/env bun`, so `bun` must be installed even if you used `npm install -g` for the package itself. Most users have Bun anyway; if not, see [bun.sh](https://bun.sh).
+
+Don't want to install? `bunx @muthuishere/vsync <subcommand>` runs the same code from npm cache each time — fine for trying it out, slower for daily use.
+
+For local development of vsync itself:
 
 ```bash
 git clone git@github.com:muthuishere/vsync.git
@@ -125,14 +129,14 @@ bun test
 ```bash
 # 1. Generate the per-(repo, env) key + config. First-ever invocation prompts
 #    for S3 creds; subsequent inits pre-fill from ~/.config/vsync/defaults.
-bunx @muthuishere/vsync init dev
+vsync init dev
 
 # 2. Put your secrets under infra/vault/dev/ and push.
 echo "DATABASE_URL=postgres://..." > infra/vault/dev/.env.dev
-bunx @muthuishere/vsync push dev
+vsync push dev
 
 # 3. Hand the team a share file + passphrase (different channels).
-bunx @muthuishere/vsync export dev
+vsync export dev
 ```
 
 For an onboarding cheat sheet to drop into your repo (so teammates and AI agents know vsync exists), run `vsync docs > infra/AGENTS.md`. Plain stdout — pipe it wherever you want.
@@ -144,11 +148,11 @@ cd <cloned-repo>
 
 # 1. Import the share file your teammate sent (carries S3 creds + key).
 #    No prior `init` required on this machine.
-bunx @muthuishere/vsync import dev ./reqsume-dev.share
+vsync import dev ./reqsume-dev.share
 # Passphrase: <paste>
 
 # 2. Pull the encrypted bundle.
-bunx @muthuishere/vsync pull dev
+vsync pull dev
 ```
 
 After step 2, `infra/vault/dev/` is populated and the encryption key is in your keychain.
@@ -157,18 +161,18 @@ After step 2, `infra/vault/dev/` is populated and the encryption key is in your
 
 ```bash
 # I edited infra/vault/dev/.env.dev locally:
-bunx @muthuishere/vsync push dev
+vsync push dev
 
 # Get the latest from S3:
-bunx @muthuishere/vsync pull dev
+vsync pull dev
 
 # See what versions exist on S3:
-bunx @muthuishere/vsync versions dev
+vsync versions dev
 
 # Push secrets out to GitHub / GCP:
-bunx @muthuishere/vsync sync dev gh
-bunx @muthuishere/vsync sync dev gcp
-bunx @muthuishere/vsync sync dev all
+vsync sync dev gh
+vsync sync dev gcp
+vsync sync dev all
 ```
 
 `pull` makes a local backup at `~/.config/vsync/backups/<env>-<ts>.zip.enc` before overwriting (two-deep rolling buffer). See "Recovering a local backup" below if you ever need one.
@@ -299,19 +303,13 @@ In practice, just don't lose the keychain entry. `pull` itself is the recovery p
 
 ## Versioning
 
-This is **0.4.0** — adds an append-only audit log at `s3://<bucket>/<repo>/<env>/audit.csv` and the `vsync audit` viewer. Fully additive over 0.3.x: no wire-format break, no config migration. Old clients ignore `audit.csv`; new clients tolerate its absence.
-
-0.3.0 was the rebrand from `@muthuishere/secret-lib` 0.2.x — new package name, new bin (`vsync`), new keychain service (`tools.vsync`), new config root (`~/.config/vsync/`), new vault layout (`infra/vault/<env>/.env.<env>`). The crypto envelope (`RQE1`) is unchanged.
-
-0.3.x and later do not auto-migrate from 0.2.x. The supported upgrade path is to re-`init` from scratch:
-
-```bash
-vsync init dev          # auto-relocates root .env.dev if it exists
-vsync push dev
-vsync export dev        # re-share with team
-```
+| Release | What's in it |
+|---|---|
+| **0.5.0** | `vsync use <env>` — symlinks `./.env` (or `--link=<path>`) at the vault's env file so `dotenv.config()` just works; switch envs with one command. README rewrite + flow diagram. |
+| 0.4.0 | Append-only audit log at `s3://<bucket>/<repo>/<env>/audit.csv` + `vsync audit` viewer. Expandable `meta` JSON cell via `--note` / `--meta` + matching env vars. |
+| 0.3.0 | Opinionated layout: vault folder at `infra/vault/<env>/` with `--vault-folder` override; self-contained per-(repo, env) config; `vsync sync` for GitHub / GCP fanout. |
 
-Any leftover 0.2.x on-disk config tree and keychain entries can be deleted; nothing in 0.3.x reads them. `@muthuishere/secret-lib` 0.2.x stays on npm for users who can't migrate.
+All 0.x releases are wire-compatible with each other on the S3 bundle envelope (`RQE1`) and manifest seal (`RQEM0001`). New clients tolerate the absence of features added in later versions; old clients ignore new objects (like `audit.csv`) on the bucket.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muthuishere/vsync",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Encrypted secret-sync CLI for small teams. Self-contained per-(repo, env) config + OS keychain key + AES-GCM-on-S3 + share-file onboarding + fanout to GitHub/GCP. Bun-native, run via bunx.",
   "type": "module",
   "bin": {
@@ -12,7 +12,10 @@
     "README.md"
   ],
   "scripts": {
-    "test": "bun test"
+    "test": "bun test",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "secrets",
@@ -41,6 +44,7 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@types/bun": "latest"
+    "@types/bun": "latest",
+    "vitepress": "^1.6.4"
   }
 }