@whatalo/cli-kit 1.0.2 → 1.1.1

package/dist/index.cjs

@@ -674,7 +674,9 @@ var import_promises4 = require("fs/promises");
 var import_node_path4 = __toESM(require("path"), 1);
 var import_node_os2 = __toESM(require("os"), 1);
 var import_node_https = __toESM(require("https"), 1);
-var TUNNEL_START_TIMEOUT_MS = 15e3;
+var TUNNEL_START_TIMEOUT_MS = 4e4;
+var MAX_TUNNEL_RETRIES = 5;
+var TUNNEL_RETRY_DELAY_MS = 1e3;
 var TUNNEL_URL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 function getBinDir() {
   return import_node_path4.default.join(import_node_os2.default.homedir(), ".whatalo", "bin");
@@ -785,9 +787,7 @@ async function downloadCloudflared(targetPath) {
   info(`cloudflared saved to ${targetPath}`);
   return targetPath;
 }
-async function createTunnel(options) {
-  const { localPort, protocol = "http" } = options;
-  const binaryPath = await ensureCloudflared();
+function spawnTunnelAttempt(binaryPath, localPort, protocol) {
   return new Promise((resolve, reject) => {
     const child = (0, import_node_child_process.spawn)(
       binaryPath,
@@ -825,16 +825,7 @@ async function createTunnel(options) {
         if (match && !urlFound) {
           urlFound = true;
           clearTimeout(timeout);
-          const tunnelUrl = match[0];
-          const kill = () => new Promise((res) => {
-            if (child.exitCode !== null) {
-              res();
-              return;
-            }
-            child.once("exit", () => res());
-            child.kill("SIGTERM");
-          });
-          resolve({ url: tunnelUrl, process: child, kill });
+          resolve([match[0], child]);
         }
       }
     });
@@ -861,6 +852,77 @@ async function createTunnel(options) {
     });
   });
 }
+function attachHealthMonitor(child, isStopped, reconnect, onReconnect) {
+  child.on("close", (code2, signal) => {
+    if (isStopped()) return;
+    warn(
+      `Tunnel process exited unexpectedly (code=${code2 ?? "null"}, signal=${signal ?? "none"}). Reconnecting...`
+    );
+    reconnect().then(([newUrl, newChild]) => {
+      info(`Tunnel reconnected (webhooks): ${newUrl}`);
+      attachHealthMonitor(newChild, isStopped, reconnect, onReconnect);
+      if (onReconnect) {
+        void Promise.resolve(onReconnect(newUrl));
+      }
+    }).catch((err) => {
+      const message = err instanceof Error ? err.message : "unknown error";
+      warn(`Tunnel reconnect failed: ${message}`);
+    });
+  });
+}
+async function createTunnel(options) {
+  const {
+    localPort,
+    protocol = "http",
+    maxRetries = MAX_TUNNEL_RETRIES,
+    onReconnect
+  } = options;
+  const binaryPath = await ensureCloudflared();
+  const spawnNew = () => spawnTunnelAttempt(binaryPath, localPort, protocol);
+  let lastError;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      if (attempt > 1) {
+        info(`Tunnel attempt ${attempt}/${maxRetries}...`);
+      }
+      const [tunnelUrl, child] = await spawnNew();
+      let stopped = false;
+      let currentChild = child;
+      attachHealthMonitor(
+        child,
+        () => stopped,
+        async () => {
+          const result = await spawnNew();
+          currentChild = result[1];
+          return result;
+        },
+        onReconnect
+      );
+      const kill = () => new Promise((res) => {
+        stopped = true;
+        if (currentChild.exitCode !== null) {
+          res();
+          return;
+        }
+        currentChild.once("exit", () => res());
+        currentChild.kill("SIGTERM");
+      });
+      return { url: tunnelUrl, process: child, kill };
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < maxRetries) {
+        warn(
+          `Tunnel startup failed (attempt ${attempt}/${maxRetries}): ${lastError.message}`
+        );
+        await new Promise((r) => setTimeout(r, TUNNEL_RETRY_DELAY_MS));
+      }
+    }
+  }
+  throw new Error(
+    `Tunnel failed after ${maxRetries} attempts. Check your network or use \`--tunnel-url\` to provide a URL manually.
+  Last error: ${lastError?.message ?? "unknown"}`
+  );
+}
 
 // src/version/check.ts
 var import_promises5 = require("fs/promises");

