cf-envsync 0.3.0 → 0.3.1

package/README.md

@@ -93,6 +93,135 @@ envsync validate
 
 ---
 
+## 5-Minute Tutorial
+
+A complete walkthrough: project setup → local dev → deploy to staging → validate.
+
+### 1. Initialize your project
+
+```bash
+# In your monorepo root
+npm install -D cf-envsync
+envsync init --monorepo
+```
+
+This scans for `wrangler.jsonc` files, discovers your workers, and generates:
+
+```
+envsync.config.ts   ← config with all apps/workers detected
+.env.example        ← key reference (committed to git)
+.env                ← local shared secrets
+.env.staging        ← staging secrets (empty, you'll fill these)
+.env.production     ← production secrets (empty)
+.gitignore          ← updated with .env.local, .env.password, **/.dev.vars
+```
+
+### 2. Fill in your secrets
+
+```bash
+# .env — local development values (committed, encrypted)
+DATABASE_URL=postgres://localhost:5432/mydb
+JWT_SECRET=dev_jwt_secret
+AUTH_SECRET=dev_auth_secret
+API_URL=http://localhost:8787
+
+# .env.staging — staging values
+DATABASE_URL=postgres://staging-db.example.com/mydb
+JWT_SECRET=staging_jwt_secret_abc
+AUTH_SECRET=staging_auth_secret_xyz
+API_URL=https://api-staging.example.com
+
+# .env.local — YOUR dev-specific overrides (gitignored, each dev has their own)
+OAUTH_REDIRECT_URL=https://my-tunnel.ngrok.io/callback
+DEV_TUNNEL_URL=https://my-tunnel.ngrok.io
+```
+
+### 3. Encrypt before committing (optional)
+
+```bash
+# Set a password
+echo "ENVSYNC_PASSWORD=my-team-password" > .env.password
+
+# Encrypt all plain values
+envsync encrypt staging
+envsync encrypt production
+
+# Now .env.staging looks like:
+# DATABASE_URL=envsync:v1:base64payload...
+# JWT_SECRET=envsync:v1:base64payload...
+```
+
+### 4. Local development
+
+```bash
+envsync dev
+```
+
+This reads `.env` + `.env.local`, merges them, and writes `.dev.vars` into each app directory. Start wrangler as usual — it reads `.dev.vars` automatically.
+
+```
+apps/api/.dev.vars      ← DATABASE_URL, JWT_SECRET, API_URL, OAUTH_REDIRECT_URL
+apps/web/.dev.vars      ← AUTH_SECRET, VITE_API_URL, VITE_OAUTH_REDIRECT_URL
+```
+
+> **Vite / non-wrangler apps:** `.dev.vars` is for wrangler only. If your app runs with `vite dev`, set `devFile` in your config:
+>
+> ```ts
+> apps: {
+>   web: {
+>     path: "apps/web",
+>     devFile: ".env.local",          // Vite reads this
+>     // or generate both:
+>     // devFile: [".dev.vars", ".env.local"],
+>   },
+> }
+> ```
+
+If you forgot to set a per-dev override, envsync tells you:
+
+```
+⚠ Missing in .env.local: DEV_TUNNEL_URL (required per-dev override)
+  → echo "DEV_TUNNEL_URL=https://your-tunnel.example.com" >> .env.local
+```
+
+### 5. Push to staging
+
+```bash
+# Preview first
+envsync push staging --dry-run
+
+# Push for real
+envsync push staging
+#   Push 4 secrets to worker "my-api-staging" (staging)? yes
+#   ✓ Pushed 4 secrets to my-api-staging
+#   Push 1 secrets to worker "my-web-staging" (staging)? yes
+#   ✓ Pushed 1 secrets to my-web-staging
+```
+
+### 6. Validate before deploying
+
+```bash
+envsync validate
+# Checks every app × every environment against .env.example
+# Exit code 1 if anything is missing → safe for CI
+```
+
+### 7. CI/CD integration
+
+```yaml
+# GitHub Actions example
+- name: Validate env vars
+  run: envsync validate
+
+- name: Push secrets to production
+  run: envsync push production --force
+  env:
+    ENVSYNC_PASSWORD: ${{ secrets.ENVSYNC_PASSWORD }}
+    CLOUDFLARE_API_TOKEN: ${{ secrets.CF_API_TOKEN }}
+```
+
+---
+
 ## Commands
 
 ### `envsync dev` — Generate `.dev.vars`
