@stackable-labs/cli-app-extension 1.10.2 → 1.11.0

package/README.md

@@ -25,8 +25,8 @@ When run without all required flags, the CLI guides you through a step-by-step p
 | 1 | **App** | Select the App you are building an Extension for (fetched live from the API) |
 | 2 | **Name** | Display name for your Extension (e.g. `My Commerce Extension`) |
 | 3 | **Targets** | Multiselect from the Surface targets/slots exposed by the selected app |
-| 4 | **Extension Port** | Dev server port for the Extension (default: `5173`) |
-| 5 | **Preview Port** | Dev server port for the Preview host (default: `5174`) |
+| 4 | **Extension Port** | Dev server port for the Extension (default: `6543`) |
+| 5 | **Preview Port** | Dev server port for the Preview host (default: `6544`) |
 | 6 | **Directory** | Output directory path (default: kebab-case of name) |
 | 7 | **Confirm** | Review all selections before scaffolding |
 
@@ -76,6 +76,43 @@ my-extension/
 └── package.json
 ```
 
+## `dev` Command
+
+Start local dev servers with a public Cloudflare tunnel for testing:
+
+```bash
+pnpm preview
+```
+
+```
+Usage: stackable-app-extension dev [options]
+
+Options:
+  --dir <path>               Project root (default: cwd)
+  --extension-port <port>    Override Extension port
+  --preview-port <port>      Override Preview port
+  --no-tunnel                Skip tunnel, just run vite dev
+  -h, --help                 Display help
+```
+
+The `dev` command:
+1. Reads `.env.stackable` for cached App/Extension context (prompts if missing)
+2. Starts Cloudflare tunnels for both extension and preview servers
+3. Starts Vite dev servers with hot-reload
+4. Displays a **Host App Query Param** you can append to your host app URL to test against the real deployed host
+
+### Host App Override
+
+The dashboard displays a query param like:
+
+```
+?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com
+```
+
+Append this to your deployed host app URL to override the extension's `bundleUrl` in your browser session only. The `@stackable-labs/embeddables` SDK detects this param and loads from your tunnel instead of the production bundle. No DB changes, no shared state — each developer gets isolated overrides.
+
+> **Note:** The `dev` command never updates the `bundleUrl` in the database. It is purely local.
+
 ## Development Workflow
 
 ```bash

package/dist/index.js

