@stackable-labs/cli-app-extension 2.21.1 → 2.23.0

package/README.md

@@ -167,28 +167,56 @@ The `dev` command:
 
 ### Host App Override
 
-The dashboard displays a query param like:
+The dashboard displays one or two copyable query params you can append to your host app URL to override the extension's `bundleUrl` for that browser session only. The `@stackable-labs/embeddables` SDK detects the param and loads from your tunnel instead of the production bundle. No DB changes, no shared state — each developer gets isolated overrides.
+
+The CLI emits one of two formats depending on whether the dev session token request succeeded:
+
+**Blob format (default — when authenticated):** the second half of `<extensionId>:<value>` is a `base64url`-encoded JSON `{url, token}` blob. The token is short-lived, signed, and verified by the host. Required for `_stackable_staging` mode.
 
 ```
-?_stackable_dev=ext-123%3Ahttps%3A%2F%2Fabc.trycloudflare.com
+?_stackable_dev=ext-123:eyJ1cmwiOiJodHRwczovL2FiYy50cnljbG91ZGZsYXJlLmNvbSIsInRva2VuIjoiZXlKaGJHY2lPaUpJVXp...
 ```
 
-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.
+The dashboard also surfaces the staging variant when applicable:
+
+```
+?_stackable_staging=ext-123:eyJ1cmwiOiJodHRwczovL2FiYy50cnljbG91ZGZsYXJlLmNvbSIsInRva2VuIjoiZXlKaGJHY2lPaUpJVXp...
+```
+
+The `_stackable_staging` variant signals the host to apply staging-environment-specific handling and **always requires the token** — there is no legacy fallback. If you don't see a Staging Param in the dashboard, the dev session token request failed; check `auth status` and re-run.
+
+**Legacy format (fallback — when no token):** if `requestDevSessionToken` fails (auth misconfigured, network error, etc.), the dashboard falls back to a token-less `<extensionId>:<tunnelUrl>` form for `_stackable_dev` only. The host's parser accepts this format too but cannot apply staging-mode overrides without the token.
+
+```
+?_stackable_dev=ext-123:https://abc.trycloudflare.com
+```
 
 #### Multiple Extensions
 
-To override multiple extensions at once, use either syntax:
+To override multiple extensions at once, use either syntax. Both blob entries and legacy entries can be mixed in the same comma-joined string — the parser tries each entry independently.
+
+**Comma-separated (single param) — preferred:**
+```
+?_stackable_dev=ext-123:eyJ1cmwi...,ext-456:eyJ1cmwi...
+```
 
-**Comma-separated (single param):**
+Mixed blob + legacy in one string also works (e.g. when one extension authenticated and another didn't):
 ```
-?_stackable_dev=ext-123:https://abc.trycloudflare.com,ext-456:https://def.trycloudflare.com
+?_stackable_dev=ext-123:eyJ1cmwi...,ext-456:https://def.trycloudflare.com
 ```
 
 **Repeated params:**
 ```
-?_stackable_dev=ext-123:https://abc.trycloudflare.com&_stackable_dev=ext-456:https://def.trycloudflare.com
+?_stackable_dev=ext-123:eyJ1cmwi...&_stackable_dev=ext-456:eyJ1cmwi...
 ```
 
+The combined staging variant works the same way (blob-only, since staging requires the token):
+```
+?_stackable_staging=ext-123:eyJ1cmwi...,ext-456:eyJ1cmwi...
+```
+
+The `stackable-extensions` repo's `pnpm preview:all` orchestrator (which spawns one `cli-app-extension dev --headless` per extension under `--only` / `--except` filters) emits both combined lines automatically in its summary footer — `?_stackable_dev=...` always, `?_stackable_staging=...` only when at least one session got a token.
+
 > **Note:** The `dev` command never updates the `bundleUrl` in the database. It is purely local.
 
 ## Development Workflow

package/dist/index.js

@@ -3,7 +3,7 @@ import { createRequire } from 'module';
 import { program, InvalidArgumentError } from 'commander';
 import { render, useApp, Box, Text, useInput, useFocus, useFocusManager } from 'ink';
 import { SURFACE_TARGET, TEMPLATE_FLAVORS } from '@stackable-labs/sdk-extension-contracts';
-import { unlink, readFile, writeFile, mkdir, rm, readdir, rmdir } from 'fs/promises';
+import { unlink, readFile, mkdir, writeFile, rm, readdir, rmdir } from 'fs/promises';
 import { join, dirname, relative } from 'path';
 import Spinner5 from 'ink-spinner';
 import { useState, useCallback, useEffect, useRef, useMemo } from 'react';
@@ -2947,6 +2947,157 @@ var startTunnel = async (port) => {
   }
   throw new Error(`Tunnel failed to return a valid URL after ${MAX_RETRIES} attempts`);
 };
