@muthuishere/vsync 0.5.1 → 0.7.0

package/README.md

@@ -194,23 +194,47 @@ Every command works fully via flags or fully via prompts.
 | `push <env>` | Zip the resolved vault folder → manifest-seal → AES-256-GCM encrypt → upload to `s3://<bucket>/<repo>/<env>/versions/<ts>.enc`, then update `s3://<bucket>/<repo>/<env>/latest`. Flags: `--no-audit`, `--note=<text>`, `--meta key=value` (repeatable). |
 | `pull <env>` | Read `latest` pointer → download version → verify embedded manifest timestamp matches pointer (anti-rollback) → decrypt → unzip into the resolved vault folder. Auto-backs up existing contents first. Flags: `--no-audit`, `--note=<text>`, `--meta key=value` (repeatable). |
 | `versions <env>` | List `s3://<bucket>/<repo>/<env>/versions/`. One line per version with size + age, `* latest` marker on the active one. Read-only; no decrypt. |
-| `sync <env> <gh\|gcp\|all>` | Read `<vaultFolder>/.env.<env>` → push each KV to the named target. Parallel (6 workers, 10-min timeout). First run prompts for routing config (gh repo / gcp project) and saves it; subsequent runs zero-prompt. Flags: `--gh-repo=<owner/name>`, `--gcp-project=<id>`. |
+| `sync <env> <gh\|gcp\|all>` | Read `<vaultFolder>/.env.<env>` → push each KV to the named target. Parallel (6 workers, 10-min timeout). First run prompts for routing config (gh repo / gcp project) and saves it; subsequent runs zero-prompt. Parser has no defaults — pass `--inline-file-suffix=<suf>` and `--exclude-property=<key>` (both repeatable) to control file inlining and excluded keys; see "Typical `vsync sync` invocation" below. Flags: `--inline-file-suffix=<suf>`, `--exclude-property=<key>`, `--gh-repo=<owner/name>`, `--gcp-project=<id>`. |
 | `audit <env>` | Print the S3-side audit log: who/where/when of every pull/push/import/export. Flags: `--limit=N`, `--all`, `--csv`. |
 | `docs` | Print a short onboarding reference (commands, vault layout, backup recovery procedure) to stdout. Pipe wherever you want — e.g. `vsync docs > infra/AGENTS.md`. |
 
 ### `sync` env-file parsing
 
-Two special-case keys (path → file content inlining):
+As of v0.7 the parser has **zero implicit policy** — no hardcoded suffixes, no hardcoded exclude list, no defaults applied by the CLI. Every rule is named at the call site.
 
-- `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`.
+**File references — opt in with `--inline-file-suffix=<suf>` (repeatable).** Any key in `.env.<env>` whose name ends in a configured suffix is read from disk; vsync pushes the file's contents under the key with the suffix stripped. Pass `--inline-file-suffix=_PATH --inline-file-suffix=_FILE` for the v0.6 shape:
 
