@muthuishere/vsync 0.5.0 → 0.6.0

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.
@@ -196,17 +200,24 @@ Every command works fully via flags or fully via prompts.
 
 ### `sync` env-file parsing
 
-Two special-case keys (path → file content inlining):
+**File references — `*_PATH` / `*_FILE`.** Any key in `.env.<env>` whose name ends in `_PATH` or `_FILE` is read from disk; vsync pushes the file's contents under the key with the suffix stripped. Examples:
+
+- `SSH_PRIVATE_KEY_PATH=keys/reqsume_dev` → pushes `<vault>/keys/reqsume_dev` as `SSH_PRIVATE_KEY`.
+- `GCP_SA_KEY_FILE=keys/sa.json` → pushes `<vault>/keys/sa.json` as `GCP_SA_KEY`.
 
-- `GCP_SA_KEY_FILE_PATH=<path>` → reads the file, pushes the contents as `GCP_SA_KEY` (must look like JSON).
-- `SSH_KEY_PATH=<path>` → reads the file, pushes as `SSH_PRIVATE_KEY`.
+Relative paths anchor to `VAULT_ROOT` (the directory of the env file being parsed). Placeholders `${VAULT_ROOT}`, `${HOME}`, and leading `~/` are expanded in every value. Any missing or unreadable referenced file aborts the whole sync before any push (all-or-none).
 
 Two local-only keys (skipped — used by `gh` / `gcloud` on the local machine, not pushed):
 
 - `GITHUB_TOKEN`
 - `GOOGLE_APPLICATION_CREDENTIALS`
 
-Everything else is pushed verbatim.
+Two routing keys (consumed by `vsync sync` itself, never pushed):
+
+- `GITHUB_REPO`
+- `GCP_PROJECT_ID`
+
+Everything else is pushed verbatim. Full convention in [`docs/guide/sync.md`](docs/guide/sync.md) and design context in [`docs/specs/v0.6-vault-relative-file-refs.md`](docs/specs/v0.6-vault-relative-file-refs.md).
 
 ### Audit log
 
@@ -238,7 +249,7 @@ Auth is **outside vsync's scope** — the lib trusts whatever `gh` and `gcloud`
 
 **`vsync sync <env> gh`:**
 1. Resolves `sync.gh.repo` from per-repo config (or `--gh-repo` flag, or first-run prompt).
-2. Parses `<vaultFolder>/.env.<env>` into push-ready KVs (after special-case + skip rules).
+2. Parses `<vaultFolder>/.env.<env>` into push-ready KVs (file-ref + skip rules below).
 3. For each KV in a 6-worker pool: `gh secret set <KEY> --env <env> --repo <sync.gh.repo>` with the value on stdin.
 4. Requires `gh` CLI installed and `gh auth login` already done.
 
@@ -248,7 +259,33 @@ Auth is **outside vsync's scope** — the lib trusts whatever `gh` and `gcloud`
 3. For each KV: `gcloud secrets describe <KEY> --project=<proj>` to check existence; either `gcloud secrets versions add <KEY>` (exists) or `gcloud secrets create <KEY> --replication-policy=automatic` (new). Value on stdin via `--data-file=-`.
 4. Requires `gcloud` CLI installed and `gcloud auth login` done. Per-env isolation comes from per-env GCP projects (dev project ≠ prod project) — secret names are flat within a project.
 