@@ -130,6 +259,8 @@ Done!
 
 Every key shows exactly where its value came from. Missing per-dev overrides are caught immediately.
 
+> **Vite / non-wrangler apps:** Set `devFile: ".env.local"` in your app config. See [the tutorial](#4-local-development).
+
 ---
 
 ### `envsync push` — Deploy secrets
@@ -459,6 +590,7 @@ export default {
 | `apps.{name}.workers` | `Record<string, string>` | Worker name per environment |
 | `apps.{name}.secrets` | `string[]` | Secret keys pushed via `wrangler secret bulk` |
 | `apps.{name}.vars` | `string[]` | Non-secret env vars (not pushed as secrets) |
+| `apps.{name}.devFile` | `string \| string[]` | Output file(s) for `envsync dev`. Default: `".dev.vars"`. Use `".env.local"` for Vite apps, or an array for both |
 | `shared` | `string[]` | Keys with the same value across multiple apps |
 | `local.overrides` | `string[]` | Keys each developer must set in `.env.local` |
 | `local.perApp` | `Record<string, string[]>` | Per-app developer override keys |

package/dist/index.js

@@ -2315,11 +2315,13 @@ function resolveConfig(config, cwd) {
         allKeys.push(key);
       }
     }
+    const devFiles = app.devFile ? Array.isArray(app.devFile) ? app.devFile : [app.devFile] : [".dev.vars"];
     apps[name] = {
       ...app,
       name,
       absolutePath: resolve2(projectRoot, app.path),
-      allKeys
+      allKeys,
+      devFiles
     };
   }
   return {
@@ -2333,15 +2335,23 @@ function resolveApps(config, appNames) {
   if (!appNames || appNames.length === 0) {
     return Object.values(config.apps);
   }
+  const available = Object.keys(config.apps);
   const resolved = [];
+  const unknown = [];
   for (const name of appNames) {
     const app = config.apps[name];
     if (!app) {
-      consola.warn(`Unknown app: "${name}". Skipping.`);
+      unknown.push(name);
       continue;
     }
     resolved.push(app);
   }
+  if (unknown.length > 0) {
+    for (const name of unknown) {
+      consola.error(`Unknown app: "${name}". Available: ${available.join(", ")}`);
+    }
+    process.exit(1);
+  }
   return resolved;
 }
 function getWorkerName(app, environment) {
@@ -13166,6 +13176,16 @@ async function loadEnvFile(filePath, env2, projectRoot, encryption) {
     return {};
   }
   const content = await readFile(filePath);
+  if (encryption) {
+    const hasEnvsyncValues = content.includes("envsync:v1:");
+    const hasDotenvxValues = content.includes("encrypted:");
+    if (encryption === "dotenvx" && hasEnvsyncValues) {
+      consola.warn(`${filePath}: config uses encryption: "dotenvx" but file contains "envsync:v1:" (password-encrypted) values. ` + `Check your encryption setting.`);
+    }
+    if (encryption === "password" && hasDotenvxValues && !hasEnvsyncValues) {
+      consola.warn(`${filePath}: config uses encryption: "password" but file contains dotenvx-encrypted values. ` + `Check your encryption setting.`);
+    }
+  }
   if (encryption === "password") {
     const envMap = parsePlainEnv(content);
     const password = findPassword(env2, projectRoot);
@@ -13228,17 +13248,22 @@ function getLocalOverridePath(config) {
   return join3(config.projectRoot, config.raw.envFiles.local);
 }
 var init_env_file = __esm(() => {
+  init_dist2();
   init_encryption();
   init_config();
   init_fs();
 });
 
 // src/core/resolver.ts
-import { normalize } from "node:path";
+import { normalize, relative } from "node:path";
 async function resolveAppEnv(config, app, environment) {
   const layers = [];
   const encryption = config.raw.encryption;
   const rootEnvPath = getRootEnvPath(config, environment);
+  if (!fileExists(rootEnvPath) && environment !== "local" && !warnedMissingFiles.has(rootEnvPath)) {
+    warnedMissingFiles.add(rootEnvPath);
+    consola.warn(`Missing env file: ${relative(config.projectRoot, rootEnvPath)} (create it or run \`envsync init\`)`);
+  }
   const rootEnv = await loadEnvFile(rootEnvPath, environment, config.projectRoot, encryption);
   if (Object.keys(rootEnv).length > 0) {
     layers.push({ source: rootEnvPath, map: rootEnv });
@@ -13281,8 +13306,12 @@ function findMissingOverrides(config, app, localEnv) {
   }
   return missing;
 }
+var warnedMissingFiles;
 var init_resolver = __esm(() => {
+  init_dist2();
   init_env_file();
+  init_fs();
+  warnedMissingFiles = new Set;
 });
 
 // src/commands/dev.ts
@@ -13290,13 +13319,13 @@ var exports_dev = {};
 __export(exports_dev, {
   default: () => dev_default
 });
-import { join as join4, relative } from "node:path";
+import { join as join4, relative as relative2 } from "node:path";
 function parseAppNames(args) {
   const rest = args._;
   return rest?.length ? rest : undefined;
 }
 function formatSource(source, key, projectRoot, sharedKeys, localOverrideKeys) {
-  const rel = relative(projectRoot, source);
+  const rel = relative2(projectRoot, source);
   if (localOverrideKeys.has(key))
     return `${rel} (per-dev override)`;
   if (sharedKeys.has(key))
@@ -13352,26 +13381,21 @@ var init_dev = __esm(() => {
       const localEnv = await loadEnvFile(localOverridePath);
       for (const app of apps) {
         const resolved = await resolveAppEnv(config, app, environment);
-        const devVarsPath = join4(app.absolutePath, ".dev.vars");
-        const relDevVars = relative(config.projectRoot, devVarsPath);
         if (Object.keys(resolved.map).length === 0) {
           consola.warn(`  No env vars resolved for ${app.name}. Skipping.`);
           continue;
         }
-        if (args["dry-run"]) {
-          consola.log(`
-  ${relDevVars}`);
-          for (let i2 = 0;i2 < resolved.entries.length; i2++) {
-            const entry = resolved.entries[i2];
-            const isLast = i2 === resolved.entries.length - 1;
-            const prefix = isLast ? "└" : "├";
-            const src2 = formatSource(entry.source, entry.key, config.projectRoot, sharedKeys, localOverrideKeys);
-            consola.log(`  ${prefix} ${entry.key.padEnd(24)} ← ${src2}`);
+        for (const devFileName of app.devFiles) {
+          const devFilePath = join4(app.absolutePath, devFileName);
+          const relDevFile = relative2(config.projectRoot, devFilePath);
+          if (args["dry-run"]) {
+            consola.log(`
+  ${relDevFile}`);
+          } else {
+            await writeEnvFile(devFilePath, resolved.map);
+            consola.log(`
+  ${relDevFile}`);
           }
-        } else {
-          await writeEnvFile(devVarsPath, resolved.map);
-          consola.log(`
-  ${relDevVars}`);
           for (let i2 = 0;i2 < resolved.entries.length; i2++) {
             const entry = resolved.entries[i2];
             const isLast = i2 === resolved.entries.length - 1;
@@ -13385,12 +13409,18 @@ var init_dev = __esm(() => {
           if (missing.length > 0) {
             for (const key of missing) {
               consola.warn(`
-⚠ Missing in ${relative(config.projectRoot, localOverridePath)}: ${key} (required per-dev override)`);
-              consola.log(`  → echo "${key}=<your-value>" >> ${relative(config.projectRoot, localOverridePath)}`);
+⚠ Missing in ${relative2(config.projectRoot, localOverridePath)}: ${key} (required per-dev override)`);
+              consola.log(`  → echo "${key}=<your-value>" >> ${relative2(config.projectRoot, localOverridePath)}`);
             }
           }
         }
       }
+      if (environment !== "local") {
+        const hasOverrides = (config.raw.local?.overrides?.length ?? 0) > 0 || Object.keys(config.raw.local?.perApp ?? {}).length > 0;
+        if (hasOverrides) {
+          consola.info(`Per-dev overrides are only applied in "local" environment (current: ${environment}).`);
+        }
+      }
       consola.success(`
 Done!`);
     }
@@ -13572,14 +13602,33 @@ var init_push = __esm(() => {
         consola.warn("No apps to process.");
         return;
       }
+      if (args.force && !args["dry-run"]) {
+        const targets = apps.map((app) => {
+          const w2 = getWorkerName(app, environment);
+          return w2 ? `${app.name} → ${w2}` : null;
+        }).filter(Boolean);
+        if (targets.length > 0) {
+          consola.warn(`Force-pushing to ${environment}: ${targets.join(", ")}`);
+        }
+      }
       const sharedKeys = new Set(config.raw.shared ?? []);
-      for (const app of apps) {
+      let hasFailure = false;
+      if (args.shared) {
+        if (sharedKeys.size === 0) {
+          consola.error("No shared keys defined in config. Nothing to push with --shared.");
+          process.exit(1);
+        }
+        consola.info(`--shared: pushing only shared keys (${[...sharedKeys].join(", ")})`);
+      }
+      for (let i2 = 0;i2 < apps.length; i2++) {
+        const app = apps[i2];
+        const progress = apps.length > 1 ? `[${i2 + 1}/${apps.length}] ` : "";
         const workerName = getWorkerName(app, environment);
         if (!workerName) {
-          consola.warn(`  No worker defined for ${app.name} in ${environment}. Skipping.`);
+          consola.warn(`${progress}No worker defined for ${app.name} in ${environment}. Skipping.`);
           continue;
         }
-        consola.start(`Pushing secrets for ${app.name} → ${workerName} (${environment})...`);
+        consola.start(`${progress}Pushing secrets for ${app.name} → ${workerName} (${environment})...`);
         const resolved = await resolveAppEnv(config, app, environment);
         let secretsToPush;
         if (args.shared) {
@@ -13600,7 +13649,8 @@ var init_push = __esm(() => {
         }
         const keyCount = Object.keys(secretsToPush).length;
         if (keyCount === 0) {
-          consola.warn(`  No secrets to push for ${app.name}. Skipping.`);
+          const reason = args.shared ? " (no shared keys for this app)" : "";
+          consola.warn(`  No secrets to push for ${app.name}${reason}. Skipping.`);
           continue;
         }
         if (args["dry-run"]) {
@@ -13623,8 +13673,13 @@ var init_push = __esm(() => {
           consola.success(`  Pushed ${keyCount} secrets to ${workerName}`);
         } else {
           consola.error(`  Failed to push secrets to ${workerName}`);
+          hasFailure = true;
         }
       }
+      if (hasFailure) {
+        consola.error("Some pushes failed.");
+        process.exit(1);
+      }
       consola.success("Done!");
     }
   });
@@ -13760,11 +13815,18 @@ var init_validate = __esm(() => {
       let environments;
       let appNames;
       if (envArg && config.environments.includes(envArg)) {
+        if (envArg in config.apps) {
+          consola.error(`"${envArg}" is both an environment and an app name. This is ambiguous.`);
+          consola.info(`  To validate environment: envsync validate ${envArg} --
+` + `  To validate app:         envsync validate -- ${envArg}`);
+          process.exit(1);
+        }
         environments = [envArg];
         appNames = parseAppNames4(args);
       } else if (envArg) {
         environments = config.environments;
         appNames = parseAppNames4(args, 0);
+        consola.info(`"${envArg}" is not an environment. Treating as app name. Validating all environments.`);
       } else {
         environments = config.environments;
         appNames = undefined;
@@ -13783,10 +13845,12 @@ var init_validate = __esm(() => {
         ...config.raw.local?.overrides ?? [],
         ...Object.values(config.raw.local?.perApp ?? {}).flat()
       ]);
+      const totalChecks = environments.length * apps.length;
       consola.log(`
-Checking against .env.example...`);
+Checking against .env.example... (${environments.length} env × ${apps.length} app${apps.length > 1 ? "s" : ""})`);
       const results = [];
       let hasIssues = false;
+      let checkIdx = 0;
       for (const environment of environments) {
         consola.log(`
   ${environment}`);
@@ -13951,8 +14015,15 @@ var init_diff = __esm(() => {
         process.exit(1);
       }
       const target = args.target;
-      const isEnvVsEnv = target && config.environments.includes(target);
-      if (isEnvVsEnv) {
+      const isEnv = target && config.environments.includes(target);
+      const isApp = target && target in config.apps;
+      if (isEnv && isApp) {
+        consola.error(`"${target}" is both an environment and an app name. This is ambiguous.`);
+        consola.info(`  To compare environments: envsync diff ${env1} ${target} --
+` + `  To diff local vs remote: envsync diff ${env1} -- ${target}`);
+        process.exit(1);
+      }
+      if (isEnv) {
         const env2 = target;
         const appNames = parseAppNames5(args, 2);
         const apps = resolveApps(config, appNames);
@@ -14049,7 +14120,7 @@ var exports_init = {};
 __export(exports_init, {
   default: () => init_default
 });
-import { join as join6, relative as relative2, basename } from "node:path";
+import { join as join6, relative as relative3, basename } from "node:path";
 function generateConfigTS(config) {
   const lines = [
     `import { defineConfig } from "cf-envsync";`,
@@ -14133,7 +14204,16 @@ var init_init = __esm(() => {
       const existingConfig = CONFIG_FILES.find((f3) => fileExists(join6(cwd, f3)));
       if (existingConfig) {
         consola.warn(`${existingConfig} already exists.`);
-        const overwrite = await consola.prompt("Overwrite?", {
+        const existingContent = await readFile(join6(cwd, existingConfig));
+        const lines = existingContent.split(`
+`);
+        const preview = lines.length > 20 ? [...lines.slice(0, 20), `  ... (${lines.length - 20} more lines)`].join(`
+`) : existingContent;
+        consola.log(`
+Current config:
+${preview}
+`);
+        const overwrite = await consola.prompt("Overwrite with new config?", {
           type: "confirm"
         });
         if (!overwrite) {
@@ -14160,12 +14240,13 @@ var init_init = __esm(() => {
           return (name === "wrangler.json" || name === "wrangler.jsonc") && !f3.includes("node_modules");
         });
         if (wranglerFiles.length === 0) {
-          consola.warn("No wrangler config files found. Creating manually.");
+          consola.warn(`No wrangler.json or wrangler.jsonc files found (searched all subdirectories, excluding node_modules).
+` + "  Falling back to manual configuration.");
         }
         for (const wranglerFile of wranglerFiles.sort()) {
           const fullPath = join6(cwd, wranglerFile);
           const appDir = join6(cwd, wranglerFile, "..");
-          const appPath = relative2(cwd, appDir);
+          const appPath = relative3(cwd, appDir);
           const appName = basename(appDir);
           consola.info(`  Found ${wranglerFile}`);
           let wranglerConfig = {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cf-envsync",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Sync .env files to Cloudflare Workers secrets, .dev.vars, and more",
   "type": "module",
   "exports": {

package/src/types/config.ts

@@ -41,6 +41,9 @@ export interface AppConfig {
   secrets?: string[];
   /** Var keys for this app (non-secret env vars) */
   vars?: string[];
+  /** Output file(s) for `envsync dev`. Defaults to ".dev.vars".
+   *  Use an array to generate multiple files, e.g. [".dev.vars", ".env.local"] */
+  devFile?: string | string[];
 }
 
 /** Resolved config after defaults and path resolution */
@@ -62,4 +65,6 @@ export interface ResolvedAppConfig extends AppConfig {
   absolutePath: string;
   /** All keys this app needs (secrets + vars + local overrides) */
   allKeys: string[];
+  /** Normalized output file names for `envsync dev` (always an array) */
+  devFiles: string[];
 }