@@ -287,7 +287,7 @@ import { Box as Box6, Text as Text6, useFocus as useFocus2, useFocusManager as u
 import TextInput3 from "ink-text-input";
 import { useState as useState3 } from "react";
 import { jsx as jsx6, jsxs as jsxs6 } from "react/jsx-runtime";
-var DEFAULT_EXTENSION_PORT = 5173;
+var DEFAULT_EXTENSION_PORT = 6543;
 var DEFAULT_PREVIEW_PORT = DEFAULT_EXTENSION_PORT + 1;
 var FieldRow = ({ label, value, onChange, onSubmit, onConfirm, placeholder, autoFocus, isFirst, isLast }) => {
   const { isFocused } = useFocus2({ autoFocus });
@@ -622,7 +622,7 @@ var UpdateSettingsPrompt = ({
             label: "Bundle URL",
             value: bundleUrlValue,
             onChange: setBundleUrlValue,
-            placeholder: "http://localhost:5173",
+            placeholder: "http://localhost:6543",
             onSubmitAll: handleSubmitAll
           }
         ),
@@ -1066,15 +1066,14 @@ var readDevContext = async (projectRoot) => {
   } catch {
   }
   const devLocalEnv = await readEnvFile(join(projectRoot, ".env.development.local"));
-  const extensionPort = parseInt(devLocalEnv.VITE_EXTENSION_PORT || env.VITE_EXTENSION_PORT || "5173", 10);
-  const previewPort = parseInt(devLocalEnv.VITE_PREVIEW_PORT || env.VITE_PREVIEW_PORT || "5174", 10);
+  const extensionPort = parseInt(devLocalEnv.VITE_EXTENSION_PORT || env.VITE_EXTENSION_PORT || "6543", 10);
+  const previewPort = parseInt(devLocalEnv.VITE_PREVIEW_PORT || env.VITE_PREVIEW_PORT || "6544", 10);
   return {
     projectRoot,
     extensionName,
     appId: stackableEnv.APP_ID || null,
     extensionId: stackableEnv.EXTENSION_ID || null,
     appName: stackableEnv.APP_NAME || null,
-    originalBundleUrl: stackableEnv.ORIGINAL_BUNDLE_URL || null,
     extensionPort,
     previewPort
   };
@@ -1103,9 +1102,6 @@ var writeDevContext = async (projectRoot, ctx) => {
   if (ctx.extensionName && ctx.extensionName !== "Unknown Extension") {
     env.EXTENSION_NAME = ctx.extensionName;
   }
-  if (ctx.originalBundleUrl) {
-    env.ORIGINAL_BUNDLE_URL = ctx.originalBundleUrl;
-  }
   await writeEnvFile(join(projectRoot, ".env.stackable"), env);
 };
 
@@ -1334,7 +1330,7 @@ const extensions: ExtensionRegistryEntry[] = [
   {
     id: manifest.name.toLowerCase().replace(/\\s+/g, '-'),
     manifest,
-    bundleUrl: import.meta.env.VITE_EXTENSION_BUNDLE_URL || \`http://localhost:\${import.meta.env.VITE_EXTENSION_PORT || '5173'}\`,
+    bundleUrl: import.meta.env.VITE_EXTENSION_BUNDLE_URL || \`http://localhost:\${import.meta.env.VITE_EXTENSION_PORT || '6543'}\`,
     enabled: true,
   },
 ]
@@ -1517,10 +1513,10 @@ var App = ({ command, initialName, initialExtensionId, options }) => {
   );
   const [selectedApp, setSelectedApp] = useState8(null);
   const [extensionPort, setExtensionPort] = useState8(
-    options?.extensionPort ? parseInt(options.extensionPort, 10) : 5173
+    options?.extensionPort ? parseInt(options.extensionPort, 10) : 6543
   );
   const [previewPort, setPreviewPort] = useState8(
-    options?.previewPort ? parseInt(options.previewPort, 10) : 5174
+    options?.previewPort ? parseInt(options.previewPort, 10) : 6544
   );
   const [outputDir, setOutputDir] = useState8("");
   const [progressSteps, setProgressSteps] = useState8(PROGRESS_STEPS[command]);
@@ -1929,7 +1925,6 @@ var DevDashboard = ({
   previewTunnelUrl,
   previewPort,
   extensionPort,
-  bundleUrlUpdated,
   onQuit
 }) => {
   useEffect5(() => {
@@ -1952,13 +1947,10 @@ var DevDashboard = ({
       StepShell,
       {
         title: "dev",
-        hint: "Live development with Tunnel",
-        footer: /* @__PURE__ */ jsxs15(Box15, { flexDirection: "column", gap: 1, children: [
-          bundleUrlUpdated && /* @__PURE__ */ jsx15(Text15, { color: "green", children: "bundleUrl updated \u2713" }),
-          /* @__PURE__ */ jsx15(Text15, { dimColor: true, children: "Press q or Ctrl-C to quit" })
-        ] }),
+        hint: `Live development ${tunnelUrl ? "with" : "w/o"} Tunnel`,
+        footer: /* @__PURE__ */ jsx15(Box15, { flexDirection: "column", gap: 1, children: /* @__PURE__ */ jsx15(Text15, { dimColor: true, children: "Press q or Ctrl-C to quit" }) }),
         children: [
-          /* @__PURE__ */ jsxs15(Box15, { flexDirection: "column", gap: 1, children: [
+          /* @__PURE__ */ jsxs15(Box15, { flexDirection: "column", children: [
             /* @__PURE__ */ jsxs15(Box15, { gap: 2, children: [
               /* @__PURE__ */ jsx15(Text15, { dimColor: true, children: "Extension:" }),
               /* @__PURE__ */ jsxs15(Text15, { children: [
@@ -1971,9 +1963,13 @@ var DevDashboard = ({
             /* @__PURE__ */ jsxs15(Box15, { gap: 2, children: [
               /* @__PURE__ */ jsx15(Text15, { dimColor: true, children: "App:" }),
               /* @__PURE__ */ jsx15(Text15, { children: `${appName ? `${appName} ` : ""}(${appId})` })
+            ] }),
+            /* @__PURE__ */ jsxs15(Box15, { gap: 2, children: [
+              /* @__PURE__ */ jsx15(Text15, { dimColor: true, children: "Bundle URL:" }),
+              /* @__PURE__ */ jsx15(Text15, { children: tunnelUrl || `http://localhost:${extensionPort}` })
             ] })
           ] }),
