convex-env-sync 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johannes Schießl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# convex-env-sync
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.3.5. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+import { spawn } from "child_process";
+import { watch, existsSync, readFileSync, writeFileSync } from "fs";
+import { resolve } from "path";
+const DELETE_MARKER = "__DELETE__";
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const options = {
+        file: ".env.convex",
+        once: false,
+        writeBack: true,
+        poll: 300,
+    };
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        const nextArg = args[i + 1];
+        if (arg === "--file" && nextArg) {
+            options.file = nextArg;
+            i++;
+        }
+        else if (arg === "--once") {
+            options.once = true;
+        }
+        else if (arg === "--no-write-back") {
+            options.writeBack = false;
+        }
+        else if (arg === "--poll" && nextArg) {
+            options.poll = parseInt(nextArg, 10);
+            i++;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            console.log(`
+convex-env-sync - Sync environment variables with Convex
+
+Usage: convex-env-sync [options]
+
+Options:
+  --file <path>      Path to env file (default: .env.convex)
+  --once             Run a single sync and exit
+  --no-write-back    Prevent updating local file from remote changes
+  --poll <seconds>   Polling interval for remote changes (default: 300)
+  -h, --help         Show this help message
+
+Special values:
+  __DELETE__         Set a variable to this value to delete it from Convex
+`);
+            process.exit(0);
+        }
+    }
+    return options;
+}
+function parseEnvFile(content) {
+    const vars = {};
+    const lines = content.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        // Handle quoted values
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key) {
+            vars[key] = value;
+        }
+    }
+    return vars;
+}
+function serializeEnvFile(vars) {
+    return (Object.entries(vars)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => {
+        // Quote values that contain spaces or special characters
+        if (value.includes(" ") || value.includes('"') || value.includes("=")) {
+            value = `"${value.replace(/"/g, '\\"')}"`;
+        }
+        return `${key}=${value}`;
+    })
+        .join("\n") + "\n");
+}
+function runConvexCommand(args) {
+    return new Promise((resolve, reject) => {
+        const proc = spawn("npx", ["convex", ...args], {
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: process.platform === "win32",
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                resolve(stdout);
+            }
+            else {
+                reject(new Error(`Convex command failed: ${stderr || stdout}`));
+            }
+        });
+        proc.on("error", (err) => {
+            reject(err);
+        });
+    });
+}
+async function getRemoteVars() {
+    const output = await runConvexCommand(["env", "list"]);
+    const vars = {};
+    // Parse the output from `convex env list`
+    // Format is typically: VAR_NAME=value or VAR_NAME="value"
+    const lines = output.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        // Handle quoted values
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (key) {
+            vars[key] = value;
+        }
+    }
+    return vars;
+}
+async function setRemoteVar(key, value) {
+    await runConvexCommand(["env", "set", key, value]);
+    console.log(`  ✓ Set ${key}`);
+}
+async function deleteRemoteVar(key) {
+    await runConvexCommand(["env", "remove", key]);
+    console.log(`  ✓ Deleted ${key}`);
+}
+function readLocalVars(filePath) {
+    if (!existsSync(filePath)) {
+        return {};
+    }
+    const content = readFileSync(filePath, "utf-8");
+    return parseEnvFile(content);
+}
+function writeLocalVars(filePath, vars) {
+    writeFileSync(filePath, serializeEnvFile(vars));
+}
+let lastKnownRemoteVars = {};
+let lastKnownLocalVars = {};
+let isSyncing = false;
+async function sync(options, isInitialSync) {
+    if (isSyncing) {
+        console.log("Sync already in progress, skipping...");
+        return;
+    }
+    isSyncing = true;
+    const filePath = resolve(options.file);
+    try {
+        console.log(`\n[${new Date().toLocaleTimeString()}] Starting sync...`);
+        // Get current state
+        const remoteVars = await getRemoteVars();
+        const localVars = readLocalVars(filePath);
+        const fileExists = existsSync(filePath);
+        // On initial sync with no local file, pull everything from remote
+        if (isInitialSync && !fileExists) {
+            console.log("Initial sync: pulling remote variables to local file...");
+            if (Object.keys(remoteVars).length > 0) {
+                writeLocalVars(filePath, remoteVars);
+                console.log(`  ✓ Created ${options.file} with ${Object.keys(remoteVars).length} variables`);
+            }
+            else {
+                writeLocalVars(filePath, {});
+                console.log(`  ✓ Created empty ${options.file}`);
+            }
+            lastKnownRemoteVars = { ...remoteVars };
+            lastKnownLocalVars = { ...remoteVars };
+            console.log("Sync complete.");
+            return;
+        }
+        // Track what needs to change
+        const toSetRemote = {};
+        const toDeleteRemote = [];
+        let updatedLocalVars = { ...localVars };
+        let localNeedsWrite = false;
+        // Process local variables -> push to remote
+        for (const [key, value] of Object.entries(localVars)) {
+            if (value === DELETE_MARKER) {
+                // User wants to delete this variable
+                if (key in remoteVars) {
+                    toDeleteRemote.push(key);
+                }
+                // Remove from local vars
+                delete updatedLocalVars[key];
+                localNeedsWrite = true;
+            }
+            else if (remoteVars[key] !== value) {
+                // Variable is new or changed locally
+                toSetRemote[key] = value;
+            }
+        }
+        // Process remote variables -> sync missing vars back to local
+        if (options.writeBack) {
+            // Add remote variables that are missing locally (re-sync from remote)
+            for (const [key, value] of Object.entries(remoteVars)) {
+                if (!(key in localVars) && !(key in toSetRemote)) {
+                    // Variable exists in Convex but not locally - add it back
+                    updatedLocalVars[key] = value;
+                    localNeedsWrite = true;
+                    console.log(`  ← Synced from remote: ${key}`);
+                }
+            }
+            // Check for remote deletions (was in lastKnownRemoteVars but not in current remote)
+            for (const key of Object.keys(lastKnownRemoteVars)) {
+                if (!(key in remoteVars) && key in localVars && localVars[key] !== DELETE_MARKER) {
+                    // Variable was deleted remotely
+                    delete updatedLocalVars[key];
+                    localNeedsWrite = true;
+                    console.log(`  ← Remote deletion detected: ${key}`);
+                }
+            }
+        }
+        // Apply remote changes
+        for (const [key, value] of Object.entries(toSetRemote)) {
+            await setRemoteVar(key, value);
+        }
+        for (const key of toDeleteRemote) {
+            await deleteRemoteVar(key);
+        }
+        // Write back to local file if needed
+        if (localNeedsWrite && options.writeBack) {
+            writeLocalVars(filePath, updatedLocalVars);
+            console.log(`  ✓ Updated ${options.file}`);
+        }
+        // Update last known state
+        lastKnownRemoteVars = await getRemoteVars(); // Re-fetch after our changes
+        lastKnownLocalVars = readLocalVars(filePath);
+        const totalChanges = Object.keys(toSetRemote).length + toDeleteRemote.length + (localNeedsWrite ? 1 : 0);
+        if (totalChanges === 0) {
+            console.log("No changes detected.");
+        }
+        else {
+            console.log("Sync complete.");
+        }
+    }
+    catch (error) {
+        console.error("Sync error:", error instanceof Error ? error.message : error);
+    }
+    finally {
+        isSyncing = false;
+    }
+}
+function debounce(fn, ms) {
+    let timeoutId = null;
+    return (...args) => {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => fn(...args), ms);
+    };
+}
+async function main() {
+    const options = parseArgs();
+    const filePath = resolve(options.file);
+    console.log("Convex Environment Variable Sync");
+    console.log("================================");
+    console.log(`File: ${filePath}`);
+    console.log(`Write-back: ${options.writeBack}`);
+    console.log(`Poll interval: ${options.poll}s`);
+    console.log(`Mode: ${options.once ? "one-time sync" : "continuous watch"}`);
+    // Initial sync
+    await sync(options, true);
+    if (options.once) {
+        console.log("\nOne-time sync complete. Exiting.");
+        process.exit(0);
+    }
+    // Set up file watcher with debounce
+    const debouncedSync = debounce(() => sync(options, false), 500);
+    console.log(`\nWatching ${options.file} for changes...`);
+    console.log("Press Ctrl+C to exit.\n");
+    // Watch for file changes
+    let watcher = null;
+    const setupWatcher = () => {
+        if (watcher) {
+            watcher.close();
+        }
+        if (existsSync(filePath)) {
+            watcher = watch(filePath, (eventType) => {
+                if (eventType === "change") {
+                    console.log(`\nFile change detected...`);
+                    debouncedSync();
+                }
+            });
+            watcher.on("error", (error) => {
+                console.error("Watcher error:", error);
+                // Try to re-establish watcher
+                setTimeout(setupWatcher, 1000);
+            });
+        }
+    };
+    setupWatcher();
+    // Poll for remote changes
+    const pollInterval = setInterval(() => {
+        console.log(`\nPolling remote...`);
+        sync(options, false);
+    }, options.poll * 1000);
+    // Handle graceful shutdown
+    process.on("SIGINT", () => {
+        console.log("\n\nShutting down...");
+        if (watcher)
+            watcher.close();
+        clearInterval(pollInterval);
+        process.exit(0);
+    });
+    process.on("SIGTERM", () => {
+        console.log("\n\nShutting down...");
+        if (watcher)
+            watcher.close();
+        clearInterval(pollInterval);
+        process.exit(0);
+    });
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "convex-env-sync",
+  "version": "0.1.0",
+  "description": "Sync environment variables with Convex using a separate .env.convex file",
+  "type": "module",
+  "bin": {
+    "convex-env-sync": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "convex",
+    "env",
+    "environment",
+    "variables",
+    "sync",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/johannesschiessl/convex-env-sync"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5"
+  },
+  "peerDependencies": {
+    "convex": "*"
+  },
+  "peerDependenciesMeta": {
+    "convex": {
+      "optional": true
+    }
+  }
+}