convex-env-sync 0.1.0 → 0.1.1

package/README.md

@@ -1,15 +1,70 @@
 # convex-env-sync
 
-To install dependencies:
+A CLI tool that syncs environment variables with Convex using a locally defined `.env.convex` file. This saves you the hassle of having to go to the dashboard to configure environment variables. On startup, it performs an initial sync, then watches the file for changes and periodically polls the Convex deployment for remote updates.
+
+It uses the official Convex CLI internally to read, set, and remove environment variables.
+
+This tool intentionally does **not** attempt to provide type-safe access to environment variables inside your Convex functions. If you’re looking for that functionality, use [convex-env by @bentsignal](https://github.com/bentsignal/convex-env) (both tools can be used together).
+
+## Guide
 
 ```bash
-bun install
+npx convex-env-sync
 ```
 
-To run:
+### Adding Variables
 
-```bash
-bun run index.ts
+To add a variable to Convex, define it in your `.env.convex` file:
+
+```env
+API_KEY=sk-123
+```
+
+The variable will be added to Convex when the file is saved.
+
+### Deleting Variables
+
+To delete a variable from Convex, set its value to `__DELETE__`:
+
+```env
+# This will delete API_KEY from Convex
+API_KEY=__DELETE__
+```
+
+The variable will be removed from Convex and deleted from the local file on save.
+
+## Note
+
+If the deployment and the local file have the same variables with different values, the local file takes precedence. This is because it is intended for use with dev deployments, in which you are usually the only user. To sync down the dev deployment version, simply delete the `.env.convex` file and run `npx convex-env-sync`.
+
+### Setup in package.json
+
+You will usually want to run this alongside your Convex dev server:
+
+```json
+{
+  "scripts": {
+    "dev:convex": "npx convex-env-sync & convex dev"
+  }
+}
 ```
 
-This project was created using `bun init` in bun v1.3.5. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### Options
+
+| Option             | Description                                         |
+| ------------------ | --------------------------------------------------- |
+| `--file <path>`    | Path to env file (default: `.env.convex`)           |
+| `--once`           | Run a single sync and exit                          |
+| `--no-write-back`  | Prevent updating the local file from remote changes |
+| `--poll <seconds>` | Polling interval for remote changes (default: 300)  |
+| `-h, --help`       | Show help message                                   |
+
+## Requirements
+
+* Node.js 18+
+* Convex CLI configured in the project (`convex dev` must work)
+* Can be run via `bunx`, `npx`, or `pnpm dlx`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,2 +1,38 @@
 #!/usr/bin/env node
-export {};
+export interface EnvVars {
+    [key: string]: string;
+}
+export interface CLIOptions {
+    file: string;
+    once: boolean;
+    writeBack: boolean;
+    poll: number;
+}
+export interface SyncDeps {
+    getRemoteVars: () => Promise<EnvVars>;
+    setRemoteVar: (key: string, value: string) => Promise<void>;
+    deleteRemoteVar: (key: string) => Promise<void>;
+    readLocalVars: (filePath: string) => EnvVars;
+    writeLocalVars: (filePath: string, vars: EnvVars) => void;
+    fileExists: (filePath: string) => boolean;
+}
+export interface SyncState {
+    lastKnownRemoteVars: EnvVars;
+    isSyncing: boolean;
+}
+export declare const DELETE_MARKER = "__DELETE__";
+export declare function parseArgs(argv?: string[]): CLIOptions;
+export declare function parseEnvFile(content: string): EnvVars;
+export declare function serializeEnvFile(vars: EnvVars): string;
+export interface SyncResult {
+    setRemoteCalls: Array<{
+        key: string;
+        value: string;
+    }>;
+    deleteRemoteCalls: string[];
+    localWritten: EnvVars | null;
+    newLastKnownRemoteVars: EnvVars;
+    pulledFromRemote: string[];
+    deletedFromLocal: string[];
+}
+export declare function syncCore(deps: SyncDeps, options: Pick<CLIOptions, "writeBack">, filePath: string, isInitialSync: boolean, state: SyncState): Promise<SyncResult | null>;

package/dist/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { spawn } from "child_process";
-import { watch, existsSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, readFileSync, watch, writeFileSync } from "fs";
 import { resolve } from "path";
-const DELETE_MARKER = "__DELETE__";
-function parseArgs() {
-    const args = process.argv.slice(2);
+export const DELETE_MARKER = "__DELETE__";
+export function parseArgs(argv) {
+    const args = argv ?? process.argv.slice(2);
     const options = {
         file: ".env.convex",
         once: false,
@@ -25,12 +25,17 @@ function parseArgs() {
             options.writeBack = false;
         }
         else if (arg === "--poll" && nextArg) {
-            options.poll = parseInt(nextArg, 10);
+            const parsed = parseInt(nextArg, 10);
+            if (isNaN(parsed) || parsed <= 0) {
+                console.error(`Invalid poll interval "${nextArg}", using default ${options.poll}`);
+            }
+            else {
+                options.poll = parsed;
+            }
             i++;
         }
         else if (arg === "--help" || arg === "-h") {
-            console.log(`
-convex-env-sync - Sync environment variables with Convex
+            console.log(`convex-env-sync - Sync environment variables with Convex
 
 Usage: convex-env-sync [options]
 
@@ -42,17 +47,15 @@ Options:
   -h, --help         Show this help message
 
 Special values:
-  __DELETE__         Set a variable to this value to delete it from Convex
-`);
+  __DELETE__         Set a variable to this value to delete it from Convex`);
             process.exit(0);
         }
     }
     return options;
 }
-function parseEnvFile(content) {
+export function parseEnvFile(content) {
     const vars = {};
-    const lines = content.split("\n");
-    for (const line of lines) {
+    for (const line of content.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed || trimmed.startsWith("#"))
             continue;
@@ -61,22 +64,21 @@ function parseEnvFile(content) {
             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("'"))) {
+        if (value.startsWith('"') && value.endsWith('"')) {
+            value = value.slice(1, -1).replace(/\\"/g, '"');
+        }
+        else if (value.startsWith("'") && value.endsWith("'")) {
             value = value.slice(1, -1);
         }
-        if (key) {
+        if (key)
             vars[key] = value;
-        }
     }
     return vars;
 }
-function serializeEnvFile(vars) {
+export 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, '\\"')}"`;
         }