package/dist/index.d.cts

@@ -2,7 +2,7 @@ export { clearSession, getSession, getSessionDir, isSessionValid, pollForToken,
 export { D as DeviceCodeResponse, b as POLL_STATUS, P as PollResult, a as PollStatus, T as TokenResponse, W as WhataloSession } from './types-DunvRQ0f.cjs';
 export { Spinner, TaskStatus, WhataloAuthError, WhataloConfigError, WhataloNetworkError, WhataloValidationError, banner, code, createSpinner, error, failMissingNonTTYFlags, handleCliError, info, link, renderInfoPanel, renderTable, renderTasks, success, table, warn, withErrorHandler } from './output/index.cjs';
 export { HttpClientOptions, WhataloApiClient } from './http/index.cjs';
-export { C as CONFIG_FILE_NAME, E as EnvEntry, W as WhataloAppConfig, p as parseEnvFile, r as readConfig, u as updateEnvFile, w as writeConfig } from './env-file-KvUHlLtI.cjs';
+export { C as CONFIG_FILE_NAME, E as EnvEntry, W as WhataloAppConfig, p as parseEnvFile, r as readConfig, u as updateEnvFile, w as writeConfig } from './env-file-Qh_6c5K2.cjs';
 export { TunnelDownloadProgress, TunnelOptions, TunnelProcess, createTunnel, ensureCloudflared } from './tunnel/index.cjs';
 export { VersionCheckResult, checkSdkCompatibility, getUpgradeCommand, isNewerVersion, scheduleVersionCheck } from './version/index.cjs';
 import 'node:child_process';

package/dist/index.d.ts

@@ -2,7 +2,7 @@ export { clearSession, getSession, getSessionDir, isSessionValid, pollForToken,
 export { D as DeviceCodeResponse, b as POLL_STATUS, P as PollResult, a as PollStatus, T as TokenResponse, W as WhataloSession } from './types-DunvRQ0f.js';
 export { Spinner, TaskStatus, WhataloAuthError, WhataloConfigError, WhataloNetworkError, WhataloValidationError, banner, code, createSpinner, error, failMissingNonTTYFlags, handleCliError, info, link, renderInfoPanel, renderTable, renderTasks, success, table, warn, withErrorHandler } from './output/index.js';
 export { HttpClientOptions, WhataloApiClient } from './http/index.js';
-export { C as CONFIG_FILE_NAME, E as EnvEntry, W as WhataloAppConfig, p as parseEnvFile, r as readConfig, u as updateEnvFile, w as writeConfig } from './env-file-KvUHlLtI.js';
+export { C as CONFIG_FILE_NAME, E as EnvEntry, W as WhataloAppConfig, p as parseEnvFile, r as readConfig, u as updateEnvFile, w as writeConfig } from './env-file-Qh_6c5K2.js';
 export { TunnelDownloadProgress, TunnelOptions, TunnelProcess, createTunnel, ensureCloudflared } from './tunnel/index.js';
 export { VersionCheckResult, checkSdkCompatibility, getUpgradeCommand, isNewerVersion, scheduleVersionCheck } from './version/index.js';
 import 'node:child_process';

package/dist/index.mjs

@@ -598,7 +598,9 @@ import { unlink, rename } from "fs/promises";
 import path3 from "path";
 import os2 from "os";
 import https from "https";
-var TUNNEL_START_TIMEOUT_MS = 15e3;
+var TUNNEL_START_TIMEOUT_MS = 4e4;
+var MAX_TUNNEL_RETRIES = 5;
+var TUNNEL_RETRY_DELAY_MS = 1e3;
 var TUNNEL_URL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 function getBinDir() {
   return path3.join(os2.homedir(), ".whatalo", "bin");
@@ -709,9 +711,7 @@ async function downloadCloudflared(targetPath) {
   info(`cloudflared saved to ${targetPath}`);
   return targetPath;
 }
-async function createTunnel(options) {
-  const { localPort, protocol = "http" } = options;
-  const binaryPath = await ensureCloudflared();
+function spawnTunnelAttempt(binaryPath, localPort, protocol) {
   return new Promise((resolve, reject) => {
     const child = spawn(
       binaryPath,
@@ -749,16 +749,7 @@ async function createTunnel(options) {
         if (match && !urlFound) {
           urlFound = true;
           clearTimeout(timeout);
-          const tunnelUrl = match[0];
-          const kill = () => new Promise((res) => {
-            if (child.exitCode !== null) {
-              res();
-              return;
-            }
-            child.once("exit", () => res());
-            child.kill("SIGTERM");
-          });
-          resolve({ url: tunnelUrl, process: child, kill });
+          resolve([match[0], child]);
         }
       }
     });
@@ -785,6 +776,77 @@ async function createTunnel(options) {
     });
   });
 }
+function attachHealthMonitor(child, isStopped, reconnect, onReconnect) {
+  child.on("close", (code2, signal) => {
+    if (isStopped()) return;
+    warn(
+      `Tunnel process exited unexpectedly (code=${code2 ?? "null"}, signal=${signal ?? "none"}). Reconnecting...`
+    );
+    reconnect().then(([newUrl, newChild]) => {
+      info(`Tunnel reconnected (webhooks): ${newUrl}`);
+      attachHealthMonitor(newChild, isStopped, reconnect, onReconnect);
+      if (onReconnect) {
+        void Promise.resolve(onReconnect(newUrl));
+      }
+    }).catch((err) => {
+      const message = err instanceof Error ? err.message : "unknown error";
+      warn(`Tunnel reconnect failed: ${message}`);
+    });
+  });
+}
+async function createTunnel(options) {
+  const {
+    localPort,
+    protocol = "http",
+    maxRetries = MAX_TUNNEL_RETRIES,
+    onReconnect
+  } = options;
+  const binaryPath = await ensureCloudflared();
+  const spawnNew = () => spawnTunnelAttempt(binaryPath, localPort, protocol);
+  let lastError;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      if (attempt > 1) {
+        info(`Tunnel attempt ${attempt}/${maxRetries}...`);
+      }
+      const [tunnelUrl, child] = await spawnNew();
+      let stopped = false;
+      let currentChild = child;
+      attachHealthMonitor(
+        child,
+        () => stopped,
+        async () => {
+          const result = await spawnNew();
+          currentChild = result[1];
+          return result;
+        },
+        onReconnect
+      );
+      const kill = () => new Promise((res) => {
+        stopped = true;
+        if (currentChild.exitCode !== null) {
+          res();
+          return;
+        }
+        currentChild.once("exit", () => res());
+        currentChild.kill("SIGTERM");
+      });
+      return { url: tunnelUrl, process: child, kill };
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < maxRetries) {
+        warn(
+          `Tunnel startup failed (attempt ${attempt}/${maxRetries}): ${lastError.message}`
+        );
+        await new Promise((r) => setTimeout(r, TUNNEL_RETRY_DELAY_MS));
+      }
+    }
+  }
+  throw new Error(
+    `Tunnel failed after ${maxRetries} attempts. Check your network or use \`--tunnel-url\` to provide a URL manually.
+  Last error: ${lastError?.message ?? "unknown"}`
+  );
+}
 
 // src/version/check.ts
 import { readFile as readFile3, writeFile as writeFile3, mkdir } from "fs/promises";