-**`vsync sync <env> all`** runs both in sequence. Failures don't abort siblings; final summary lists what failed.
+**`vsync sync <env> all`** runs both in sequence. Per-secret push failures don't abort siblings; final summary lists what failed. Parse-time failures (see "all-or-none" below) abort everything before any push.
+
+### File-reference convention (`.env.<env>`)
+
+Vsync reads each line of `.env.<env>` and pushes a KV to gh/gcp. Some keys carry **file paths** instead of literal values — vsync reads the file and pushes its bytes:
+
+| In env file | Pushed as | Notes |
+|---|---|---|
+| `FOO_PATH=keys/foo` | `FOO` = file contents | suffix `_PATH` stripped; file resolved vault-relative |
+| `FOO_FILE=keys/foo` | `FOO` = file contents | suffix `_FILE` stripped; same resolution |
+| `SSH_PRIVATE_KEY_PATH=keys/dev` | `SSH_PRIVATE_KEY` = file contents | name the env-file key after the secret you want |
+| `GITHUB_TOKEN=…` | *skipped* | local-only |
+| `GOOGLE_APPLICATION_CREDENTIALS=…` | *skipped* | local-only |
+| `GITHUB_REPO=…`, `GCP_PROJECT_ID=…` | *routing meta* — never pushed | consumed by sync itself |
+
+**Path resolution.** Relative paths anchor to `VAULT_ROOT` (the directory of the env file being parsed). Three forms of placeholder expansion are recognised in **every** value — file-ref or plain:
+
+| Form | Means |
+|---|---|
+| `${VAULT_ROOT}/keys/foo` | `<vault>/keys/foo` (explicit) |
+| `keys/foo` or `./keys/foo` | `<vault>/keys/foo` (implicit — no placeholder needed) |
+| `~/.ssh/id_rsa` or `${HOME}/.ssh/id_rsa` | `$HOME/.ssh/id_rsa` |
+| `/abs/path` | absolute, pass-through |
+
+**All-or-none on file refs.** If any `*_PATH` / `*_FILE` references a missing or unreadable file, vsync collects every such error and aborts before pushing anything. No partial syncs.
+
+The canonical short-form reference lives in the header comment of [`src/envfile.ts`](src/envfile.ts); design context is in [`docs/specs/v0.6-vault-relative-file-refs.md`](docs/specs/v0.6-vault-relative-file-refs.md).
 
 ---
 
@@ -299,19 +336,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/bin/sync.ts

@@ -8,10 +8,13 @@
 // cfg.sync.gcp.project), NOT in the .env file. First run prompts for
 // missing routing and saves it; subsequent runs are zero-prompt.
 //
-// Path-expansion + skip rules in src/envfile.ts:
-//   - GCP_SA_KEY_FILE_PATH → GCP_SA_KEY (file content)
-//   - SSH_KEY_PATH → SSH_PRIVATE_KEY (file content)
+// File-reference + skip rules in src/envfile.ts (canonical short-form ref in
+// that file's header comment; design spec in docs/specs/v0.6-vault-relative-file-refs.md):
+//   - *_PATH / *_FILE          → strip suffix, push file contents under stripped name
 //   - GITHUB_TOKEN, GOOGLE_APPLICATION_CREDENTIALS skipped (local-only)
+//   - Path resolution anchors to VAULT_ROOT (dir of the .env.<env> being parsed);
+//     ${VAULT_ROOT} / ${HOME} / leading ~/ are expanded in every value.
+//   - Any missing referenced file aborts the whole sync before any push.
 
 import { join } from "node:path";
 import { parseArgs } from "../src/argv";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muthuishere/vsync",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "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"
   }
 }

package/src/envfile.ts

@@ -1,19 +1,32 @@
 // Parse a `.env.<ENV>` file into push-ready secret tasks.
 //
-// Mirrors the parsing behavior of reqsume/secrets.go:
+// Behavior overview:
 //   - skip blank lines + `#` comments
 //   - first `=` splits key/value, both trimmed
 //   - strip a single pair of surrounding `"` or `'` from the value
 //   - skip GITHUB_TOKEN / GOOGLE_APPLICATION_CREDENTIALS (local-only)
-//   - GCP_SA_KEY_FILE_PATH=<path>  → reads file, pushes as GCP_SA_KEY (must look like JSON)
-//   - SSH_KEY_PATH=<path>          → reads file, pushes as SSH_PRIVATE_KEY
+//   - placeholder expansion in every value: `${VAULT_ROOT}`, `${HOME}`,
+//     leading `~/`. `VAULT_ROOT` = the directory the env file lives in.
+//
+// File-reference convention (vsync reads the file, pushes its contents
+// under the stripped key name):
+//
+//   FOO_PATH=keys/foo            -> push as FOO with contents of <vault>/keys/foo
+//   FOO_FILE=./keys/foo          -> push as FOO with contents of <vault>/keys/foo
+//
+// Relative paths are always resolved against `VAULT_ROOT` (i.e. the env
+// file's own directory). Absolute paths and `~/` are honored as-is.
+//
+// All-or-none: if any file referenced by a `*_PATH`/`*_FILE` key is missing
+// or unreadable, parseEnvFile throws a single aggregated error and emits no
+// tasks. Sync must not run partially.
 //
 // GITHUB_REPO and GCP_PROJECT_ID are pulled out into `meta` and never pushed
 // as secrets — they're routing config consumed by sync-secrets itself.
 
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 
 export type SecretTask = { key: string; value: string };
 
