@muthuishere/vsync 0.3.0

package/src/prompt.ts

@@ -0,0 +1,133 @@
+// prompt.ts — tiny TTY input helpers used by every CLI subcommand so the
+// same verb can be driven entirely by flags ("--bucket=foo --region=…")
+// for scripting, OR by interactive prompts when flags are missing.
+//
+// Three helpers:
+//   askText / askBool / askSecret   — promise-returning readline calls
+//   resolveOrAsk(value, question)   — uses the provided value or prompts
+//   confirmYes(question)            — small y/n with a default
+//
+// We deliberately avoid third-party deps. Bun ships with a global
+// `prompt()` (Web standard) for plain text. For hidden input we toggle
+// raw mode on process.stdin and read char-by-char so passphrases don't
+// echo to the screen.
+
+import { stdin, stdout } from "node:process";
+
+/** True when stdin is a real TTY (so prompts make sense). */
+export function isTty(): boolean {
+  return Boolean((stdin as any).isTTY);
+}
+
+/** Bun's global prompt(), with a default-value fallback when offered. */
+export function askText(label: string, defaultValue?: string): string {
+  const promptStr =
+    defaultValue !== undefined ? `${label} [${defaultValue}]: ` : `${label}: `;
+  const v = (globalThis as any).prompt(promptStr);
+  if (v === null || v === undefined) {
+    throw new Error("aborted (no input)");
+  }
+  const trimmed = String(v).trim();
+  return trimmed || defaultValue || "";
+}
+
+/** y/n prompt; honours a default if user just hits enter. */
+export function askBool(label: string, defaultValue: boolean): boolean {
+  const def = defaultValue ? "Y/n" : "y/N";
+  const v = (globalThis as any).prompt(`${label} [${def}]: `);
+  if (v === null || v === undefined) return defaultValue;
+  const t = String(v).trim().toLowerCase();
+  if (!t) return defaultValue;
+  return t.startsWith("y");
+}
+
+/** Hidden input — toggles raw mode on TTY and masks each keystroke. */
+export async function askSecret(label: string): Promise<string> {
+  if (!isTty()) {
+    // Non-TTY (piped stdin) — just read a line.
+    return await readLineFromStdin(label);
+  }
+  stdout.write(label + ": ");
+  return await new Promise<string>((resolve, reject) => {
+    const buf: string[] = [];
+    (stdin as any).setRawMode?.(true);
+    (stdin as any).resume?.();
+    stdin.setEncoding("utf8");
+    const onData = (chunk: string) => {
+      for (const ch of chunk) {
+        if (ch === "\n" || ch === "\r" || ch === "") {
+          (stdin as any).setRawMode?.(false);
+          stdin.off("data", onData);
+          stdin.pause();
+          stdout.write("\n");
+          resolve(buf.join("").trim());
+          return;
+        }
+        if (ch === "") {
+          (stdin as any).setRawMode?.(false);
+          stdin.off("data", onData);
+          stdin.pause();
+          stdout.write("\n");
+          reject(new Error("aborted"));
+          return;
+        }
+        if (ch === "" || ch === "\b") {
+          if (buf.length) {
+            buf.pop();
+            stdout.write("\b \b");
+          }
+          continue;
+        }
+        buf.push(ch);
+        stdout.write("*");
+      }
+    };
+    stdin.on("data", onData);
+  });
+}
+
+async function readLineFromStdin(label: string): Promise<string> {
+  if (label) stdout.write(label + ": ");
+  return await new Promise<string>((resolve) => {
+    let buf = "";
+    stdin.setEncoding("utf8");
+    const onData = (chunk: string) => {
+      buf += chunk;
+      const nl = buf.indexOf("\n");
+      if (nl >= 0) {
+        stdin.off("data", onData);
+        resolve(buf.slice(0, nl).trim());
+      }
+    };
+    stdin.once("end", () => resolve(buf.trim()));
+    stdin.on("data", onData);
+  });
+}
+
+/** Use the provided value if defined+non-empty, otherwise prompt. Throws
+ *  if not a TTY and no value was given (can't prompt non-interactively). */
+export function resolveOrAsk(
+  value: string | undefined,
+  label: string,
+  defaultValue?: string,
+): string {
+  if (value !== undefined && value !== "") return value;
+  if (!isTty()) {
+    if (defaultValue !== undefined) return defaultValue;
+    throw new Error(
+      `missing ${label} and stdin is not a TTY — pass --${label.toLowerCase().replace(/\s+/g, "-")}=… on the command line`,
+    );
+  }
+  return askText(label, defaultValue);
+}
+
+/** Yes/no confirmation. If --yes flag pre-set, returns true silently. */
+export function confirmYes(label: string, preApproved: boolean): boolean {
+  if (preApproved) return true;
+  if (!isTty()) {
+    throw new Error(
+      `${label} requires interactive confirmation — pass --yes to bypass`,
+    );
+  }
+  return askBool(label, false);
+}