-Two local-only keys (skipped — used by `gh` / `gcloud` on the local machine, not pushed):
+- `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).
+
+**Excluded keys — opt in with `--exclude-property=<key>` (repeatable).** Any key in this list is dropped from the run and never pushed. Typical candidates are tokens that exist locally for `gh` / `gcloud` to use directly:
 
 - `GITHUB_TOKEN`
 - `GOOGLE_APPLICATION_CREDENTIALS`
 
-Everything else is pushed verbatim.
+If you pass no `--exclude-property` flag at all, **nothing is skipped** — every KV gets pushed. Same for `--inline-file-suffix`: with no flag, no file inlining happens.
+
+Every `vsync sync` run prints the active parser policy header before the first push, so you can see exactly which rules were in effect. Full convention in [`docs/guide/sync.md`](docs/guide/sync.md) and design context in [`docs/specs/v0.7-explicit-sync-parser.md`](docs/specs/v0.7-explicit-sync-parser.md).
+
+### Typical `vsync sync` invocation
+
+The parser has no defaults. Pass the rules you want, every time. The shape
+that matches v0.6 behavior is:
+
+```bash
+vsync sync dev gh \
+  --inline-file-suffix=_PATH \
+  --inline-file-suffix=_FILE \
+  --exclude-property=GITHUB_TOKEN \
+  --exclude-property=GOOGLE_APPLICATION_CREDENTIALS
+```
+
+Drop this into your Taskfile / Makefile / CI so the call site shows the
+whole policy at a glance.
+
+**Migrating from v0.6?** Bare `vsync sync dev gh` no longer skips `GITHUB_TOKEN` / `GOOGLE_APPLICATION_CREDENTIALS` and no longer inlines `*_PATH` / `*_FILE`. Append the four flags above to every invocation to preserve the old behavior. The in-env routing keys `GITHUB_REPO` / `GCP_PROJECT_ID` are also no longer recognized — move them into config via `--gh-repo` / `--gcp-project` (persisted) and delete the lines from `.env.<env>`. See [`docs/specs/v0.7-explicit-sync-parser.md`](docs/specs/v0.7-explicit-sync-parser.md) §5 for full migration steps.
 
 ### Audit log
 
@@ -242,7 +266,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 (using the `--inline-file-suffix` / `--exclude-property` flags you passed — see 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 +276,38 @@ 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.
+
+Every run also prints the active parser policy header before the first push, so the operator can see which suffixes and exclusions were in effect for this invocation.
+
+### File-reference convention (`.env.<env>`) — explicit opt-in
+
+Vsync reads each line of `.env.<env>` and pushes a KV to gh/gcp. When you pass `--inline-file-suffix=<suffix>`, keys ending in that suffix are treated as file paths — vsync reads the file and pushes its bytes under the stripped name.
+
+With `--inline-file-suffix=_PATH --inline-file-suffix=_FILE` in effect:
+
+| 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 |
+
+With no `--inline-file-suffix` flag, no inlining happens — `FOO_PATH=keys/foo` is pushed as the literal string `keys/foo`.
+
+With `--exclude-property=GITHUB_TOKEN --exclude-property=GOOGLE_APPLICATION_CREDENTIALS` in effect, those keys are dropped from the run. With no `--exclude-property` flag, nothing is skipped.
+
+**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 configured file-ref 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.7-explicit-sync-parser.md`](docs/specs/v0.7-explicit-sync-parser.md).
 
 ---
 
@@ -305,7 +360,9 @@ In practice, just don't lose the keychain entry. `pull` itself is the recovery p
 
 | 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.7.0** | `vsync sync` parser has zero implicit policy. New repeatable flags `--inline-file-suffix=<suf>` and `--exclude-property=<key>` replace the old hardcoded `_PATH` / `_FILE` suffixes and the implicit `GITHUB_TOKEN` / `GOOGLE_APPLICATION_CREDENTIALS` skip-list — name every rule at the call site. In-env routing keys `GITHUB_REPO` / `GCP_PROJECT_ID` are no longer recognized (routing lives in config only). Every run prints the active policy header before pushing. Two intentional breaks vs. 0.6.x — see [`docs/specs/v0.7-explicit-sync-parser.md`](docs/specs/v0.7-explicit-sync-parser.md) §5. |
+| 0.6.0 | `.env.<env>` file-reference convention: any key ending in `_PATH` / `_FILE` is read from disk and the file's contents are pushed under the stripped name. Paths anchor to `VAULT_ROOT`; `${VAULT_ROOT}` / `${HOME}` / `~/` placeholders work in every value. All-or-none on missing files. (Superseded in 0.7 — suffixes are no longer hardcoded; pass `--inline-file-suffix` explicitly.) |
+| 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. |
 

package/bin/sync.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
-// Usage: vsync sync <env> <gh|gcp|all> [--gh-repo=<owner/name>] [--gcp-project=<id>]
+// Usage: vsync sync <env> <gh|gcp|all>
+//          [--inline-file-suffix=<suf>] (repeatable)
+//          [--exclude-property=<key>]   (repeatable)
+//          [--gh-repo=<owner/name>] [--gcp-project=<id>] [--repo=<name>]
 //
 // Reads <vaultFolder>/.env.<env> and pushes each variable to the named
 // secret backend, in parallel (6 workers, 10-min overall timeout).
@@ -8,10 +11,17 @@
 // 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)
