@muthuishere/vsync 0.3.0

package/bin/sync.ts

@@ -0,0 +1,279 @@
+#!/usr/bin/env bun
+// Usage: vsync sync <env> <gh|gcp|all> [--gh-repo=<owner/name>] [--gcp-project=<id>]
+//
+// Reads <vaultFolder>/.env.<env> and pushes each variable to the named
+// secret backend, in parallel (6 workers, 10-min overall timeout).
+//
+// Routing config lives in the per-repo vsync file (cfg.sync.gh.repo /
+// 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)
+
+import { join } from "node:path";
+import { parseArgs } from "../src/argv";
+import { parseEnvFile, type SecretTask } from "../src/envfile";
+import { runPool } from "../src/syncpool";
+import { getRepoName, getRepoRoot } from "../src/repo";
+import {
+  loadConfigFile,
+  saveConfigFile,
+  type ConfigFile,
+} from "../src/repoconfig";
+import { resolveVaultFolder } from "../src/envconfig";
+import { askText, isTty } from "../src/prompt";
+
+const TARGETS = ["gh", "gcp", "all"] as const;
+type Target = (typeof TARGETS)[number];
+
+const WORKERS = 6;
+const TIMEOUT_MS = 10 * 60 * 1000;
+
+export async function main(argv: string[]): Promise<void> {
+  const { positional, flags } = 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>");
+    process.exit(1);
+  }
+
+  const repo = await getRepoName({ override: flags.repo });
+  const root = await getRepoRoot();
+
+  const cfg = await loadConfigFile(repo, env);
+  if (!cfg) {
+    console.error(
+      `no config file for ${repo}/${env}. Run 'vsync init ${env}' first.`,
+    );
+    process.exit(1);
+  }
+
+  const vaultFolder = resolveVaultFolder(cfg, env);
+  const envFilePath = join(root, vaultFolder, `.env.${env}`);
+
+  let parsed;
+  try {
+    parsed = parseEnvFile(envFilePath);
+  } catch (e) {
+    console.error((e as Error).message);
+    process.exit(1);
+  }
+
+  const { tasks } = parsed;
+  if (tasks.length === 0) {
+    console.error(`no secrets to sync from ${envFilePath}`);
+    process.exit(1);
+  }
+
+  const targets: Array<"gh" | "gcp"> =
+    target === "all" ? ["gh", "gcp"] : [target];
+
+  // Resolve + persist routing for every target we're about to run.
+  let cfgMutated = false;
+  const ghRepo = targets.includes("gh")
+    ? await resolveGhRepo(cfg, flags, () => {
+        cfgMutated = true;
+      })
+    : undefined;
+  const gcpProject = targets.includes("gcp")
+    ? await resolveGcpProject(cfg, flags, () => {
+        cfgMutated = true;
+      })
+    : undefined;
+
+  if (cfgMutated) {
+    await saveConfigFile(repo, env, cfg);
+  }
+
+  let totalOk = 0;
+  const totalFailed: string[] = [];
+
+  for (const t of targets) {
+    const start = Date.now();
+    let result;
+    if (t === "gh") {
+      await ensureBinary("gh");
+      console.log(
+        `\nSyncing ${tasks.length} secrets to GitHub: repo=${ghRepo}, environment=${env}`,
+      );
+      result = await runPool(tasks, WORKERS, TIMEOUT_MS, (task, signal) =>
+        setGhSecret(task, ghRepo!, env, signal),
+      );
+    } else {
+      await ensureBinary("gcloud");
+      console.log(
+        `\nSyncing ${tasks.length} secrets to GCP Secret Manager: project=${gcpProject}`,
+      );
+      result = await runPool(tasks, WORKERS, TIMEOUT_MS, (task, signal) =>
+        setGcpSecret(task, gcpProject!, signal),
+      );
+    }
+    const elapsed = ((Date.now() - start) / 1000).toFixed(1);
+    if (result.failed.length > 0) {
+      console.log(
+        `  ${t}: ${result.ok} ok, ${result.failed.length} failed (${result.failed.join(", ")}) in ${elapsed}s`,
+      );
+    } else {
+      console.log(`  ${t}: all ${result.ok} synced in ${elapsed}s`);
+    }
+    totalOk += result.ok;
+    totalFailed.push(...result.failed.map((k) => `${t}:${k}`));
+  }
+
+  if (totalFailed.length > 0) {
+    console.log(`\nDone — ${totalOk} ok, ${totalFailed.length} failed.`);
+    process.exit(1);
+  }
+  console.log(`\n✅ All ${totalOk} secrets synced across ${targets.length} target(s).`);
+}
+
+async function resolveGhRepo(
+  cfg: ConfigFile,
+  flags: Record<string, string>,
+  markMutated: () => void,
+): Promise<string> {
+  if (flags["gh-repo"]) {
+    setSync(cfg, "gh", { repo: flags["gh-repo"] }, markMutated);
+    return flags["gh-repo"];
+  }
+  if (cfg.sync?.gh?.repo) return cfg.sync.gh.repo;
+  if (!isTty()) {
+    throw new Error(
+      "sync.gh.repo not configured for this (repo, env) and no --gh-repo flag passed.",
+    );
+  }
+  const value = askText("GitHub repo for sync (owner/name)");
+  if (!value) throw new Error("aborted (empty gh repo)");
+  setSync(cfg, "gh", { repo: value }, markMutated);
+  return value;
+}
+
+async function resolveGcpProject(
+  cfg: ConfigFile,
+  flags: Record<string, string>,
+  markMutated: () => void,
+): Promise<string> {
+  if (flags["gcp-project"]) {
+    setSync(cfg, "gcp", { project: flags["gcp-project"] }, markMutated);
+    return flags["gcp-project"];
+  }
+  if (cfg.sync?.gcp?.project) return cfg.sync.gcp.project;
+  if (!isTty()) {
+    throw new Error(
+      "sync.gcp.project not configured for this (repo, env) and no --gcp-project flag passed.",
+    );
+  }
+  const value = askText("GCP project ID for sync");
+  if (!value) throw new Error("aborted (empty gcp project)");
+  setSync(cfg, "gcp", { project: value }, markMutated);
+  return value;
+}
+
+function setSync(
+  cfg: ConfigFile,
+  target: "gh" | "gcp",
+  block: ConfigFile["sync"] extends infer S ? S extends undefined ? never : NonNullable<S>[typeof target] : never,
+  markMutated: () => void,
+): void {
+  cfg.sync = cfg.sync ?? {};
+  // @ts-expect-error structural assignment narrowed by target
+  cfg.sync[target] = block;
+  markMutated();
+}
+
+async function setGhSecret(
+  t: SecretTask,
+  repo: string,
+  environment: string,
+  signal: AbortSignal,
+): Promise<void> {
+  console.log(`Setting secret: ${t.key}`);
+  const proc = Bun.spawn({
+    cmd: ["gh", "secret", "set", t.key, "--env", environment, "--repo", repo],
+    stdin: new TextEncoder().encode(t.value),
+    stdout: "pipe",
+    stderr: "pipe",
+    signal,
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    throw new Error(`gh secret set: ${stderr || `exit ${code}`}`);
+  }
+  console.log(`✓ ${t.key}`);
+}
+
+async function setGcpSecret(
+  t: SecretTask,
+  project: string,
+  signal: AbortSignal,
+): Promise<void> {
+  console.log(`Setting secret: ${t.key}`);
+
+  const exists = await secretExists(t.key, project, signal);
+
+  const cmd = exists
+    ? ["gcloud", "secrets", "versions", "add", t.key, "--data-file=-", `--project=${project}`]
+    : [
+        "gcloud", "secrets", "create", t.key,
+        "--replication-policy=automatic",
+        "--data-file=-",
+        `--project=${project}`,
+      ];
+
+  const proc = Bun.spawn({
+    cmd,
+    stdin: new TextEncoder().encode(t.value),
+    stdout: "pipe",
+    stderr: "pipe",
+    signal,
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    throw new Error(`${cmd[1]} ${cmd[2]}: ${stderr || `exit ${code}`}`);
+  }
+  console.log(`✓ ${t.key}`);
+}
+
+async function secretExists(
+  name: string,
+  project: string,
+  signal: AbortSignal,
+): Promise<boolean> {
+  const proc = Bun.spawn({
+    cmd: ["gcloud", "secrets", "describe", name, `--project=${project}`],
+    stdout: "pipe",
+    stderr: "pipe",
+    signal,
+  });
+  return (await proc.exited) === 0;
+}
+
+async function ensureBinary(name: string): Promise<void> {
+  const proc = Bun.spawn({
+    cmd: ["which", name],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if ((await proc.exited) !== 0) {
+    console.error(`${name} not found on PATH — install it before running vsync sync.`);
+    process.exit(1);
+  }
+}
+
+if (import.meta.main) {
+  await main(process.argv.slice(2));
+}

package/bin/versions.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env bun
+// Usage: vsync versions <env> [--repo=<name>]
+//
+// Lists s3://<bucket>/<env>/versions/ — one line per <ts>.enc with size
+// and age, with a `* latest` marker on the version <env>/latest currently
+// points at. Read-only; doesn't decrypt anything (so no keychain key is
+// needed — just the per-repo file with S3 creds).
+
+import { parseArgs } from "../src/argv";
+import { getRepoName } from "../src/repo";
+import { loadConfigFile, configFilePath } from "../src/repoconfig";
+import { makeClient } from "../src/s3";
+
+export async function main(argv: string[]): Promise<void> {
+  const { positional, flags } = parseArgs(argv);
+  const env = positional[0];
+  if (!env) {
+    console.error("usage: vsync versions <env> [--repo=<name>]");
+    process.exit(1);
+  }
+  const repo = await getRepoName({ override: flags.repo });
+
+  const cfg = await loadConfigFile(repo, env);
+  if (!cfg) {
+    console.error(
+      `no config file for ${repo}/${env} at ${configFilePath(repo, env)}.\n` +
+        `Run 'vsync init ${env}' first, or 'vsync import ${env} <share-file>' if a teammate sent you one.`,
+    );
+    process.exit(1);
+  }
+
+  const client = makeClient(cfg.s3);
+  const prefix = `${repo}/${env.toLowerCase()}/versions/`;
+
+  let listing;
+  try {
+    listing = await client.list({ prefix });
+  } catch (e) {
+    console.error(`failed to list s3://${cfg.s3.bucket}/${prefix}: ${(e as Error).message}`);
+    process.exit(1);
+  }
+
+  // Read the latest pointer in parallel with the listing — empty/missing
+  // is OK (means no successful push yet).
+  let latestTs = "";
+  try {
+    latestTs = (await client.file(`${repo}/${env.toLowerCase()}/latest`).text()).trim();
+  } catch {
+    // No pointer yet.
+  }
+
+  const objects = (listing?.contents ?? [])
+    .filter((o: any) => typeof o?.key === "string" && o.key.endsWith(".enc"))
+    .map((o: any) => {
+      const fname = o.key.slice(prefix.length); // <ts>.enc
+      const ts = fname.replace(/\.enc$/, "");
+      return {
+        ts,
+        key: o.key as string,
+        size: typeof o.size === "number" ? o.size : 0,
+        lastModified:
+          o.lastModified instanceof Date
+            ? o.lastModified
+            : o.lastModified
+              ? new Date(o.lastModified)
+              : null,
+      };
+    })
+    .sort((a, b) => (a.ts < b.ts ? 1 : a.ts > b.ts ? -1 : 0)); // newest first
+
+  if (objects.length === 0) {
+    console.log(`(no versions yet at s3://${cfg.s3.bucket}/${prefix})`);
+    return;
+  }
+
+  console.log(`s3://${cfg.s3.bucket}/${prefix}  (${objects.length} version${objects.length === 1 ? "" : "s"})`);
+  for (const o of objects) {
+    const marker = o.ts === latestTs ? " *" : "  ";
+    const size = formatSize(o.size);
+    const age = o.lastModified ? formatAge(o.lastModified) : "?";
+    console.log(`${marker} ${o.ts}   ${size.padStart(8)}   ${age}`);
+  }
+  if (latestTs && !objects.some((o) => o.ts === latestTs)) {
+    console.log(`\n⚠  pointer claims ${latestTs} but no matching version object found.`);
+  }
+}
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function formatAge(d: Date): string {
+  const ms = Date.now() - d.getTime();
+  const sec = Math.max(0, Math.floor(ms / 1000));
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  const day = Math.floor(hr / 24);
+  return `${day}d ago`;
+}
+
+if (import.meta.main) {
+  await main(process.argv.slice(2));
+}

package/bin/vsync.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env bun
+// Single CLI entry point. Dispatches to the per-subcommand modules.
+//
+// All subcommands accept (and many require):
+//   <env>            positional — lowercase: dev, local, production, …
+//   --repo=<name>    override the auto-detected repo name
+//                    (env SECRETS_SYNC_REPO → package.json::name → git basename → cwd)
+//   --interactive    force interactive prompts even when flags provided
+//
+// Designed for `bunx @muthuishere/vsync <subcommand> ...`.
+
+const SUBCOMMANDS = [
+  "init",
+  "export",
+  "import",
+  "push",
+  "pull",
+  "versions",
+  "sync",
+  "docs",
+] as const;
+type Subcommand = (typeof SUBCOMMANDS)[number];
+
+function usage(code = 0): never {
+  const out = code === 0 ? console.log : console.error;
+  out("usage: vsync <subcommand> [args...]");
+  out("");
+  out("setup");
+  out("  init <env> [flags]              create per-(repo, env) config + AES key");
+  out("");
+  out("sharing");
+  out("  export <env> [--out=path]       write a passphrase-encrypted .share file");
+  out("  import <env> <share-file>       restore a .share file into local config + keychain");
+  out("");
+  out("day-to-day");
+  out("  push <env>                      encrypt + upload local vault folder to s3://<bucket>/<repo>/<env>/");
+  out("  pull <env>                      download from s3://<bucket>/<repo>/<env>/ + decrypt + unpack");
+  out("  versions <env>                  list versions on S3 for this (repo, env) (read-only)");
+  out("");
+  out("external fanout");
+  out("  sync <env> <gh|gcp|all>         push <vaultFolder>/.env.<env> KVs to GH/GCP secret stores");
+  out("");
+  out("docs");
+  out("  docs                            print the onboarding reference to stdout");
+  out("");
+  out("All commands accept --repo=<name> (defaults: $SECRETS_SYNC_REPO →");
+  out("package.json::name → git basename → cwd basename) and --interactive.");
+  process.exit(code);
+}
+
+const subcommand = process.argv[2];
+const subArgv = process.argv.slice(3);
+
+if (!subcommand || subcommand === "--help" || subcommand === "-h") usage(0);
+
+if (!SUBCOMMANDS.includes(subcommand as Subcommand)) {
+  console.error(`unknown subcommand: ${subcommand}`);
+  usage(1);
+}
+
+switch (subcommand as Subcommand) {
+  case "init": {
+    const { main } = await import("./init");
+    await main(subArgv);
+    break;
+  }
+  case "export": {
+    const { main } = await import("./export");
+    await main(subArgv);
+    break;
+  }
+  case "import": {
+    const { main } = await import("./import");
+    await main(subArgv);
+    break;
+  }
+  case "push": {
+    const { main } = await import("./push");
+    await main(subArgv);
+    break;
+  }
+  case "pull": {
+    const { main } = await import("./pull");
+    await main(subArgv);
+    break;
+  }
+  case "versions": {
+    const { main } = await import("./versions");
+    await main(subArgv);
+    break;
+  }
+  case "sync": {
+    const { main } = await import("./sync");
+    await main(subArgv);
+    break;
+  }
+  case "docs": {
+    const { main } = await import("./docs");
+    await main(subArgv);
+    break;
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@muthuishere/vsync",
+  "version": "0.3.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": {
+    "vsync": "./bin/vsync.ts"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "keywords": [
+    "secrets",
+    "env",
+    "dotenv",
+    "vault",
+    "s3",
+    "keychain",
+    "encryption",
+    "bun",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/muthuishere/vsync.git"
+  },
+  "homepage": "https://github.com/muthuishere/vsync#readme",
+  "bugs": {
+    "url": "https://github.com/muthuishere/vsync/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.2.21"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest"
+  }
+}

package/src/archive.ts

@@ -0,0 +1,89 @@
+// Folder ⇄ zip helpers. Shells out to system `zip` / `unzip`.
+
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync } from "node:fs";
+
+// Zip a folder's contents into a temp .zip file. Returns the path to the zip.
+// The folder's children are placed at the zip root (preserves subdirectory
+// structure inside the folder, but not the folder name itself).
+export async function zipFolder(folderPath: string): Promise<string> {
+  const out = join(
+    tmpdir(),
+    `pkg-${Date.now()}-${Math.random().toString(36).slice(2)}.zip`,
+  );
+  const proc = Bun.spawn(["zip", "-r", "-q", out, "."], {
+    cwd: folderPath,
+    stderr: "pipe",
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const err = await new Response(proc.stderr).text();
+    throw new Error(`zip exited ${code}: ${err.trim()}`);
+  }
+  return out;
+}
+
+// Zip a list of paths (files and/or folders) relative to baseDir into one
+// temp zip. Paths are stored at their relative locations, so unzipping back
+// at baseDir restores them exactly. Returns the zip's path.
+export async function zipPaths(
+  baseDir: string,
+  paths: string[],
+): Promise<string> {
+  if (paths.length === 0) {
+    throw new Error("zipPaths: no paths supplied");
+  }
+  const out = join(
+    tmpdir(),
+    `bundle-${Date.now()}-${Math.random().toString(36).slice(2)}.zip`,
+  );
+  const proc = Bun.spawn(["zip", "-r", "-q", out, ...paths], {
+    cwd: baseDir,
+    stderr: "pipe",
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const err = await new Response(proc.stderr).text();
+    throw new Error(`zip exited ${code}: ${err.trim()}`);
+  }
+  return out;
+}
+
+// Zip a list of paths (files and/or folders) relative to baseDir into a zip
+// at outPath. Paths are stored at their relative locations, so unzipping at
+// baseDir restores them exactly.
+export async function zipPaths(
+  baseDir: string,
+  paths: string[],
+  outPath: string,
+): Promise<void> {
+  if (paths.length === 0) {
+    throw new Error("zipPaths: no paths supplied");
+  }
+  const proc = Bun.spawn(["zip", "-r", "-q", outPath, ...paths], {
+    cwd: baseDir,
+    stderr: "pipe",
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const err = await new Response(proc.stderr).text();
+    throw new Error(`zip exited ${code}: ${err.trim()}`);
+  }
+}
+
+// Extract zipPath into targetFolder, creating it if missing. Overwrites.
+export async function unzipTo(
+  zipPath: string,
+  targetFolder: string,
+): Promise<void> {
+  mkdirSync(targetFolder, { recursive: true });
+  const proc = Bun.spawn(["unzip", "-q", "-o", zipPath, "-d", targetFolder], {
+    stderr: "pipe",
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const err = await new Response(proc.stderr).text();
+    throw new Error(`unzip exited ${code}: ${err.trim()}`);
+  }
+}

package/src/argv.ts

@@ -0,0 +1,34 @@
+// Minimal argv parser: positional args + --key=value (or --key) flags.
+// Stops parsing at `--` (everything after is positional).
+
+export type ParsedArgs = {
+  positional: string[];
+  flags: Record<string, string>;
+};
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const positional: string[] = [];
+  const flags: Record<string, string> = {};
+  let passthrough = false;
+  for (const arg of argv) {
+    if (passthrough) {
+      positional.push(arg);
+      continue;
+    }
+    if (arg === "--") {
+      passthrough = true;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const eq = arg.indexOf("=");
+      if (eq === -1) {
+        flags[arg.slice(2)] = "true";
+      } else {
+        flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags };
+}