@@ -84,6 +86,74 @@ function serializeEnvFile(vars) {
     })
         .join("\n") + "\n");
 }
+export async function syncCore(deps, options, filePath, isInitialSync, state) {
+    if (state.isSyncing)
+        return null;
+    const result = {
+        setRemoteCalls: [],
+        deleteRemoteCalls: [],
+        localWritten: null,
+        newLastKnownRemoteVars: {},
+        pulledFromRemote: [],
+        deletedFromLocal: [],
+    };
+    const remoteVars = await deps.getRemoteVars();
+    const localVars = deps.readLocalVars(filePath);
+    const fileExists = deps.fileExists(filePath);
+    if (isInitialSync && !fileExists) {
+        deps.writeLocalVars(filePath, remoteVars);
+        result.localWritten = remoteVars;
+        result.newLastKnownRemoteVars = { ...remoteVars };
+        return result;
+    }
+    const toSetRemote = {};
+    const toDeleteRemote = [];
+    let updatedLocalVars = { ...localVars };
+    let localNeedsWrite = false;
+    for (const [key, value] of Object.entries(localVars)) {
+        if (value === DELETE_MARKER) {
+            if (key in remoteVars)
+                toDeleteRemote.push(key);
+            delete updatedLocalVars[key];
+            localNeedsWrite = true;
+        }
+        else if (remoteVars[key] !== value) {
+            toSetRemote[key] = value;
+        }
+    }
+    if (options.writeBack) {
+        for (const [key, value] of Object.entries(remoteVars)) {
+            if (!(key in localVars) && !(key in toSetRemote)) {
+                updatedLocalVars[key] = value;
+                localNeedsWrite = true;
+                result.pulledFromRemote.push(key);
+            }
+        }
+        for (const key of Object.keys(state.lastKnownRemoteVars)) {
+            if (!(key in remoteVars) &&
+                key in localVars &&
+                localVars[key] !== DELETE_MARKER) {
+                delete updatedLocalVars[key];
+                localNeedsWrite = true;
+                result.deletedFromLocal.push(key);
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(toSetRemote)) {
+        await deps.setRemoteVar(key, value);
+        result.setRemoteCalls.push({ key, value });
+    }
+    for (const key of toDeleteRemote) {
+        await deps.deleteRemoteVar(key);
+        result.deleteRemoteCalls.push(key);
+    }
+    if (localNeedsWrite && options.writeBack) {
+        deps.writeLocalVars(filePath, updatedLocalVars);
+        result.localWritten = updatedLocalVars;
+    }
+    result.newLastKnownRemoteVars = await deps.getRemoteVars();
+    return result;
+}
 function runConvexCommand(args) {
     return new Promise((resolve, reject) => {
         const proc = spawn("npx", ["convex", ...args], {
@@ -114,10 +184,7 @@ function runConvexCommand(args) {
 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) {
+    for (const line of output.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed)
             continue;
@@ -126,24 +193,24 @@ async function getRemoteVars() {
             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("'"))) {
+        if (value.startsWith('"') && value.endsWith('"')) {
+            value = value.slice(1, -1).replace(/\\"/g, '"');
+        }
+        else if (value.startsWith("'") && value.endsWith("'")) {
             value = value.slice(1, -1);
         }
-        if (key) {
+        if (key)
             vars[key] = value;
-        }
     }
     return vars;
 }
 async function setRemoteVar(key, value) {
     await runConvexCommand(["env", "set", key, value]);
-    console.log(`  ✓ Set ${key}`);
+    console.log(`pushed ${key}`);
 }
 async function deleteRemoteVar(key) {
     await runConvexCommand(["env", "remove", key]);
-    console.log(`  ✓ Deleted ${key}`);
+    console.log(`deleted ${key}`);
 }
 function readLocalVars(filePath) {
     if (!existsSync(filePath)) {
@@ -156,104 +223,47 @@ 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...");
+    if (isSyncing)
         return;
-    }
     isSyncing = true;
     const filePath = resolve(options.file);
+    const deps = {
+        getRemoteVars,
+        setRemoteVar,
+        deleteRemoteVar,
+        readLocalVars,
+        writeLocalVars,
+        fileExists: existsSync,
+    };
     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);
+        const fileExistedBefore = existsSync(filePath);
+        const result = await syncCore(deps, options, filePath, isInitialSync, {
+            lastKnownRemoteVars,
+            isSyncing: false,
+        });
+        if (result) {
+            if (isInitialSync && !fileExistedBefore && result.localWritten) {
+                const count = Object.keys(result.localWritten).length;
+                if (count > 0) {
+                    console.log(`created ${options.file} with ${count} var${count === 1 ? "" : "s"} from Convex`);
                 }
-                // 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}`);
+                else {
+                    console.log(`created ${options.file} (empty)`);
                 }
             }
-            // 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}`);
-                }
+            for (const key of result.pulledFromRemote) {
+                console.log(`pulled ${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.");
+            for (const key of result.deletedFromLocal) {
+                console.log(`removed ${key}`);
+            }
+            lastKnownRemoteVars = result.newLastKnownRemoteVars;
         }
     }
     catch (error) {
-        console.error("Sync error:", error instanceof Error ? error.message : error);
+        console.error("error:", error instanceof Error ? error.message : error);
     }
     finally {
         isSyncing = false;
@@ -270,65 +280,37 @@ function debounce(fn, 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.");
+        console.log("synced");
         process.exit(0);
     }
-    // Set up file watcher with debounce
+    console.log(`watching ${options.file}`);
     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) {
+        if (watcher)
             watcher.close();
-        }
         if (existsSync(filePath)) {
             watcher = watch(filePath, (eventType) => {
-                if (eventType === "change") {
-                    console.log(`\nFile change detected...`);
+                if (eventType === "change")
                     debouncedSync();
-                }
-            });
-            watcher.on("error", (error) => {
-                console.error("Watcher error:", error);
-                // Try to re-establish watcher
-                setTimeout(setupWatcher, 1000);
             });
+            watcher.on("error", () => 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...");
+    const pollInterval = setInterval(() => sync(options, false), options.poll * 1000);
+    const shutdown = () => {
         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);
-    });
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
 }
 main().catch((error) => {
-    console.error("Fatal error:", error);
+    console.error("fatal:", error);
     process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convex-env-sync",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Sync environment variables with Convex using a separate .env.convex file",
   "type": "module",
   "bin": {