-//   - GITHUB_TOKEN, GOOGLE_APPLICATION_CREDENTIALS skipped (local-only)
+// Parser policy is explicit per-invocation (v0.7 — zero defaults; see
+// docs/specs/v0.7-explicit-sync-parser.md):
+//   - --inline-file-suffix=<suf>   keys ending in <suf> are file refs; the
+//                                  suffix is stripped and the file's bytes
+//                                  are pushed under the stripped name.
+//                                  Repeatable. Omit = no file inlining.
+//   - --exclude-property=<key>     keys to drop (never pushed). Repeatable.
+//                                  Omit = nothing skipped.
+//   - 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";
@@ -33,22 +43,18 @@ const WORKERS = 6;
 const TIMEOUT_MS = 10 * 60 * 1000;
 
 export async function main(argv: string[]): Promise<void> {
-  const { positional, flags } = parseArgs(argv);
+  const { positional, flags, lists } = parseArgs(argv);
   const env = positional[0];
   const target = positional[1] as Target | undefined;
 
   if (!env || !target || !TARGETS.includes(target)) {
-    console.error("usage: vsync sync <env> <gh|gcp|all>");
-    console.error("");
-    console.error("  env     environment name; reads <vaultFolder>/.env.<env>");
-    console.error("  gh      push to GitHub repo secrets (env = <env>)");
-    console.error("  gcp     push to GCP Secret Manager (project from cfg.sync.gcp.project)");
-    console.error("  all     push to every configured target");
-    console.error("");
-    console.error("Flags: --gh-repo=<owner/name>, --gcp-project=<id>, --repo=<name>");
+    usage();
     process.exit(1);
   }
 
+  const inlineFileSuffixes = lists["inline-file-suffix"] ?? [];
+  const excludeProperties = lists["exclude-property"] ?? [];
+
   const repo = await getRepoName({ override: flags.repo });
   const root = await getRepoRoot();
 
@@ -63,15 +69,20 @@ export async function main(argv: string[]): Promise<void> {
   const vaultFolder = resolveVaultFolder(cfg, env);
   const envFilePath = join(root, vaultFolder, `.env.${env}`);
 
+  printPolicyHeader(inlineFileSuffixes, excludeProperties);
+
   let parsed;
   try {
-    parsed = parseEnvFile(envFilePath);
+    parsed = parseEnvFile(envFilePath, {
+      inlineFileSuffixes,
+      excludeProperties,
+    });
   } catch (e) {
     console.error((e as Error).message);
     process.exit(1);
   }
 
-  const { tasks } = parsed;
+  const { tasks, skipped } = parsed;
   if (tasks.length === 0) {
     console.error(`no secrets to sync from ${envFilePath}`);
     process.exit(1);
@@ -108,6 +119,7 @@ export async function main(argv: string[]): Promise<void> {
       console.log(
         `\nSyncing ${tasks.length} secrets to GitHub: repo=${ghRepo}, environment=${env}`,
       );
+      printSkipped(skipped);
       result = await runPool(tasks, WORKERS, TIMEOUT_MS, (task, signal) =>
         setGhSecret(task, ghRepo!, env, signal),
       );
@@ -116,6 +128,7 @@ export async function main(argv: string[]): Promise<void> {
       console.log(
         `\nSyncing ${tasks.length} secrets to GCP Secret Manager: project=${gcpProject}`,
       );
+      printSkipped(skipped);
       result = await runPool(tasks, WORKERS, TIMEOUT_MS, (task, signal) =>
         setGcpSecret(task, gcpProject!, signal),
       );
@@ -139,6 +152,51 @@ export async function main(argv: string[]): Promise<void> {
   console.log(`\n✅ All ${totalOk} secrets synced across ${targets.length} target(s).`);
 }
 
+function usage(): void {
+  console.error("usage: vsync sync <env> <gh|gcp|all>");
+  console.error("");
+  console.error("  env     environment name; reads <vaultFolder>/.env.<env>");
+  console.error("  gh      push to GitHub repo secrets (env = <env>)");
+  console.error("  gcp     push to GCP Secret Manager (project from cfg.sync.gcp.project)");
+  console.error("  all     push to every configured target");
+  console.error("");
+  console.error("Parser policy (no defaults — pass explicitly):");
+  console.error("  --inline-file-suffix=<suf>   key suffix that turns a value into a file ref (repeatable)");
+  console.error("  --exclude-property=<key>     key to skip entirely (repeatable)");
+  console.error("");
+  console.error("Routing flags: --gh-repo=<owner/name>, --gcp-project=<id>, --repo=<name>");
+}
+
+/** Print the active parser policy to stdout (spec v0.7 §4.1). */
+export function printPolicyHeader(
+  inlineFileSuffixes: string[],
+  excludeProperties: string[],
+): void {
+  console.log("\nParser policy:");
+  if (inlineFileSuffixes.length === 0) {
+    console.log("  inline-file-suffix: (none — file refs disabled)");
+  } else {
+    for (const suf of inlineFileSuffixes) {
+      console.log(`  inline-file-suffix: ${suf}`);
+    }
+  }
+  if (excludeProperties.length === 0) {
+    console.log("  exclude-property:   (none — nothing skipped)");
+  } else {
+    for (const key of excludeProperties) {
+      console.log(`  exclude-property:   ${key}`);
+    }
+  }
+}
+
+function printSkipped(
+  skipped: Array<{ key: string; reason: "excluded" }>,
+): void {
+  for (const s of skipped) {
+    console.log(`  skipped (${s.reason}): ${s.key}`);
+  }
+}
+
 async function resolveGhRepo(
   cfg: ConfigFile,
   flags: Record<string, string>,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muthuishere/vsync",
-  "version": "0.5.1",
+  "version": "0.7.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,37 +1,68 @@
 // Parse a `.env.<ENV>` file into push-ready secret tasks.
 //
-// Mirrors the parsing behavior of reqsume/secrets.go:
+// Zero-policy parser (v0.7): the parser carries no defaults. Every rule that
+// affects what gets pushed is supplied by the caller via `ParseOptions`.
+//
+// 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
+//   - keys listed in `opts.excludeProperties` are dropped onto `skipped` and
+//     never pushed; passing `[]` means nothing is skipped.
+//   - keys ending in one of `opts.inlineFileSuffixes` (and strictly longer
+//     than the suffix) are treated as file references — the suffix is
+//     stripped and the file's bytes are pushed under the stripped key.
+//     Passing `[]` disables file inlining entirely.
+//   - placeholder expansion in every value: `${VAULT_ROOT}`, `${HOME}`,
+//     leading `~/`. `VAULT_ROOT` = the directory the env file lives in.
+//     Disable with `opts.expandPlaceholders === false`.
+//
+// File-reference convention (when a suffix is configured, e.g. `_PATH`):
+//
+//   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.
 //
-// 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.
+// All-or-none: if any file referenced by an inline-file-suffix key is missing
+// or unreadable, parseEnvFile throws a single aggregated error and emits no
+// tasks. Sync must not run partially.
 
 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 };
 
+export type ParseOptions = {
+  /** Suffixes that turn a key into a file reference. Empty = no inlining. */
+  inlineFileSuffixes: string[];
+
+  /** Keys to skip entirely (never pushed). Empty = nothing skipped. */
+  excludeProperties: string[];
+
+  /** Placeholder expansion in values. Default true. */
+  expandPlaceholders?: boolean;
+};
+
 export type ParsedEnv = {
   tasks: SecretTask[];
-  meta: { GITHUB_REPO?: string; GCP_PROJECT_ID?: string };
+  skipped: Array<{ key: string; reason: "excluded" }>;
 };
 
-const LOCAL_ONLY = new Set(["GITHUB_TOKEN", "GOOGLE_APPLICATION_CREDENTIALS"]);
-const ROUTING = new Set(["GITHUB_REPO", "GCP_PROJECT_ID"]);
-
-export function parseEnvFile(path: string): ParsedEnv {
+export function parseEnvFile(path: string, opts: ParseOptions): 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 skipped: ParsedEnv["skipped"] = [];
+  const errors: string[] = [];
+
+  const excludeSet = new Set(opts.excludeProperties);
+  const expand = opts.expandPlaceholders !== false;
 
   for (const rawLine of raw.split(/\r?\n/)) {
     const line = rawLine.trim();
@@ -41,42 +72,35 @@ 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)`);
+    if (excludeSet.has(key)) {
+      skipped.push({ key, reason: "excluded" });
       continue;
     }
 
-    if (ROUTING.has(key)) {
-      meta[key as keyof ParsedEnv["meta"]] = value;
-      continue;
-    }
+    const value = expand ? expandPlaceholders(rawValue, vaultRoot) : rawValue;
 
-    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: caller-supplied suffixes → strip + inline file.
+    const stripped = stripFileSuffix(key, opts.inlineFileSuffixes);
+    if (stripped) {
+      readFileRef(value, vaultRoot, key, errors, (content) => {
+        tasks.push({ key: stripped, value: content });
+      });
       continue;
     }
 
+    // Plain value.
     tasks.push({ key, value });
   }
 
-  return { tasks, meta };
+  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, skipped };
 }
 
 function stripQuotes(value: string): string {
@@ -89,7 +113,39 @@ 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 stripFileSuffix(key: string, suffixes: string[]): string | null {
+  for (const suf of suffixes) {
+    if (!suf) continue;
+    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}`);
+  }
 }