@muthuishere/vsync 0.5.1 → 0.6.0

package/README.md

@@ -200,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:
 
-- `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`.
+- `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`.
+
+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
 
@@ -242,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.
 
@@ -252,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).
 
 ---
 

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.1",
+  "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": {

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}`);
+  }
 }