@@ -25,13 +38,17 @@ export type ParsedEnv = {
 const LOCAL_ONLY = new Set(["GITHUB_TOKEN", "GOOGLE_APPLICATION_CREDENTIALS"]);
 const ROUTING = new Set(["GITHUB_REPO", "GCP_PROJECT_ID"]);
 
+const PATH_SUFFIXES = ["_PATH", "_FILE"] as const;
+
 export function parseEnvFile(path: string): ParsedEnv {
   if (!existsSync(path)) {
     throw new Error(`.env file not found: ${path}`);
   }
   const raw = readFileSync(path, "utf8");
+  const vaultRoot = dirname(path);
   const tasks: SecretTask[] = [];
   const meta: ParsedEnv["meta"] = {};
+  const errors: string[] = [];
 
   for (const rawLine of raw.split(/\r?\n/)) {
     const line = rawLine.trim();
@@ -41,41 +58,39 @@ export function parseEnvFile(path: string): ParsedEnv {
     if (eq === -1) continue;
 
     const key = line.slice(0, eq).trim();
-    let value = stripQuotes(line.slice(eq + 1).trim());
+    const rawValue = stripQuotes(line.slice(eq + 1).trim());
 
     if (LOCAL_ONLY.has(key)) {
       console.log(`Skipping ${key} (local use only)`);
       continue;
     }
 
+    const value = expandPlaceholders(rawValue, vaultRoot);
+
     if (ROUTING.has(key)) {
       meta[key as keyof ParsedEnv["meta"]] = value;
       continue;
     }
 
-    if (key === "GCP_SA_KEY_FILE_PATH") {
-      const content = readFileExpandTilde(value).trim();
-      if (!content.startsWith("{")) {
-        throw new Error(`GCP key file does not look like JSON: ${value}`);
-      }
-      tasks.push({ key: "GCP_SA_KEY", value: content });
-      continue;
-    }
-
-    if (key === "SSH_KEY_PATH") {
-      try {
-        tasks.push({ key: "SSH_PRIVATE_KEY", value: readFileExpandTilde(value) });
-      } catch (e) {
-        console.warn(
-          `Warning: error reading SSH private key from ${value}: ${(e as Error).message}`,
-        );
-      }
+    // Generic suffix rule: *_PATH or *_FILE → strip suffix, push file body.
+    const stripped = stripPathSuffix(key);
+    if (stripped) {
+      readFileRef(value, vaultRoot, key, errors, (content) => {
+        tasks.push({ key: stripped, value: content });
+      });
       continue;
     }
 
+    // Plain value.
     tasks.push({ key, value });
   }
 
+  if (errors.length > 0) {
+    throw new Error(
+      `parseEnvFile: aborting sync — ${errors.length} file reference(s) could not be resolved:\n  - ${errors.join("\n  - ")}`,
+    );
+  }
+
   return { tasks, meta };
 }
 
@@ -89,7 +104,38 @@ function stripQuotes(value: string): string {
   return value;
 }
 
-function readFileExpandTilde(path: string): string {
-  if (path.startsWith("~/")) path = join(homedir(), path.slice(2));
-  return readFileSync(path, "utf8");
+function expandPlaceholders(value: string, vaultRoot: string): string {
+  let out = value;
+  if (out.startsWith("~/")) out = join(homedir(), out.slice(2));
+  out = out.replaceAll("${VAULT_ROOT}", vaultRoot);
+  out = out.replaceAll("${HOME}", homedir());
+  return out;
+}
+
+function stripPathSuffix(key: string): string | null {
+  for (const suf of PATH_SUFFIXES) {
+    if (key.endsWith(suf) && key.length > suf.length) {
+      return key.slice(0, -suf.length);
+    }
+  }
+  return null;
+}
+
+function readFileRef(
+  value: string,
+  vaultRoot: string,
+  key: string,
+  errors: string[],
+  onSuccess: (content: string) => void,
+): void {
+  const resolved = isAbsolute(value) ? value : join(vaultRoot, value);
+  if (!existsSync(resolved)) {
+    errors.push(`${key}: file not found at ${resolved}`);
+    return;
+  }
+  try {
+    onSuccess(readFileSync(resolved, "utf8"));
+  } catch (e) {
+    errors.push(`${key}: error reading ${resolved}: ${(e as Error).message}`);
+  }
 }