package/dist/tunnel/index.cjs

@@ -45,6 +45,9 @@ var import_node_https = __toESM(require("https"), 1);
 
 // src/output/format.ts
 var import_chalk = __toESM(require("chalk"), 1);
+function warn(message) {
+  console.log(`  ${import_chalk.default.yellow("\u26A0")} ${message}`);
+}
 function info(message) {
   console.log(`  ${import_chalk.default.blue("\u2139")} ${message}`);
 }
@@ -58,7 +61,9 @@ var STATUS_ICONS = {
 };
 
 // src/tunnel/cloudflared.ts
-var TUNNEL_START_TIMEOUT_MS = 15e3;
+var TUNNEL_START_TIMEOUT_MS = 4e4;
+var MAX_TUNNEL_RETRIES = 5;
+var TUNNEL_RETRY_DELAY_MS = 1e3;
 var TUNNEL_URL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 function getBinDir() {
   return import_node_path.default.join(import_node_os.default.homedir(), ".whatalo", "bin");
@@ -169,9 +174,7 @@ async function downloadCloudflared(targetPath) {
   info(`cloudflared saved to ${targetPath}`);
   return targetPath;
 }
-async function createTunnel(options) {
-  const { localPort, protocol = "http" } = options;
-  const binaryPath = await ensureCloudflared();
+function spawnTunnelAttempt(binaryPath, localPort, protocol) {
   return new Promise((resolve, reject) => {
     const child = (0, import_node_child_process.spawn)(
       binaryPath,
@@ -209,16 +212,7 @@ async function createTunnel(options) {
         if (match && !urlFound) {
           urlFound = true;
           clearTimeout(timeout);
-          const tunnelUrl = match[0];
-          const kill = () => new Promise((res) => {
-            if (child.exitCode !== null) {
-              res();
-              return;
-            }
-            child.once("exit", () => res());
-            child.kill("SIGTERM");
-          });
-          resolve({ url: tunnelUrl, process: child, kill });
+          resolve([match[0], child]);
         }
       }
     });
@@ -245,6 +239,77 @@ async function createTunnel(options) {
     });
   });
 }
