fix(cloudflare): debounce wrangler restarts and skip when env is unchanged

Agent-Logs-Url: https://github.com/dmno-dev/varlock/sessions/ef8b4df3-0fb0-4ccb-b2e2-c90dac16c7d6

Co-authored-by: theoephraim <1158956+theoephraim@users.noreply.github.com>

Author: Copilot

.changeset/debounce-unchanged-env-restart.md

@@ -0,0 +1,10 @@
+---
+"@varlock/cloudflare-integration": patch
+---
+
+fix(cloudflare): debounce wrangler restarts and skip when env is unchanged
+
+`varlock-wrangler dev` now caches the serialized resolved env graph and compares it
+after each debounced watch event. Wrangler only restarts when the resolved env has
+actually changed, preventing restart loops caused by spurious `fs.watch()` events
+on macOS (which can emit events even when file contents are identical).

framework-tests/frameworks/cloudflare/wrangler.test.ts

@@ -192,6 +192,58 @@ describe('Cloudflare Workers varlock-wrangler only', () => {
     ],
   });
 
+  wranglerEnv.describeDevScenario('no restart on unchanged env content', {
+    command: 'varlock-wrangler dev --port 18792',
+    readyPattern: /Ready on|ready in/i,
+    readyTimeout: 30_000,
+    templateFiles: {
+      'src/index.ts': { path: 'workers/basic-worker.ts', prepend: "import '@varlock/cloudflare-integration/init';\n" },
+      'wrangler.jsonc': '_base-wrangler/wrangler.jsonc',
+      'tsconfig.json': '_base-wrangler/tsconfig.json',
+    },
+    requests: [
+      // first request — baseline
+      {
+        path: '/',
+        bodyAssertions: {
+          shouldContain: ['public_var::public-test-value'],
+        },
+      },
+      // second request — write the same .env.schema content (simulates macOS spurious watch events)
+      // use fileEditDelay so we wait without expecting a restart
+      {
+        path: '/',
+        fileEdits: {
+          '.env.schema': [
+            '# @defaultSensitive=false @defaultRequired=infer',
+            '# @currentEnv=$APP_ENV',
+            '# ---',
+            '',
+            '# @type=enum(dev, prod)',
+            'APP_ENV=dev',
+            '',
+            'PUBLIC_VAR=public-test-value',
+            'API_URL=https://api.example.com',
+            '',
+            '# @sensitive',
+            'SECRET_KEY=super-secret-value',
+          ].join('\n'),
+        },
+        // wait longer than the 300ms debounce to confirm no restart occurred
+        fileEditDelay: 1500,
+        bodyAssertions: {
+          shouldContain: ['public_var::public-test-value'],
+        },
+      },
+    ],
+    outputAssertions: [
+      {
+        description: 'wrangler is not restarted when env content is unchanged',
+        shouldNotContain: ['env changed, restarting wrangler'],
+      },
+    ],
+  });
+
   describe('invalid config', () => {
     wranglerEnv.describeScenario('invalid schema causes dev failure', {
       command: 'varlock-wrangler dev --port 18791',

packages/integrations/cloudflare/src/varlock-wrangler.ts

@@ -413,12 +413,21 @@ async function handleDev(args: Array<string>) {
 
   // watch env source files for changes and restart wrangler with fresh data
   let restartTimeout: ReturnType<typeof setTimeout> | undefined;
+  let cachedGraphJson = loaded.json;
   function scheduleRestart() {
-    // debounce — multiple files may change at once
+    // debounce — multiple files may change at once (e.g. editor saves multiple files,
+    // or macOS fs.watch() emits extra events for unchanged files)
     if (restartTimeout) clearTimeout(restartTimeout);
     restartTimeout = setTimeout(() => {
       try {
         const freshLoaded = loadSerializedGraph();
+        // compare serialized JSON strings — only restart when the resolved env actually changed
+        if (freshLoaded.json === cachedGraphJson) {
+          restartTimeout = undefined;
+          return;
+        }
+        cachedGraphJson = freshLoaded.json;
+        loaded = freshLoaded;
         cachedContent = formatEnvFileContent(freshLoaded);
         handle.update(cachedContent);
         console.log('[varlock-wrangler] env changed, restarting wrangler...');