package/src/repo.ts

@@ -0,0 +1,89 @@
+// repo.ts — utilities for working out which repo we're running in.
+//
+// Two things consumers need:
+//   - getRepoRoot()   — the filesystem path of the repo top-level
+//   - getRepoName()   — a short identifier used as the namespace for the
+//                       config file and keychain entry
+//
+// Repo-name precedence (first match wins):
+//   1. Explicit override (e.g. `--repo=foo` flag passed through)
+//   2. SECRETS_SYNC_REPO env var
+//   3. `name` from package.json at the repo root, with any leading scope
+//      stripped (e.g. "@muthuishere/vsync" → "vsync")
+//   4. basename of the git remote / git toplevel (e.g. "reqsume")
+//   5. basename of process.cwd() as a last resort
+//
+// All four file-paths and the keychain account are derived from the
+// resulting name, so it should be stable across machines for the same
+// repo.
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+/** Filesystem path of the repo root (git toplevel, else cwd). */
+export async function getRepoRoot(): Promise<string> {
+  const proc = Bun.spawn(["git", "rev-parse", "--show-toplevel"], {
+    stderr: "pipe",
+    stdout: "pipe",
+  });
+  const code = await proc.exited;
+  if (code === 0) {
+    return (await new Response(proc.stdout).text()).trim();
+  }
+  return process.cwd();
+}
+
+export type RepoNameOptions = {
+  /** Caller-supplied override (e.g. parsed from --repo=… flag). */
+  override?: string;
+  /** Repo root override (mostly for tests). Defaults to getRepoRoot(). */
+  root?: string;
+};
+
+/**
+ * Resolve the canonical repo name used by config file paths and keychain
+ * entries. See the precedence list at the top of this file.
+ */
+export async function getRepoName(
+  opts: RepoNameOptions = {},
+): Promise<string> {
+  const fromOverride = sanitize(opts.override);
+  if (fromOverride) return fromOverride;
+
+  const fromEnv = sanitize(process.env.SECRETS_SYNC_REPO);
+  if (fromEnv) return fromEnv;
+
+  const root = opts.root ?? (await getRepoRoot());
+
+  const fromPkg = sanitize(await readPackageName(root));
+  if (fromPkg) return fromPkg;
+
+  const fromGit = sanitize(path.basename(root));
+  if (fromGit) return fromGit;
+
+  return sanitize(path.basename(process.cwd())) || "default";
+}
+
+async function readPackageName(root: string): Promise<string | null> {
+  try {
+    const buf = await fs.readFile(path.join(root, "package.json"), "utf8");
+    const parsed = JSON.parse(buf);
+    const name: unknown = parsed?.name;
+    if (typeof name !== "string" || !name) return null;
+    // Strip npm scope: "@scope/foo" → "foo"
+    const slash = name.indexOf("/");
+    return slash >= 0 ? name.slice(slash + 1) : name;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Allow letters, digits, underscore, hyphen, and dot. Strip anything else.
+ * Empty result returns null so callers fall through to the next source.
+ */
+function sanitize(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const trimmed = value.trim().replace(/[^A-Za-z0-9._-]/g, "");
+  return trimmed || null;
+}

package/src/repoconfig.ts

@@ -0,0 +1,163 @@
+// repoconfig.ts — the on-disk per-(repo, env) half of a vsync config.
+// Self-contained: holds everything push / pull / sync need at runtime,
+// minus the encryption key (which lives in the OS keychain — see
+// keychain.ts).
+//
+// Path: ${XDG_CONFIG_HOME:-$HOME/.config}/vsync/<repo>/env_<env>
+//
+// File mode 0600, parent dir 0700. Stored as gzip(JSON) — raw bytes,
+// no base64 wrapper.
+
+import { gunzipSync, gzipSync } from "node:zlib";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+import type { S3Credentials } from "./s3";
+import { vsyncBaseDir } from "./defaults";
+
+/**
+ * On-disk shape. Self-contained — push / pull / sync read this file and
+ * the keychain entry, nothing else. `loadEnvConfig` (envconfig.ts) just
+ * splices in the keychain key.
+ *
+ * `files.vaultFolder` overrides the default `infra/vault/<env>` for
+ * monorepos. `sync.gh.repo` / `sync.gcp.project` are routing config
+ * for the `vsync sync` fanout, written on first invocation.
+ */
+export type ConfigFile = {
+  version: 1;
+  s3: S3Credentials;
+  encryption: { salt: string };
+  files?: { vaultFolder?: string };
+  sync?: {
+    gh?: { repo: string };
+    gcp?: { project: string };
+  };
+};
+
+/** Full path for a given (repo, env). env is lowercased; repo is taken as-is. */
+export function configFilePath(repo: string, env: string): string {
+  if (!repo) throw new Error("repo is required");
+  if (!env) throw new Error("env is required");
+  return path.join(vsyncBaseDir(), repo, `env_${env.toLowerCase()}`);
+}
+
+/**
+ * Persist a ConfigFile. Creates the directory tree if missing. Uses 0700
+ * on directories and 0600 on the file so other local users on the
+ * machine can't read it.
+ */
+export async function saveConfigFile(
+  repo: string,
+  env: string,
+  cfg: ConfigFile,
+): Promise<string> {
+  validateConfigFile(cfg);
+  const file = configFilePath(repo, env);
+  const dir = path.dirname(file);
+
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  try {
+    await fs.chmod(dir, 0o700);
+  } catch {
+    // Non-fatal; some filesystems (e.g. Windows) don't honour chmod.
+  }
+
+  const json = JSON.stringify(cfg);
+  const gz = gzipSync(Buffer.from(json, "utf8"));
+  await fs.writeFile(file, gz, { mode: 0o600 });
+  try {
+    await fs.chmod(file, 0o600);
+  } catch {
+    // Same caveat as above.
+  }
+  return file;
+}
+
+/**
+ * Read the on-disk config back. Returns null when the file doesn't exist
+ * (so callers can produce a "no config for <repo>/<env>" message). Any
+ * other error — corrupt gzip, malformed JSON, validation failure — is
+ * thrown.
+ */
+export async function loadConfigFile(
+  repo: string,
+  env: string,
+): Promise<ConfigFile | null> {
+  const file = configFilePath(repo, env);
+  let buf: Buffer;
+  try {
+    buf = await fs.readFile(file);
+  } catch (err: any) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTDIR")) return null;
+    throw err;
+  }
+  const json = gunzipSync(buf).toString("utf8");
+  const parsed = JSON.parse(json);
+  validateConfigFile(parsed);
+  return parsed;
+}
+
+/**
+ * Delete the on-disk config (no-op if missing). Doesn't touch the
+ * keychain — use keychain.deleteKey for that.
+ */
+export async function deleteConfigFile(
+  repo: string,
+  env: string,
+): Promise<boolean> {
+  const file = configFilePath(repo, env);
+  try {
+    await fs.unlink(file);
+    return true;
+  } catch (err: any) {
+    if (err && err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+/** Defensive shape check; mirrors validate() in envconfig.ts but key-free. */
+export function validateConfigFile(cfg: unknown): asserts cfg is ConfigFile {
+  const c = cfg as Partial<ConfigFile> | null;
+  if (!c || typeof c !== "object") throw new Error("config: not an object");
+  if (c.version !== 1) {
+    throw new Error(`config: unsupported version ${c.version} (expected 1)`);
+  }
+  const s3 = c.s3;
+  for (const k of [
+    "endpoint",
+    "region",
+    "accessKeyId",
+    "secretAccessKey",
+    "bucket",
+  ] as const) {
+    if (!s3?.[k]) throw new Error(`config: s3.${k} missing`);
+  }
+  if (typeof s3?.useSsl !== "boolean") {
+    throw new Error("config: s3.useSsl missing or not a boolean");
+  }
+  const enc = c.encryption;
+  if (!enc?.salt) throw new Error("config: encryption.salt missing");
+  if (c.files !== undefined) {
+    if (typeof c.files !== "object" || c.files === null) {
+      throw new Error("config: files must be an object if present");
+    }
+    if (
+      c.files.vaultFolder !== undefined &&
+      typeof c.files.vaultFolder !== "string"
+    ) {
+      throw new Error("config: files.vaultFolder must be a string if present");
+    }
+  }
+  if (c.sync !== undefined) {
+    if (typeof c.sync !== "object" || c.sync === null) {
+      throw new Error("config: sync must be an object if present");
+    }
+    if (c.sync.gh !== undefined && (!c.sync.gh.repo || typeof c.sync.gh.repo !== "string")) {
+      throw new Error("config: sync.gh.repo must be a string if sync.gh is present");
+    }
+    if (c.sync.gcp !== undefined && (!c.sync.gcp.project || typeof c.sync.gcp.project !== "string")) {
+      throw new Error("config: sync.gcp.project must be a string if sync.gcp is present");
+    }
+  }
+}

package/src/s3.ts

@@ -0,0 +1,25 @@
+// Bun S3 client wrapper. Credentials come from the decoded VIDEO_AI_ENV_<NAME>
+// blob; see src/envconfig.ts.
+
+export type S3Credentials = {
+  endpoint: string;
+  region: string;
+  useSsl: boolean;
+  accessKeyId: string;
+  secretAccessKey: string;
+  bucket: string;
+};
+
+export function makeClient(creds: S3Credentials) {
+  const protocol = creds.useSsl ? "https://" : "http://";
+  const endpoint = creds.endpoint.startsWith("http")
+    ? creds.endpoint
+    : protocol + creds.endpoint;
+  return new Bun.S3Client({
+    accessKeyId: creds.accessKeyId,
+    secretAccessKey: creds.secretAccessKey,
+    region: creds.region,
+    bucket: creds.bucket,
+    endpoint,
+  });
+}

package/src/sharefile.ts

@@ -0,0 +1,100 @@
+// sharefile.ts — build / parse the passphrase-encrypted share file that
+// teammates pass between machines.
+//
+// Wire format (file bytes, written verbatim — no base64 wrapper):
+//   bytes  0..3   "SLS1"           — magic for the share file itself
+//   bytes  4      saltLen (1 byte) — length of the salt that follows
+//   bytes  5..5+L salt (L bytes)   — base64-string bytes, used by PBKDF2
+//   bytes  rest                    — output of src/crypto.ts encrypt()
+//                                    (which has its own RQE1 magic + IV + ct)
+//
+// The encrypted payload is the ExportPayload JSON (config + key + repo + env).
+
+import { encrypt, decrypt } from "./crypto";
+import {
+  EXPORT_BLOB_VERSION,
+  type ExportPayload,
+  parseExportBlob,
+  buildExportBlob,
+} from "./envconfig";
+
+const SHARE_MAGIC = new Uint8Array([0x53, 0x4c, 0x53, 0x31]); // "SLS1"
+const SALT_BYTES = 16;
+
+/** Encrypt + frame the payload into a single byte sequence suitable for
+ * writing to a `.share` file. */
+export async function buildShareFile(
+  payload: ExportPayload,
+  passphrase: string,
+): Promise<Uint8Array> {
+  if (payload.version !== EXPORT_BLOB_VERSION) {
+    throw new Error(
+      `buildShareFile: payload.version ${payload.version} not supported`,
+    );
+  }
+  const saltBytes = crypto.getRandomValues(new Uint8Array(SALT_BYTES));
+  const saltStr = Buffer.from(saltBytes).toString("base64");
+
+  // Re-use envconfig.buildExportBlob so the JSON+gzip+base64 framing
+  // matches what was the env-var-era export. The result is one base64
+  // ASCII string; we encrypt those bytes.
+  const blobStr = buildExportBlob(payload);
+  const blobBytes = new TextEncoder().encode(blobStr);
+  const encrypted = await encrypt(blobBytes, passphrase, saltStr);
+
+  const saltAscii = new TextEncoder().encode(saltStr);
+  if (saltAscii.length > 0xff) {
+    throw new Error("internal: salt too long for 1-byte length prefix");
+  }
+  const out = new Uint8Array(
+    SHARE_MAGIC.length + 1 + saltAscii.length + encrypted.length,
+  );
+  let offset = 0;
+  out.set(SHARE_MAGIC, offset);
+  offset += SHARE_MAGIC.length;
+  out[offset] = saltAscii.length;
+  offset += 1;
+  out.set(saltAscii, offset);
+  offset += saltAscii.length;
+  out.set(encrypted, offset);
+  return out;
+}
+
+/** Decrypt + unframe — the inverse of buildShareFile. */
+export async function parseShareFile(
+  bytes: Uint8Array,
+  passphrase: string,
+): Promise<ExportPayload> {
+  if (bytes.length < SHARE_MAGIC.length + 1) {
+    throw new Error("share file is too short");
+  }
+  for (let i = 0; i < SHARE_MAGIC.length; i++) {
+    if (bytes[i] !== SHARE_MAGIC[i]) {
+      throw new Error(
+        "not a vsync share file (magic header missing). " +
+          "Check that you passed the file produced by `vsync export`.",
+      );
+    }
+  }
+  let offset = SHARE_MAGIC.length;
+  const saltLen = bytes[offset]!;
+  offset += 1;
+  if (bytes.length < offset + saltLen) {
+    throw new Error("share file truncated (salt header)");
+  }
+  const saltStr = new TextDecoder().decode(bytes.subarray(offset, offset + saltLen));
+  offset += saltLen;
+  const ciphertext = bytes.subarray(offset);
+
+  let decrypted: Uint8Array;
+  try {
+    decrypted = await decrypt(ciphertext, passphrase, saltStr);
+  } catch (e) {
+    throw new Error(
+      "failed to decrypt share file — passphrase wrong or file corrupt. " +
+        "Ask the sender to re-share both.",
+    );
+  }
+  const blobStr = new TextDecoder().decode(decrypted);
+  return parseExportBlob(blobStr);
+}

package/src/syncpool.ts

@@ -0,0 +1,47 @@
+// Bounded worker pool for fan-out secret pushes.
+//
+// Mirrors reqsume/secrets.go:runTasksConcurrently — N workers pull tasks off
+// a shared cursor, failures are collected (don't abort), an overall timeout
+// aborts everything via AbortSignal.
+
+import type { SecretTask } from "./envfile";
+
+export type SyncResult = { failed: string[]; ok: number };
+
+export async function runPool(
+  tasks: SecretTask[],
+  workers: number,
+  timeoutMs: number,
+  fn: (t: SecretTask, signal: AbortSignal) => Promise<void>,
+): Promise<SyncResult> {
+  const n = Math.max(1, workers);
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+
+  const failed: string[] = [];
+  let ok = 0;
+  let cursor = 0;
+
+  const worker = async () => {
+    while (!ctrl.signal.aborted) {
+      const idx = cursor++;
+      if (idx >= tasks.length) return;
+      const t = tasks[idx];
+      try {
+        await fn(t, ctrl.signal);
+        ok++;
+      } catch (e) {
+        console.error(`WARNING: skipping ${t.key}: ${(e as Error).message}`);
+        failed.push(t.key);
+      }
+    }
+  };
+
+  try {
+    await Promise.all(Array.from({ length: n }, () => worker()));
+  } finally {
+    clearTimeout(timer);
+  }
+
+  return { ok, failed };
+}

package/src/templates/docs.md.ts

@@ -0,0 +1,89 @@
+// Static onboarding reference emitted by `vsync docs`.
+//
+// Lives as a string export so it ships with the binary and stays in
+// sync with the verb set. Pipe to a file if you want to commit it:
+//   vsync docs > infra/AGENTS.md
+
+export const DOCS_MD = `# vsync — onboarding reference
+
+Generated by \`vsync docs\` and intended to be committed at the path of
+your choice (\`infra/AGENTS.md\`, \`infra/CLAUDE.md\`, etc.) so AI agents
+and teammates landing in this repo know where secrets live and how to
+work with them.
+
+## What this repo uses
+
+Secrets sync via \`@muthuishere/vsync\`. The canonical store is an
+S3-compatible bucket; per-machine state lives at
+\`~/.config/vsync/\` plus an OS keychain entry under service
+\`tools.vsync\`.
+
+## Where secret content lives
+
+\`\`\`
+infra/vault/
+  dev/
+    .env.dev
+    some-secret.json
+    ...
+  production/
+    .env.production
+\`\`\`
+
+(\`infra/vault/<env>\` is the default — a per-(repo, env) override may
+point elsewhere; check \`~/.config/vsync/<repo>/env_<env>\` for
+\`files.vaultFolder\`.)
+
+Apps point dotenv (or equivalent) at the in-vault path:
+
+\`\`\`js
+dotenv.config({ path: \`infra/vault/\${env}/.env.\${env}\` });
+\`\`\`
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| \`vsync init <env>\` | First-time setup: generate AES key, write per-repo config, create vault folder. Re-runnable. |
+| \`vsync export <env>\` | Write a passphrase-encrypted \`.share\` file to send a teammate (file + passphrase on different channels). |
+| \`vsync import <env> <file>\` | Install a teammate's \`.share\` file. No prior init required. |
+| \`vsync push <env>\` | Encrypt the vault folder and upload to S3. |
+| \`vsync pull <env>\` | Download the latest from S3 and unzip into the vault folder (auto-backs up the existing folder first). |
+| \`vsync versions <env>\` | List the available versions on S3 (read-only, no decrypt). |
+| \`vsync sync <env> <gh\\|gcp\\|all>\` | Push the vault's \`.env.<env>\` KVs out to GitHub Repo Secrets / GCP Secret Manager. |
+| \`vsync docs\` | Print this reference. |
+
+Every command takes \`--repo=<name>\` to override the auto-detected repo
+name and \`--interactive\` to force prompts. Each command works fully
+via flags or fully via prompts.
+
+## Recovering a local backup
+
+Each \`vsync pull\` writes the prior vault folder to
+\`~/.config/vsync/backups/<env>-<ts>.zip.enc\` (two-deep rolling buffer).
+The format is AES-256-GCM with the same per-(repo, env) keychain key
+plus the salt from the per-repo config. To decrypt by hand:
+
+1. Get the keychain key:
+   - macOS: \`security find-generic-password -s tools.vsync -a <repo>/<env> -w\`
+   - Linux: \`secret-tool lookup service tools.vsync account <repo>/<env>\`
+2. Get the salt: \`gunzip -c ~/.config/vsync/<repo>/env_<env> | jq -r .encryption.salt\`
+3. The envelope is \`RQE1\` (4-byte magic) + 12-byte IV + AES-GCM ciphertext.
+   Derive \`AES-256-GCM key = PBKDF2-SHA256(keychain-key, salt, 600k)\`.
+
+Easier: just \`vsync pull\` again to restore from S3.
+
+## Rules for AI agents working in this repo
+
+1. **Never commit anything under \`infra/vault/\`.** Add it to
+   \`.gitignore\` if missing.
+2. **Never read or edit files under \`~/.config/vsync/\` directly.**
+   Use the CLI verbs.
+3. **Never paste keychain keys or salts into source code, comments,
+   PR descriptions, or chat.** They're machine-local secrets.
+4. **Routing config (sync.gh.repo, sync.gcp.project) is per-(repo, env).**
+   Read it from \`~/.config/vsync/<repo>/env_<env>\` if you need to know
+   the GH repo or GCP project the team syncs to. Don't hardcode it.
+5. **If a command asks for a passphrase or share-file path, surface the
+   prompt to the human user.** Don't auto-fill or skip.
+`;