+function attachHealthMonitor(child, isStopped, reconnect, onReconnect) {
+  child.on("close", (code, signal) => {
+    if (isStopped()) return;
+    warn(
+      `Tunnel process exited unexpectedly (code=${code ?? "null"}, signal=${signal ?? "none"}). Reconnecting...`
+    );
+    reconnect().then(([newUrl, newChild]) => {
+      info(`Tunnel reconnected (webhooks): ${newUrl}`);
+      attachHealthMonitor(newChild, isStopped, reconnect, onReconnect);
+      if (onReconnect) {
+        void Promise.resolve(onReconnect(newUrl));
+      }
+    }).catch((err) => {
+      const message = err instanceof Error ? err.message : "unknown error";
+      warn(`Tunnel reconnect failed: ${message}`);
+    });
+  });
+}
+async function createTunnel(options) {
+  const {
+    localPort,
+    protocol = "http",
+    maxRetries = MAX_TUNNEL_RETRIES,
+    onReconnect
+  } = options;
+  const binaryPath = await ensureCloudflared();
+  const spawnNew = () => spawnTunnelAttempt(binaryPath, localPort, protocol);
+  let lastError;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      if (attempt > 1) {
+        info(`Tunnel attempt ${attempt}/${maxRetries}...`);
+      }
+      const [tunnelUrl, child] = await spawnNew();
+      let stopped = false;
+      let currentChild = child;
+      attachHealthMonitor(
+        child,
+        () => stopped,
+        async () => {
+          const result = await spawnNew();
+          currentChild = result[1];
+          return result;
+        },
+        onReconnect
+      );
+      const kill = () => new Promise((res) => {
+        stopped = true;
+        if (currentChild.exitCode !== null) {
+          res();
+          return;
+        }
+        currentChild.once("exit", () => res());
+        currentChild.kill("SIGTERM");
+      });
+      return { url: tunnelUrl, process: child, kill };
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < maxRetries) {
+        warn(
+          `Tunnel startup failed (attempt ${attempt}/${maxRetries}): ${lastError.message}`
+        );
+        await new Promise((r) => setTimeout(r, TUNNEL_RETRY_DELAY_MS));
+      }
+    }
+  }
+  throw new Error(
+    `Tunnel failed after ${maxRetries} attempts. Check your network or use \`--tunnel-url\` to provide a URL manually.
+  Last error: ${lastError?.message ?? "unknown"}`
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createTunnel,

package/dist/tunnel/index.d.cts

@@ -6,6 +6,17 @@ interface TunnelOptions {
     localPort: number;
     /** Protocol to use for the tunnel connection (default: "http") */
     protocol?: "http" | "https";
+    /**
+     * Maximum number of times to retry tunnel creation on failure.
+     * Defaults to MAX_TUNNEL_RETRIES (5).
+     */
+    maxRetries?: number;
+    /**
+     * Called whenever the tunnel reconnects after an unexpected process exit.
+     * Receives the new public URL so the caller can update the dev session.
+     * Optional — callers that do not need URL update notifications can omit this.
+     */
+    onReconnect?: (newUrl: string) => void | Promise<void>;
 }
 /**
  * Represents a running tunnel process.
@@ -37,7 +48,7 @@ interface TunnelDownloadProgress {
  * Binary resolution order:
  *  1. System PATH  (user's global install, resolved via `which`/`where`)
  *  2. ~/.whatalo/bin/cloudflared  (previously downloaded by the CLI)
- *  3. Download from GitHub releases → ~/.whatalo/bin/cloudflared
+ *  3. Download from GitHub releases -> ~/.whatalo/bin/cloudflared
  *
  * Note: process-spawning helpers use spawnSync / spawn (not exec/execSync)
  * to avoid shell interpolation entirely — all arguments are passed as an
@@ -56,14 +67,24 @@ interface TunnelDownloadProgress {
  */
 declare function ensureCloudflared(): Promise<string>;
 /**
- * Spawns a cloudflared quick tunnel targeting the given local port.
+ * Creates a cloudflared quick tunnel targeting the given local port.
  *
- * Streams stderr line-by-line to detect the assigned public URL.
- * Resolves once the URL is found or rejects after TUNNEL_START_TIMEOUT_MS.
+ * Enhancements over a bare spawn:
+ *
+ *  - 40-second startup timeout (previously 15 s) to handle slow initialization
+ *  - Up to MAX_TUNNEL_RETRIES (5) automatic retry attempts with a 1-second
+ *    delay between each before giving up
+ *  - Health monitoring via attachHealthMonitor: detects unexpected process exit
+ *    and auto-reconnects; calls options.onReconnect with the new URL so the
+ *    caller can patch server-side state (e.g., dev session tunnel URL)
+ *
+ * The tunnel is primarily used for webhook and API callbacks. Plugin iframes
+ * are served directly from the developer's local server via the CDN dev bundle,
+ * so tunnel availability affects event delivery, not page rendering.
  *
  * @param options - localPort is required; protocol defaults to "http"
- * @returns A TunnelProcess containing the public URL and a kill() helper
- * @throws If the process exits before printing a URL, or if startup times out
+ * @returns A TunnelProcess with the current public URL and a kill() helper
+ * @throws After exhausting all retries with a descriptive aggregated error
  */
 declare function createTunnel(options: TunnelOptions): Promise<TunnelProcess>;
 

package/dist/tunnel/index.d.ts

@@ -6,6 +6,17 @@ interface TunnelOptions {
     localPort: number;
     /** Protocol to use for the tunnel connection (default: "http") */
     protocol?: "http" | "https";
+    /**
+     * Maximum number of times to retry tunnel creation on failure.
+     * Defaults to MAX_TUNNEL_RETRIES (5).
+     */
+    maxRetries?: number;
+    /**
+     * Called whenever the tunnel reconnects after an unexpected process exit.
+     * Receives the new public URL so the caller can update the dev session.
+     * Optional — callers that do not need URL update notifications can omit this.
+     */
+    onReconnect?: (newUrl: string) => void | Promise<void>;
 }
 /**
  * Represents a running tunnel process.
@@ -37,7 +48,7 @@ interface TunnelDownloadProgress {
  * Binary resolution order:
  *  1. System PATH  (user's global install, resolved via `which`/`where`)
  *  2. ~/.whatalo/bin/cloudflared  (previously downloaded by the CLI)
- *  3. Download from GitHub releases → ~/.whatalo/bin/cloudflared
+ *  3. Download from GitHub releases -> ~/.whatalo/bin/cloudflared
  *
  * Note: process-spawning helpers use spawnSync / spawn (not exec/execSync)
  * to avoid shell interpolation entirely — all arguments are passed as an
@@ -56,14 +67,24 @@ interface TunnelDownloadProgress {
  */
 declare function ensureCloudflared(): Promise<string>;
 /**
- * Spawns a cloudflared quick tunnel targeting the given local port.
+ * Creates a cloudflared quick tunnel targeting the given local port.
  *
- * Streams stderr line-by-line to detect the assigned public URL.
- * Resolves once the URL is found or rejects after TUNNEL_START_TIMEOUT_MS.
+ * Enhancements over a bare spawn:
+ *
+ *  - 40-second startup timeout (previously 15 s) to handle slow initialization
+ *  - Up to MAX_TUNNEL_RETRIES (5) automatic retry attempts with a 1-second
+ *    delay between each before giving up
+ *  - Health monitoring via attachHealthMonitor: detects unexpected process exit
+ *    and auto-reconnects; calls options.onReconnect with the new URL so the
+ *    caller can patch server-side state (e.g., dev session tunnel URL)
+ *
+ * The tunnel is primarily used for webhook and API callbacks. Plugin iframes
+ * are served directly from the developer's local server via the CDN dev bundle,
+ * so tunnel availability affects event delivery, not page rendering.
  *
  * @param options - localPort is required; protocol defaults to "http"
- * @returns A TunnelProcess containing the public URL and a kill() helper
- * @throws If the process exits before printing a URL, or if startup times out
+ * @returns A TunnelProcess with the current public URL and a kill() helper
+ * @throws After exhausting all retries with a descriptive aggregated error
  */
 declare function createTunnel(options: TunnelOptions): Promise<TunnelProcess>;
 

package/dist/tunnel/index.mjs

@@ -8,6 +8,9 @@ import https from "https";
 
 // src/output/format.ts
 import chalk from "chalk";
+function warn(message) {
+  console.log(`  ${chalk.yellow("\u26A0")} ${message}`);
+}
 function info(message) {
   console.log(`  ${chalk.blue("\u2139")} ${message}`);
 }
@@ -21,7 +24,9 @@ var STATUS_ICONS = {
 };
 
 // src/tunnel/cloudflared.ts
-var TUNNEL_START_TIMEOUT_MS = 15e3;
+var TUNNEL_START_TIMEOUT_MS = 4e4;
+var MAX_TUNNEL_RETRIES = 5;
+var TUNNEL_RETRY_DELAY_MS = 1e3;
 var TUNNEL_URL_REGEX = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;
 function getBinDir() {
   return path.join(os.homedir(), ".whatalo", "bin");
@@ -132,9 +137,7 @@ async function downloadCloudflared(targetPath) {
   info(`cloudflared saved to ${targetPath}`);
   return targetPath;
 }
-async function createTunnel(options) {
-  const { localPort, protocol = "http" } = options;
-  const binaryPath = await ensureCloudflared();
+function spawnTunnelAttempt(binaryPath, localPort, protocol) {
   return new Promise((resolve, reject) => {
     const child = spawn(
       binaryPath,
@@ -172,16 +175,7 @@ async function createTunnel(options) {
         if (match && !urlFound) {
           urlFound = true;
           clearTimeout(timeout);
-          const tunnelUrl = match[0];
-          const kill = () => new Promise((res) => {
-            if (child.exitCode !== null) {
-              res();
-              return;
-            }
-            child.once("exit", () => res());
-            child.kill("SIGTERM");
-          });
-          resolve({ url: tunnelUrl, process: child, kill });
+          resolve([match[0], child]);
         }
       }
     });
@@ -208,6 +202,77 @@ async function createTunnel(options) {
     });
   });
 }
+function attachHealthMonitor(child, isStopped, reconnect, onReconnect) {
+  child.on("close", (code, signal) => {
+    if (isStopped()) return;
+    warn(
+      `Tunnel process exited unexpectedly (code=${code ?? "null"}, signal=${signal ?? "none"}). Reconnecting...`
+    );
+    reconnect().then(([newUrl, newChild]) => {
+      info(`Tunnel reconnected (webhooks): ${newUrl}`);
+      attachHealthMonitor(newChild, isStopped, reconnect, onReconnect);
+      if (onReconnect) {
+        void Promise.resolve(onReconnect(newUrl));
+      }
+    }).catch((err) => {
+      const message = err instanceof Error ? err.message : "unknown error";
+      warn(`Tunnel reconnect failed: ${message}`);
+    });
+  });
+}
+async function createTunnel(options) {
+  const {
+    localPort,
+    protocol = "http",
+    maxRetries = MAX_TUNNEL_RETRIES,
+    onReconnect
+  } = options;
+  const binaryPath = await ensureCloudflared();
+  const spawnNew = () => spawnTunnelAttempt(binaryPath, localPort, protocol);
+  let lastError;
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      if (attempt > 1) {
+        info(`Tunnel attempt ${attempt}/${maxRetries}...`);
+      }
+      const [tunnelUrl, child] = await spawnNew();
+      let stopped = false;
+      let currentChild = child;
+      attachHealthMonitor(
+        child,
+        () => stopped,
+        async () => {
+          const result = await spawnNew();
+          currentChild = result[1];
+          return result;
+        },
+        onReconnect
+      );
+      const kill = () => new Promise((res) => {
+        stopped = true;
+        if (currentChild.exitCode !== null) {
+          res();
+          return;
+        }
+        currentChild.once("exit", () => res());
+        currentChild.kill("SIGTERM");
+      });
+      return { url: tunnelUrl, process: child, kill };
+    } catch (err) {
+      lastError = err instanceof Error ? err : new Error(String(err));
+      if (attempt < maxRetries) {
+        warn(
+          `Tunnel startup failed (attempt ${attempt}/${maxRetries}): ${lastError.message}`
+        );
+        await new Promise((r) => setTimeout(r, TUNNEL_RETRY_DELAY_MS));
+      }
+    }
+  }
+  throw new Error(
+    `Tunnel failed after ${maxRetries} attempts. Check your network or use \`--tunnel-url\` to provide a URL manually.
+  Last error: ${lastError?.message ?? "unknown"}`
+  );
+}
 export {
   createTunnel,
   ensureCloudflared

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whatalo/cli-kit",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "type": "module",
   "license": "MIT",
   "description": "Shared CLI utilities for Whatalo plugin development tools",
@@ -64,6 +64,11 @@
       "types": "./dist/version/index.d.ts",
       "import": "./dist/version/index.mjs",
       "require": "./dist/version/index.cjs"
+    },
+    "./bundle": {
+      "types": "./dist/bundle/index.d.ts",
+      "import": "./dist/bundle/index.mjs",
+      "require": "./dist/bundle/index.cjs"
     }
   },
   "files": [