+
+// src/lib/devParams.ts
+var toBase64Url = (input) => btoa(input).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+var buildDevParams = ({ extensionId, tunnelUrl, devSessionToken }) => {
+  if (!tunnelUrl) {
+    return {
+      devEntry: null,
+      devParam: null,
+      stagingEntry: null,
+      stagingParam: null,
+      paramBlob: null
+    };
+  }
+  if (devSessionToken) {
+    const paramBlob = toBase64Url(JSON.stringify({ url: tunnelUrl, token: devSessionToken }));
+    const extensionEntry = `${extensionId}:${paramBlob}`;
+    return {
+      paramBlob,
+      devEntry: extensionEntry,
+      stagingEntry: extensionEntry,
+      devParam: `?_stackable_dev=${extensionEntry}`,
+      stagingParam: `?_stackable_staging=${extensionEntry}`
+    };
+  }
+  const devEntry = `${extensionId}:${tunnelUrl}`;
+  return {
+    paramBlob: null,
+    devEntry,
+    stagingEntry: null,
+    stagingParam: null,
+    devParam: `?_stackable_dev=${devEntry}`
+  };
+};
+
+// src/lib/runDev.ts
+var runDev = async ({ token, devContext, options, resolved }) => {
+  console.log(`[dev] Saving context: appId=${resolved.appId} extensionId=${resolved.extensionId}`);
+  await writeDevContext(devContext.projectRoot, {
+    ...devContext,
+    appId: resolved.appId,
+    extensionId: resolved.extensionId,
+    appName: resolved.appName || null
+  });
+  const manifestWarnings = [];
+  if (devContext.manifest) {
+    try {
+      const extensions = await fetchExtensions(token, resolved.appId);
+      const registryExt = extensions[resolved.extensionId];
+      if (registryExt) {
+        const localPerms = new Set(devContext.manifest.permissions);
+        const registryPerms = new Set(registryExt.manifest.permissions);
+        const missingPerms = [...localPerms].filter((p) => !registryPerms.has(p));
+        const extraPerms = [...registryPerms].filter((p) => !localPerms.has(p));
+        const localDomains = new Set(devContext.manifest.allowedDomains);
+        const registryDomains = new Set(registryExt.manifest.allowedDomains);
+        const missingDomains = [...localDomains].filter((d) => !registryDomains.has(d));
+        const extraDomains = [...registryDomains].filter((d) => !localDomains.has(d));
+        if (missingPerms.length > 0) {
+          manifestWarnings.push(`Permissions in local but not registry: ${missingPerms.join(", ")}`);
+        }
+        if (extraPerms.length > 0) {
+          manifestWarnings.push(`Permissions in registry but not local: ${extraPerms.join(", ")}`);
+        }
+        if (missingDomains.length > 0) {
+          manifestWarnings.push(`Domains in local but not registry: ${missingDomains.join(", ")}`);
+        }
+        if (extraDomains.length > 0) {
+          manifestWarnings.push(`Domains in registry but not local: ${extraDomains.join(", ")}`);
+        }
+      }
+    } catch {
+    }
+  }
+  const useTunnel = options.tunnel !== false;
+  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 tunnelHandle = null;
+  let previewTunnelHandle = null;
+  let previewTunnelUrl = null;
+  let tunnelUrl = null;
+  if (useTunnel) {
+    try {
+      console.log(`[dev] Starting extension tunnel on port ${extensionPort}...`);
+      const t = await startTunnel(extensionPort);
+      console.log(`[dev] Extension tunnel ready: ${t.url}`);
+      tunnelHandle = t;
+      tunnelUrl = t.url;
+      console.log(`[dev] Starting preview tunnel on port ${previewPort}...`);
+      const pt = await startTunnel(previewPort);
+      console.log(`[dev] Preview tunnel ready: ${pt.url}`);
+      previewTunnelHandle = pt;
+      previewTunnelUrl = pt.url;
+      console.log(`[dev] Writing VITE_EXTENSION_BUNDLE_URL=${t.url} to .env`);
+      await patchProjectEnv(devContext.projectRoot, "VITE_EXTENSION_BUNDLE_URL", t.url);
+    } catch (err) {
+      console.error("[dev] Failed to start tunnel:", err);
+    }
+  } else {
+    console.log("[dev] Tunnel disabled (--no-tunnel)");
+  }
+  let devSessionToken = null;
+  try {
+    console.log("[dev] Requesting dev session token...");
+    devSessionToken = await requestDevSessionToken(token, resolved.appId, resolved.extensionId);
+    console.log("[dev] Dev session token received");
+  } catch (err) {
+    console.warn("[dev] Failed to obtain dev session token \u2014 dev/staging mode URLs will not include auth token:", err);
+  }
+  console.log(`[dev] Starting dev server in ${devContext.projectRoot}`);
+  const devServerHandle = startDevServer(devContext.projectRoot);
+  const params = buildDevParams({
+    extensionId: resolved.extensionId,
+    tunnelUrl,
+    devSessionToken
+  });
+  console.log("[dev] Ready");
+  return {
+    devContext,
+    extensionPort,
+    previewPort,
+    tunnelUrl,
+    previewTunnelUrl,
+    tunnelHandle,
+    previewTunnelHandle,
+    devServerHandle,
+    devSessionToken,
+    manifestWarnings,
+    params
+  };
+};
+var cleanupDev = async (result) => {
+  console.log("[dev] Shutting down...");
+  try {
+    console.log("[dev] Removing VITE_EXTENSION_BUNDLE_URL from .env");
+    await removeProjectEnvKey(result.devContext.projectRoot, "VITE_EXTENSION_BUNDLE_URL");
+    if (result.tunnelHandle) {
+      console.log("[dev] Stopping Extension tunnel");
+      result.tunnelHandle.stop();
+    }
+    if (result.previewTunnelHandle) {
+      console.log("[dev] Stopping preview tunnel");
+      result.previewTunnelHandle.stop();
+    }
+    console.log("[dev] Stopping dev server");
+    result.devServerHandle.stop();
+  } catch (err) {
+    console.error("[dev] Error during cleanup:", err);
+  }
+  console.log("[dev] Done");
+};
 var DevSetup = ({ initialContext, token, onReady }) => {
   const [step, setStep] = useState("app");
   const [selectedApp, setSelectedApp] = useState(null);
@@ -3043,7 +3194,6 @@ var CopyableField = ({
     /* @__PURE__ */ jsx(Box, { paddingLeft: 2, children: expanded ? /* @__PURE__ */ jsx(Text, { wrap: "wrap", children: value }) : children || /* @__PURE__ */ jsx(Text, { children: labelColor ? /* @__PURE__ */ jsx(Text, { color: labelColor, children: truncated }) : truncated }) })
   ] });
 };