-          /* @__PURE__ */ jsxs15(Box15, { flexDirection: "column", gap: 1, children: [
+          /* @__PURE__ */ jsxs15(Box15, { flexDirection: "column", children: [
             previewTunnelUrl && /* @__PURE__ */ jsxs15(Box15, { gap: 2, children: [
               /* @__PURE__ */ jsx15(Text15, { dimColor: true, children: "Tunnel Dev - Preview:" }),
               /* @__PURE__ */ jsx15(Text15, { children: previewTunnelUrl })
@@ -1984,7 +1980,9 @@ var DevDashboard = ({
                 "http://localhost:",
                 previewPort
               ] })
-            ] }),
+            ] })
+          ] }),
+          /* @__PURE__ */ jsxs15(Box15, { flexDirection: "column", children: [
             tunnelUrl && /* @__PURE__ */ jsxs15(Box15, { gap: 2, children: [
               /* @__PURE__ */ jsx15(Text15, { dimColor: true, children: "Tunnel Dev - Extension:" }),
               /* @__PURE__ */ jsx15(Text15, { children: tunnelUrl })
@@ -1995,15 +1993,15 @@ var DevDashboard = ({
                 "http://localhost:",
                 extensionPort
               ] })
-            ] }),
-            /* @__PURE__ */ jsxs15(Box15, { gap: 2, children: [
-              /* @__PURE__ */ jsx15(Text15, { dimColor: true, children: "Bundle URL:" }),
-              /* @__PURE__ */ jsxs15(Text15, { children: [
-                tunnelUrl || `http://localhost:${extensionPort}`,
-                bundleUrlUpdated ? " (updated \u2713)" : ""
-              ] })
             ] })
-          ] })
+          ] }),
+          /* @__PURE__ */ jsx15(Box15, { flexDirection: "column", children: tunnelUrl && /* @__PURE__ */ jsxs15(Box15, { gap: 2, children: [
+            /* @__PURE__ */ jsx15(Text15, { dimColor: true, children: "Host Dev - Query Param:" }),
+            /* @__PURE__ */ jsxs15(Text15, { children: [
+              "?_stackable_dev=",
+              encodeURIComponent(`${extensionId}:${tunnelUrl}`)
+            ] })
+          ] }) })
         ]
       }
     )