-var toBase64Url = (input) => btoa(input).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 var DevDashboard = ({
   previewTunnelUrl,
   tunnelUrl,
@@ -3068,12 +3218,7 @@ var DevDashboard = ({
       process.off("SIGINT", handler);
     };
   }, [onQuit]);
-  const devParamBlob = useMemo(() => {
-    if (!tunnelUrl || !devSessionToken) {
-      return "";
-    }
-    return toBase64Url(JSON.stringify({ url: tunnelUrl, token: devSessionToken }));
-  }, [tunnelUrl, devSessionToken]);
+  const params = useMemo(() => buildDevParams({ extensionId, tunnelUrl, devSessionToken: devSessionToken ?? null }), [extensionId, tunnelUrl, devSessionToken]);
   useInput((input, key) => {
     if (input === "q" || key.ctrl && input === "c") {
       onQuit();
@@ -3087,7 +3232,7 @@ var DevDashboard = ({
         title: "dev",
         hint: `Live development ${tunnelUrl ? "with" : "w/o"} Tunnel \u2014 ${appName ? `${appName} ` : ""}(${appId})`,
         footer: /* @__PURE__ */ jsxs(Box, { flexDirection: "column", gap: 1, children: [
-          devParamBlob && /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
+          params.paramBlob && /* @__PURE__ */ jsxs(Text, { dimColor: true, children: [
             "Press ",
             /* @__PURE__ */ jsx(Text, { bold: true, color: "yellow", children: "[d]" }),
             " to copy Dev Param, ",
@@ -3142,12 +3287,12 @@ var DevDashboard = ({
               ] })
             ] })
           ] }),
-          tunnelUrl && devSessionToken && /* @__PURE__ */ jsxs(Fragment, { children: [
+          params.devParam && params.stagingParam && params.paramBlob && /* @__PURE__ */ jsxs(Fragment, { children: [
             /* @__PURE__ */ jsx(
               CopyableField,
               {
                 label: "Dev Param (no encryption):",
-                value: `?_stackable_dev=${extensionId}:${devParamBlob}`,
+                value: params.devParam,
                 shortcutKey: "d",
                 children: /* @__PURE__ */ jsxs(Text, { children: [
                   "?",
@@ -3155,7 +3300,7 @@ var DevDashboard = ({
                   "=",
                   /* @__PURE__ */ jsx(Text, { color: "cyan", children: extensionId }),
                   ":",
-                  devParamBlob.slice(0, 20),
+                  params.paramBlob.slice(0, 20),
                   "..."
                 ] })
               }
@@ -3164,7 +3309,7 @@ var DevDashboard = ({
               CopyableField,
               {
                 label: "Staging Param (with encryption):",
-                value: `?_stackable_staging=${extensionId}:${devParamBlob}`,
+                value: params.stagingParam,
                 shortcutKey: "s",
                 children: /* @__PURE__ */ jsxs(Text, { children: [
                   "?",
@@ -3172,13 +3317,13 @@ var DevDashboard = ({
                   "=",
                   /* @__PURE__ */ jsx(Text, { color: "cyan", children: extensionId }),
                   ":",
-                  devParamBlob.slice(0, 20),
+                  params.paramBlob.slice(0, 20),
                   "..."
                 ] })
               }
             )
           ] }),
-          tunnelUrl && !devSessionToken && /* @__PURE__ */ jsxs(Box, { gap: 2, children: [
+          params.devParam && !params.paramBlob && /* @__PURE__ */ jsxs(Box, { gap: 2, children: [
             /* @__PURE__ */ jsx(Text, { dimColor: true, children: "Host Dev - Query Param:" }),
             /* @__PURE__ */ jsxs(Text, { children: [
               "?",
@@ -3206,15 +3351,8 @@ var DevApp = ({ token, userId, orgId, options = {} }) => {
   const [state, setState] = useState("setup");
   const [devContext, setDevContext] = useState(null);
   const [resolvedContext, setResolvedContext] = useState(null);
-  const [tunnelUrl, setTunnelUrl] = useState(null);
-  const [previewTunnelUrl, setPreviewTunnelUrl] = useState(null);
-  const [tunnelHandle, setTunnelHandle] = useState(null);
-  const [previewTunnelHandle, setPreviewTunnelHandle] = useState(null);
-  const [devServerHandle, setDevServerHandle] = useState(null);
-  const [manifestWarnings, setManifestWarnings] = useState([]);
-  const [devSessionToken, setDevSessionToken] = useState(null);
+  const [runResult, setRunResult] = useState(null);
   const shuttingDown = useRef(false);
-  const useTunnel = options.tunnel !== false;
   useEffect(() => {
     const projectRoot = options.dir || process.cwd();
     console.log(`[dev] Reading context from ${projectRoot}`);
@@ -3228,83 +3366,10 @@ var DevApp = ({ token, userId, orgId, options = {} }) => {
       return;
     }
     setResolvedContext(resolved);
-    console.log(`[dev] Saving context: appId=${resolved.appId} extensionId=${resolved.extensionId}`);
-    await writeDevContext(devContext.projectRoot, {
-      ...devContext,
-      appId: resolved.appId,
-      extensionId: resolved.extensionId,
-      appName: resolved.appName || null
-    });
-    if (devContext.manifest) {
-      try {
-        const extensions = await fetchExtensions(token, resolved.appId);
-        const registryExt = extensions[resolved.extensionId];
-        if (registryExt) {
-          const localPerms = new Set(devContext.manifest.permissions);
-          const registryPerms = new Set(registryExt.manifest.permissions);
-          const missingPerms = [...localPerms].filter((p) => !registryPerms.has(p));
-          const extraPerms = [...registryPerms].filter((p) => !localPerms.has(p));
-          const localDomains = new Set(devContext.manifest.allowedDomains);
-          const registryDomains = new Set(registryExt.manifest.allowedDomains);
-          const missingDomains = [...localDomains].filter((d) => !registryDomains.has(d));
-          const extraDomains = [...registryDomains].filter((d) => !localDomains.has(d));
-          const warnings = [];
-          if (missingPerms.length > 0) {
-            warnings.push(`Permissions in local but not registry: ${missingPerms.join(", ")}`);
-          }
-          if (extraPerms.length > 0) {
-            warnings.push(`Permissions in registry but not local: ${extraPerms.join(", ")}`);
-          }
-          if (missingDomains.length > 0) {
-            warnings.push(`Domains in local but not registry: ${missingDomains.join(", ")}`);
-          }
-          if (extraDomains.length > 0) {
-            warnings.push(`Domains in registry but not local: ${extraDomains.join(", ")}`);
-          }
-          if (warnings.length > 0) {
-            setManifestWarnings(warnings);
-          }
-        }
-      } catch {
-      }
-    }
-    const extensionPort = options.extensionPort ? parseInt(options.extensionPort, 10) : devContext.extensionPort;
-    const previewPort = options.previewPort ? parseInt(options.previewPort, 10) : devContext.previewPort;
-    await patchViteAllowedHosts(devContext.projectRoot);
-    if (useTunnel) {
-      try {
-        console.log(`[dev] Starting extension tunnel on port ${extensionPort}...`);
-        const tunnelResult = await startTunnel(extensionPort);
-        console.log(`[dev] Extension tunnel ready: ${tunnelResult.url}`);
-        setTunnelHandle(tunnelResult);
-        setTunnelUrl(tunnelResult.url);
-        console.log(`[dev] Starting preview tunnel on port ${previewPort}...`);
-        const previewTunnelResult = await startTunnel(previewPort);
-        console.log(`[dev] Preview tunnel ready: ${previewTunnelResult.url}`);
-        setPreviewTunnelHandle(previewTunnelResult);
-        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);
-      } catch (err) {
-        console.error("[dev] Failed to start tunnel:", err);
-      }
-    } else {
-      console.log("[dev] Tunnel disabled (--no-tunnel)");
-    }
-    try {
-      console.log("[dev] Requesting dev session token...");
-      const sessionToken = await requestDevSessionToken(token, resolved.appId, resolved.extensionId);
-      console.log("[dev] Dev session token received");
-      setDevSessionToken(sessionToken);
-    } catch (err) {
-      console.warn("[dev] Failed to obtain dev session token \u2014 dev/staging mode URLs will not include auth token:", err);
-    }
-    console.log(`[dev] Starting dev server in ${devContext.projectRoot}`);
-    const serverHandle = startDevServer(devContext.projectRoot);
-    setDevServerHandle(serverHandle);
-    console.log("[dev] Ready");
+    const result = await runDev({ token, devContext, options, resolved });
+    setRunResult(result);
     setState("running");
-  }, [devContext, token, options.extensionPort, options.previewPort, useTunnel]);
+  }, [devContext, token, options]);
   useEffect(() => {
     if (state === "setup" && devContext && devContext.appId && devContext.extensionId) {
       handleSetupReady({
@@ -3315,31 +3380,12 @@ var DevApp = ({ token, userId, orgId, options = {} }) => {
     }
   }, [state, devContext, handleSetupReady]);
   const handleQuit = async () => {
-    if (!devContext || !resolvedContext || shuttingDown.current) {
+    if (!runResult || shuttingDown.current) {
       return;
     }
     shuttingDown.current = true;
     setState("stopping");
-    console.log("[dev] Shutting down...");
-    try {
-      console.log("[dev] Removing VITE_EXTENSION_BUNDLE_URL from .env");
-      await removeProjectEnvKey(devContext.projectRoot, "VITE_EXTENSION_BUNDLE_URL");
-      if (tunnelHandle) {
-        console.log("[dev] Stopping Extension tunnel");
-        tunnelHandle.stop();
-      }
-      if (previewTunnelHandle) {
-        console.log("[dev] Stopping preview tunnel");
-        previewTunnelHandle.stop();
-      }
-      if (devServerHandle) {
-        console.log("[dev] Stopping dev server");
-        devServerHandle.stop();
-      }
-    } catch (err) {
-      console.error("[dev] Error during cleanup:", err);
-    }
-    console.log("[dev] Done");
+    await cleanupDev(runResult);
     process.exit(0);
   };
   useInput((input, key) => {
@@ -3364,22 +3410,22 @@ var DevApp = ({ token, userId, orgId, options = {} }) => {
     }
     return null;
   }
-  if (state === "running" && devContext && resolvedContext) {
+  if (state === "running" && devContext && resolvedContext && runResult) {
     return /* @__PURE__ */ jsx(
       DevDashboard,
       {
-        previewTunnelUrl,
-        tunnelUrl,
+        previewTunnelUrl: runResult.previewTunnelUrl,
+        tunnelUrl: runResult.tunnelUrl,
         orgId,
         userId,
         appId: resolvedContext.appId,
         appName: resolvedContext.appName,
         extensionName: devContext.extensionName,
         extensionId: resolvedContext.extensionId,
-        extensionPort: options.extensionPort ? parseInt(options.extensionPort, 10) : devContext.extensionPort,
-        previewPort: options.previewPort ? parseInt(options.previewPort, 10) : devContext.previewPort,
-        manifestWarnings,
-        devSessionToken,
+        extensionPort: runResult.extensionPort,
+        previewPort: runResult.previewPort,
+        manifestWarnings: runResult.manifestWarnings,
+        devSessionToken: runResult.devSessionToken,
         onQuit: handleQuit
       }
     );
@@ -3960,8 +4006,7 @@ var ensureToken = async () => {
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const isExpired = message.toLowerCase().includes("expired");
-    let recoveredState = null;
-    let flowError = null;
+    const ref = { state: null, error: null };
     const instance = render(
       /* @__PURE__ */ jsx(
         AuthLogin,
@@ -3970,25 +4015,86 @@ var ensureToken = async () => {
           adminApiBaseUrl: getAdminApiBaseUrl(),
           reason: isExpired ? AUTH_LOGIN_REASON.EXPIRED : AUTH_LOGIN_REASON.NOT_LOGGED_IN,
           onSuccess: (authState) => {
-            recoveredState = authState;
+            ref.state = authState;
           },
           onError: (err2) => {
-            flowError = err2;
+            ref.error = err2;
           }
         }
       )
     );
     await instance.waitUntilExit();
-    if (flowError || !recoveredState) {
+    if (ref.error || !ref.state) {
       return null;
     }
     return {
-      token: recoveredState.token,
-      userId: recoveredState.userId,
-      orgId: recoveredState.orgId
+      token: ref.state.token,
+      userId: ref.state.userId,
+      orgId: ref.state.orgId
     };
   }
 };
+var ensureTokenOrFail = async () => {
+  try {
+    const token = await getToken();
+    const state = await readAuthState();
+    if (!state) {
+      throw new Error("not authenticated");
+    }
+    return { token, userId: state.userId, orgId: state.orgId };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[dev] Authentication required: ${message}`);
+    console.error("[dev] Run `stackable-app-extension auth login` interactively first, then re-run with --headless.");
+    process.exit(1);
+  }
+};
+var runHeadlessDev = async (options) => {
+  const auth2 = await ensureTokenOrFail();
+  const projectRoot = options.dir || process.cwd();
+  console.log(`[dev] Reading context from ${projectRoot}`);
+  const devContext = await readDevContext(projectRoot);
+  console.log(
+    `[dev] Context loaded: extension="${devContext.extensionName}" appId=${devContext.appId ?? "(missing)"} extensionId=${devContext.extensionId ?? "(missing)"}`
+  );
+  if (!devContext.appId || !devContext.extensionId) {
+    console.error("[dev] No appId/extensionId in .env.stackable.");
+    console.error("[dev] Run `pnpm preview` interactively once to configure this extension, then re-run with --headless.");
+    process.exit(1);
+  }
+  const result = await runDev({
+    token: auth2.token,
+    devContext,
+    options,
+    resolved: {
+      appId: devContext.appId,
+      extensionId: devContext.extensionId,
+      appName: devContext.appName || void 0
+    }
+  });
+  if (result.params.devEntry) {
+    console.log(`[dev] dev-entry: ${result.params.devEntry}`);
+  }
+  if (result.params.devParam) {
+    console.log(`[dev] dev-param: ${result.params.devParam}`);
+  }
+  if (result.params.stagingEntry) {
+    console.log(`[dev] staging-entry: ${result.params.stagingEntry}`);
+  }
+  if (result.params.stagingParam) {
+    console.log(`[dev] staging-param: ${result.params.stagingParam}`);
+  }
+  for (const warning of result.manifestWarnings) {
+    console.warn(`[dev] manifest warning: ${warning}`);
+  }
+  console.log("[dev] Press Ctrl+C to stop");
+  await new Promise((resolve) => {
+    process.once("SIGTERM", () => resolve());
+    process.once("SIGINT", () => resolve());
+  });
+  await cleanupDev(result);
+  process.exit(0);
+};
 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("--app-id <id>", "Skip App selection").option("--project-id <id>", "Studio project ID (fetches files/manifest from Studio)").option("--template <flavor>", `Template flavor: ${TEMPLATE_FLAVORS.join(", ")}`, parseTemplateFlavor).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(async (name, options) => {
   const auth2 = await ensureToken();
@@ -4050,7 +4156,12 @@ program.command("update" /* UPDATE */).description("Update an existing Extension
     )
   );
 });
-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(async (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("--headless", "Skip interactive dashboard (auto-enabled when stdin is not a TTY)").action(async (options) => {
+  const headless = options.headless || !process.stdin.isTTY;
+  if (headless) {
+    await runHeadlessDev(options);
+    return;
+  }
   const auth2 = await ensureToken();
   if (!auth2) {
     return;

package/package.json

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