@@ -2012,28 +2010,17 @@ var DevDashboard = ({
 
 // src/components/DevApp.tsx
 import { jsx as jsx16 } from "react/jsx-runtime";
-var isEphemeralUrl = (url) => {
-  try {
-    const { hostname } = new URL(url);
-    return hostname.endsWith(".ngrok.io") || hostname.endsWith(".ngrok-free.app") || hostname.endsWith(".trycloudflare.com");
-  } catch {
-    return true;
-  }
-};
 var DevApp = ({ options = {} }) => {
   const [state, setState] = useState10("setup");
   const [devContext, setDevContext] = useState10(null);
   const [resolvedContext, setResolvedContext] = useState10(null);
   const [tunnelUrl, setTunnelUrl] = useState10(null);
   const [previewTunnelUrl, setPreviewTunnelUrl] = useState10(null);
-  const [bundleUrlUpdated, setBundleUrlUpdated] = useState10(false);
   const [tunnelHandle, setTunnelHandle] = useState10(null);
   const [previewTunnelHandle, setPreviewTunnelHandle] = useState10(null);
   const [devServerHandle, setDevServerHandle] = useState10(null);
   const shuttingDown = useRef(false);
   const useTunnel = options.tunnel !== false;
-  const useUpdate = options.update !== false;
-  const useRestore = options.restore !== false;
   useEffect6(() => {
     const projectRoot = options.dir || process.cwd();
     console.log(`[dev] Reading context from ${projectRoot}`);
@@ -2055,32 +2042,6 @@ var DevApp = ({ options = {} }) => {
     const extensionPort = options.extensionPort ? parseInt(options.extensionPort, 10) : devContext.extensionPort;
     const previewPort = options.previewPort ? parseInt(options.previewPort, 10) : devContext.previewPort;
     await patchViteAllowedHosts(devContext.projectRoot);
-    let cachedOriginalUrl = devContext.originalBundleUrl;
-    if (useUpdate) {
-      try {
-        console.log("[dev] Fetching current bundleUrl from API...");
-        const extensions = await fetchExtensions(resolved.appId);
-        const currentExtension = extensions[resolved.extensionId];
-        if (currentExtension?.bundleUrl) {
-          console.log(`[dev] Current bundleUrl: ${currentExtension.bundleUrl}`);
-          if (!isEphemeralUrl(currentExtension.bundleUrl)) {
-            console.log("[dev] Caching stable bundleUrl to .env.stackable");
-            cachedOriginalUrl = currentExtension.bundleUrl;
-            await writeDevContext(devContext.projectRoot, {
-              ...devContext,
-              appId: resolved.appId,
-              extensionId: resolved.extensionId,
-              appName: resolved.appName || null,
-              originalBundleUrl: cachedOriginalUrl
-            });
-          } else {
-            console.log("[dev] Current bundleUrl is ephemeral, keeping previous cached value");
-          }
-        }
-      } catch (err) {
-        console.warn("[dev] Failed to fetch current bundleUrl:", err);
-      }
-    }
     if (useTunnel) {
       try {
         console.log(`[dev] Starting extension tunnel on port ${extensionPort}...`);
@@ -2095,14 +2056,6 @@ var DevApp = ({ options = {} }) => {
         setPreviewTunnelUrl(previewTunnelResult.url);
         console.log(`[dev] Writing VITE_EXTENSION_BUNDLE_URL=${tunnelResult.url} to .env`);
         await patchProjectEnv(devContext.projectRoot, "VITE_EXTENSION_BUNDLE_URL", tunnelResult.url);
-        if (useUpdate) {
-          console.log(`[dev] Updating bundleUrl to ${tunnelResult.url}`);
-          await updateExtension(resolved.appId, resolved.extensionId, {
-            bundleUrl: tunnelResult.url
-          });
-          console.log("[dev] bundleUrl updated successfully");
-          setBundleUrlUpdated(true);
-        }
       } catch (err) {
         console.error("[dev] Failed to start tunnel:", err);
       }
@@ -2114,7 +2067,7 @@ var DevApp = ({ options = {} }) => {
     setDevServerHandle(serverHandle);
     console.log("[dev] Ready");
     setState("running");
-  }, [devContext, options.extensionPort, options.previewPort, useTunnel, useUpdate]);
+  }, [devContext, options.extensionPort, options.previewPort, useTunnel]);
   useEffect6(() => {
     if (state === "setup" && devContext && devContext.appId && devContext.extensionId) {
       handleSetupReady({
@@ -2130,15 +2083,6 @@ var DevApp = ({ options = {} }) => {
     setState("stopping");
     console.log("[dev] Shutting down...");
     try {
-      if (useRestore && devContext.originalBundleUrl) {
-        console.log(`[dev] Restoring bundleUrl to ${devContext.originalBundleUrl}`);
-        await updateExtension(resolvedContext.appId, resolvedContext.extensionId, {
-          bundleUrl: devContext.originalBundleUrl
-        });
-        console.log("[dev] bundleUrl restored");
-      } else if (useRestore && !devContext.originalBundleUrl) {
-        console.warn("[dev] No cached original bundleUrl to restore");
-      }
       console.log("[dev] Removing VITE_EXTENSION_BUNDLE_URL from .env");
       await removeProjectEnvKey(devContext.projectRoot, "VITE_EXTENSION_BUNDLE_URL");
       if (tunnelHandle) {
@@ -2183,7 +2127,6 @@ var DevApp = ({ options = {} }) => {
         previewPort: options.previewPort ? parseInt(options.previewPort, 10) : devContext.previewPort,
         tunnelUrl,
         previewTunnelUrl,
-        bundleUrlUpdated,
         onQuit: handleQuit
       }
     );
@@ -2218,8 +2161,11 @@ var checkForUpdate = (currentVersion) => {
       res.on("end", () => {
         try {
           const { version: latest } = JSON.parse(data);
-          if (latest && latest !== currentVersion && isNewer(latest, currentVersion)) {
-            const warning = "\n\x1B[33m\u26A0  Update available: " + currentVersion + " \u2192 " + latest + "\x1B[0m\n   Run \x1B[36mnpx @stackable-labs/cli-app-extension@latest\x1B[0m to update\n";
+          if (latest && latest !== currentVersion && currentVersion !== "0.0.0" && isNewer(latest, currentVersion)) {
+            const warning = `
+\x1B[33m\u26A0  Update available: ${currentVersion} \u2192 ${latest}\x1B[0m
+   Run \x1B[36mnpx @stackable-labs/cli-app-extension@latest\x1B[0m to update
+`;
             console.error(warning);
           }
         } catch {
@@ -2244,16 +2190,16 @@ var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
 checkForUpdate(version);
 program.name("stackable-app-extension").description("Stackable Labs - App Extension developer CLI").version(version);
-program.command("create" /* CREATE */).description("Create a new Extension project").argument("[name]", "Extension project name").option("--extension-port <port>", "Extension dev server port (default: 5173)").option("--preview-port <port>", "Preview dev server port").option("--skip-install", "Skip package manager install").option("--skip-git", "Skip git initialization").action((name, options) => {
+program.command("create" /* CREATE */).description("Create a new Extension project").argument("[name]", "Extension project name").option("--extension-port <port>", "Extension dev server port (default: 6543)").option("--preview-port <port>", "Preview dev server port").option("--skip-install", "Skip package manager install").option("--skip-git", "Skip git initialization").action((name, options) => {
   render(/* @__PURE__ */ jsx17(App, { command: "create" /* CREATE */, initialName: name, options }));
 });
-program.command("scaffold" /* SCAFFOLD */).description("Scaffold a local project from an existing Extension").option("--extension-port <port>", "Extension dev server port (default: 5173)").option("--preview-port <port>", "Preview dev server port").option("--skip-install", "Skip package manager install").option("--skip-git", "Skip git initialization").action((options) => {
+program.command("scaffold" /* SCAFFOLD */).description("Scaffold a local project from an existing Extension").option("--extension-port <port>", "Extension dev server port (default: 6543)").option("--preview-port <port>", "Preview dev server port").option("--skip-install", "Skip package manager install").option("--skip-git", "Skip git initialization").action((options) => {
   render(/* @__PURE__ */ jsx17(App, { command: "scaffold" /* SCAFFOLD */, options }));
 });
 program.command("update" /* UPDATE */).description("Update an existing Extension").argument("[extensionId]", "Extension ID to update").option("--app-id <id>", "Skip App selection").option("--name <name>", "New Extension name").option("--targets <targets>", "Comma-separated target slots (validated against app)").option("--bundle-url <url>", "New bundle URL").option("--enabled <bool>", "Enable/disable Extension").option("--set-version <version>", "Explicit version (skips auto-compute)").action((extensionId, options) => {
   render(/* @__PURE__ */ jsx17(App, { command: "update" /* UPDATE */, initialExtensionId: extensionId, options }));
 });
-program.command("dev" /* DEV */).description("Start dev servers with a public tunnel").option("--dir <path>", "Project root (default: cwd)").option("--extension-port <port>", "Override Extension port").option("--preview-port <port>", "Override Preview port").option("--no-tunnel", "Skip tunnel, just run vite dev").option("--no-update", "Skip bundleUrl update on server").option("--no-restore", "On exit, keep tunnel URL as bundleUrl").action((options) => {
+program.command("dev" /* DEV */).description("Start dev servers with a public tunnel").option("--dir <path>", "Project root (default: cwd)").option("--extension-port <port>", "Override Extension port").option("--preview-port <port>", "Override Preview port").option("--no-tunnel", "Skip tunnel, just run vite dev").action((options) => {
   render(/* @__PURE__ */ jsx17(DevApp, { options }), { exitOnCtrlC: false });
 });
 program.parse(process.argv.filter((arg) => arg !== "--"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackable-labs/cli-app-extension",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "type": "module",
   "private": false,
   "bin": {