tiendu 0.5.0 → 0.6.1

package/README.md

@@ -100,6 +100,8 @@ The build:
 4. Bundles JS/TS and CSS into `dist/assets/`
 5. Runs project PostCSS plugins for CSS entries when available (for example Tailwind v4)
 
+For TypeScript source, extensionless relative imports such as `import { initHeaderCart } from '../lib/scripts/cart'` are supported and recommended.
+
 Entry naming convention:
 
 - `src/layout/theme.ts` → `dist/assets/layout-theme.bundle.js`

package/bin/tiendu.js

@@ -12,6 +12,8 @@ import {
   previewList,
   previewDelete,
   previewOpen,
+  previewAttach,
+  previewDetach,
 } from "../lib/preview.mjs";
 import {
   checkForUpdates,
@@ -24,23 +26,29 @@ tiendu — Tiendu theme development CLI
 
 Usage:
   tiendu init [dir]          Set up a theme project (optionally in a new directory)
-  tiendu pull                Download the live theme from your store
+  tiendu pull [previewKey]   Download the live theme, or a specific preview's files
   tiendu build               Build a theme (requires tiendu.config.json)
-  tiendu push [--skip-build] Upload local files to the active preview (full replace)
+  tiendu push [previewKey] [--skip-build]
+                              Upload files to the attached or specified preview
   tiendu dev                 Start dev mode: auto-sync changes to a live preview URL
-  tiendu publish [--skip-build]
-                              Publish the active preview to the live storefront
-
-  tiendu preview             Show the active preview details
-  tiendu preview create      Create a new remote preview
-  tiendu preview list        List previews for your store
-  tiendu preview delete      Delete the active preview
-  tiendu preview open        Open the active preview URL in your browser
+  tiendu publish [previewKey] [--skip-build]
+                              Publish the attached or specified preview to the live storefront
+
+  tiendu preview             Show the attached preview details
+  tiendu preview create [name]
+                              Create a new preview (and attach to it)
+  tiendu preview list        List all previews for your store
+  tiendu preview attach [key]
+                              Attach to an existing preview by its key
+  tiendu preview detach      Detach from the current preview (without deleting it)
+  tiendu preview delete [key]
+                              Delete a preview (defaults to the attached one)
+  tiendu preview open        Open the attached preview URL in your browser
 
   tiendu check-updates       Check npm for a newer CLI version
   tiendu version             Show the current CLI version
 
-  tiendu help                Show this help message
+  tiendu --help, -h          Show this help message
   tiendu --version, -v       Show the current CLI version
 
 Typical workflow:
@@ -52,10 +60,19 @@ Typical workflow:
   tiendu publish             Ship to the live storefront when ready
 `;
 
+/**
+ * Extract the first positional argument that is not a flag (--skip-build, etc.).
+ * @param {string[]} args - CLI args after the command name
+ * @returns {string | undefined}
+ */
+const extractPositionalArg = (args) =>
+  args.find((arg) => !arg.startsWith("--"));
+
 const main = async () => {
   const args = process.argv.slice(2);
   const command = args[0];
   const subcommand = args[1];
+  const restArgs = args.slice(1);
   const skipBuild = args.includes("--skip-build");
 
   if (
@@ -69,7 +86,6 @@ const main = async () => {
 
   if (
     !command ||
-    command === "help" ||
     command === "--help" ||
     command === "-h"
   ) {
@@ -91,7 +107,8 @@ const main = async () => {
   }
 
   if (command === "pull") {
-    await pull();
+    const previewKey = extractPositionalArg(restArgs);
+    await pull({ previewKey });
     return;
   }
 
@@ -102,7 +119,8 @@ const main = async () => {
   }
 
   if (command === "push") {
-    await push({ skipBuild });
+    const previewKey = extractPositionalArg(restArgs);
+    await push({ skipBuild, previewKey });
     return;
   }
 
@@ -112,7 +130,8 @@ const main = async () => {
   }
 
   if (command === "publish") {
-    await publish({ skipBuild });
+    const previewKey = extractPositionalArg(restArgs);
+    await publish({ skipBuild, previewKey });
     return;
   }
 
@@ -129,8 +148,16 @@ const main = async () => {
       await previewList();
       return;
     }
+    if (subcommand === "attach") {
+      await previewAttach(args[2]);
+      return;
+    }
+    if (subcommand === "detach") {
+      await previewDetach();
+      return;
+    }
     if (subcommand === "delete") {
-      await previewDelete();
+      await previewDelete(args[2]);
       return;
     }
     if (subcommand === "open") {

package/lib/api.mjs

@@ -83,6 +83,47 @@ export const fetchUserStores = async (apiBaseUrl, apiKey) => {
   }
 };
 
+/**
+ * Fetch a single preview by key.
+ *
+ * @param {string} apiBaseUrl
+ * @param {string} apiKey
+ * @param {number} storeId
+ * @param {string} previewKey
+ * @returns {Promise<{ ok: true, data: any } | { ok: false, error: string }>}
+ */
+export const fetchPreview = async (apiBaseUrl, apiKey, storeId, previewKey) => {
+  try {
+    const response = await apiFetch(
+      apiBaseUrl,
+      apiKey,
+      `/api/v2/stores/${storeId}/theme-previews/${previewKey}`,
+    );
+
+    const authError = checkAuthErrors(response);
+    if (authError) return authError;
+
+    if (response.status === 404) {
+      return { ok: false, error: "Preview not found." };
+    }
+
+    if (!response.ok) {
+      return {
+        ok: false,
+        error: `Server error: ${response.status} ${response.statusText}`,
+      };
+    }
+
+    const preview = await response.json();
+    return { ok: true, data: preview };
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Could not fetch preview: ${error.message}`,
+    };
+  }
+};
+
 /**
  * Download the storefront archive (zip) as a buffer.
  *
@@ -124,6 +165,49 @@ export const downloadStorefrontArchive = async (
   }
 };
 
+/**
+ * Download a preview's archive (zip) as a buffer.
+ *
+ * @param {string} apiBaseUrl
+ * @param {string} apiKey
+ * @param {number} storeId
+ * @param {string} previewKey
+ * @returns {Promise<{ ok: true, data: Buffer } | { ok: false, error: string }>}
+ */
+export const downloadPreviewArchive = async (
+  apiBaseUrl,
+  apiKey,
+  storeId,
+  previewKey,
+) => {
+  try {
+    const response = await apiFetch(
+      apiBaseUrl,
+      apiKey,
+      `/api/admin/stores/${storeId}/theme-previews/${previewKey}/download`,
+    );
+
+    const authError = checkAuthErrors(response);
+    if (authError) return authError;
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      return {
+        ok: false,
+        error: `Server error: ${response.status} ${response.statusText}${body ? ` — ${body}` : ""}`,
+      };
+    }
+
+    const arrayBuffer = await response.arrayBuffer();
+    return { ok: true, data: Buffer.from(arrayBuffer) };
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Could not download preview: ${error.message}`,
+    };
+  }
+};
+
 /**
  * Upload a zip buffer to a preview, replacing its content.
  *

package/lib/build.mjs

@@ -23,7 +23,7 @@ import {
 import { listFilesRecursive } from "./fs-utils.mjs";
 import { createCssPostCssPlugin } from "./postcss.mjs";
 
-const THEME_SOURCE_OUTPUT_DIRS = ["layout", "templates", "snippets"];
+const THEME_SOURCE_OUTPUT_DIRS = ["layout", "templates", "sections", "snippets", "config"];
 const LIQUID_LIKE_EXTENSIONS = new Set([".liquid", ".html", ".htm"]);
 const ENTRY_SOURCE_EXTENSIONS = new Set([".js", ".ts", ".css"]);
 const NESTED_ASSET_PATH_PATTERN = /\/assets\/([A-Za-z0-9._-]+(?:\/[A-Za-z0-9._/-]+)+)([?#][A-Za-z0-9=&._-]+)?/g;
@@ -155,7 +155,7 @@ const shouldTriggerTailwindCssRebuild = (relativePath) => {
   const normalizedPath = relativePath.split(path.sep).join("/");
   const extension = path.extname(normalizedPath).toLowerCase();
 
-  if (!["layout/", "templates/", "snippets/"].some((prefix) => normalizedPath.startsWith(prefix))) {
+  if (!["layout/", "templates/", "sections/", "snippets/"].some((prefix) => normalizedPath.startsWith(prefix))) {
     return false;
   }
 
@@ -275,7 +275,7 @@ export const build = async ({ watch: watchMode = false } = {}) => {
 
   const outdir = path.join(distDir, "assets");
   const jsBuildOptions = jsCount > 0
-    ? { entryPoints: jsEntries, bundle: true, format: "esm", target: "es2020", outdir, logLevel: "warning", write: true, plugins: jsPlugins }
+    ? { entryPoints: jsEntries, bundle: true, format: "esm", target: "es2020", outdir, logLevel: "warning", write: true, resolveExtensions: [".ts", ".tsx", ".js", ".jsx", ".json"], plugins: jsPlugins }
     : null;
   const cssBuildOptions = cssCount > 0
     ? { entryPoints: cssEntries, bundle: true, outdir, logLevel: "warning", write: true, plugins: cssPlugins }

package/lib/dev.mjs

@@ -2,12 +2,10 @@ import { watch } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 import * as p from "@clack/prompts";
-import { loadConfigOrFail, writeConfig, isBuiltTheme, getDistDir } from "./config.mjs";
+import { loadConfigOrFail, isBuiltTheme, getDistDir } from "./config.mjs";
 import {
-  buildPreviewUrl,
-  createPreview,
-  listPreviews,
-  resolveActivePreview,
+  fetchPreviewDetails,
+  resolvePreviewKeyInteractively,
 } from "./preview.mjs";
 import {
   deletePreviewFile,
@@ -21,6 +19,7 @@ import { retryAsync } from "./retry.mjs";
 
 const RETRY_ATTEMPTS = 3;
 const MAX_SYNC_FILE_SIZE_BYTES = 20 * 1024 * 1024;
+const CLEANUP_TIMEOUT_MS = 5_000;
 const IGNORED_ROOT_SEGMENTS = new Set(["node_modules", ".git"]);
 
 const hasDotfileSegment = (relativePath) =>
@@ -45,6 +44,27 @@ const shouldIgnoreWatchedPath = (relativePath, builtTheme) => {
 const shouldRetrySyncResult = (result) =>
   !result.ok && Boolean(result.retriable);
 
+const runCleanupStep = async (label, cleanupFn) => {
+  if (!cleanupFn) return;
+
+  let timeoutId = null;
+
+  try {
+    await Promise.race([
+      Promise.resolve().then(() => cleanupFn()),
+      new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+          reject(new Error(`${label} did not finish within ${CLEANUP_TIMEOUT_MS}ms.`));
+        }, CLEANUP_TIMEOUT_MS);
+      }),
+    ]);
+  } catch (error) {
+    p.log.warn(error.message);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+};
+
 const uploadFileWithRetries = (
   apiBaseUrl,
   apiKey,
@@ -95,19 +115,6 @@ const deleteFileWithRetries = (
     },
   );
 
-const resolvePreviewForDev = (previews, configuredPreviewKey) => {
-  const activePreview = resolveActivePreview(previews, configuredPreviewKey);
-  if (activePreview) {
-    return { preview: activePreview, fallbackUsed: false };
-  }
-
-  if (configuredPreviewKey && previews.length === 1) {
-    return { preview: previews[0], fallbackUsed: true };
-  }
-
-  return { preview: null, fallbackUsed: false };
-};
-
 export const dev = async () => {
   const { config, credentials } = await loadConfigOrFail();
   const { apiBaseUrl, storeId } = config;
@@ -127,48 +134,26 @@ export const dev = async () => {
     buildCleanup = buildResult.cleanup;
   }
 
-  const spinner = p.spinner();
-  spinner.start("Connecting to preview...");
+  // Resolve preview via shared interactive picker
+  const previewKey = await resolvePreviewKeyInteractively({ config, credentials });
 
-  const listResult = await listPreviews(apiBaseUrl, apiKey, storeId);
-  if (!listResult.ok) {
-    spinner.stop("Failed to connect.", 1);
-    p.log.error(listResult.error);
+  // Fetch preview to get hostname for local proxy
+  const previewResult = await fetchPreviewDetails(
+    apiBaseUrl,
+    apiKey,
+    storeId,
+    previewKey,
+  );
+  if (!previewResult.ok) {
+    p.log.error(`Preview ${previewKey} not found.`);
     process.exit(1);
   }
 
-  const previewResolution = resolvePreviewForDev(listResult.data, config.previewKey);
-  let activePreview = previewResolution.preview;
-  if (previewResolution.fallbackUsed && activePreview) {
-    p.log.warn(
-      `Stored preview ${config.previewKey} was not found. Using the only available preview ${activePreview.previewKey}.`,
-    );
-  }
-
-  if (!activePreview) {
-    if (config.previewKey) {
-      p.log.warn(
-        `Stored preview ${config.previewKey} was not found. Creating a new preview...`,
-      );
-    }
-
-    spinner.message("Creating preview...");
-    const previewResult = await createPreview(apiBaseUrl, apiKey, storeId, "Dev");
-    if (!previewResult.ok) {
-      spinner.stop("Failed to create preview.", 1);
-      p.log.error(previewResult.error);
-      process.exit(1);
-    }
-
-    activePreview = previewResult.data;
-  }
-
-  const previewKey = activePreview.previewKey;
-  if (config.previewKey !== previewKey) {
-    await writeConfig({ ...config, previewKey });
-  }
+  const previewHostname = previewResult.data.preview.previewHostname;
+  const previewUrl = previewResult.data.url;
 
-  const previewUrl = buildPreviewUrl(apiBaseUrl, activePreview.previewHostname);
+  const spinner = p.spinner();
+  spinner.start("Compressing files...");
 
   const uploadResult = await pushPreparedDirectoryToPreview({
     apiBaseUrl,
@@ -177,7 +162,7 @@ export const dev = async () => {
     previewKey,
     rootDir,
     spinner,
-    packMessage: "Running initial push...",
+    compressMessage: "Compressing files...",
     retryMessage: (result, nextAttempt) =>
       `Initial push failed. Retrying ${nextAttempt}/${RETRY_ATTEMPTS}... ${result.error}`,
   });
@@ -191,19 +176,19 @@ export const dev = async () => {
   try {
     localPreviewServer = await startLocalPreviewServer({
       apiBaseUrl,
-      previewHostname: activePreview.previewHostname,
+      previewHostname,
     });
   } catch (error) {
     p.log.warn(`Could not start local live preview: ${error.message}`);
   }
 
-  spinner.stop("Preview ready.");
+  spinner.stop(`Preview ready (${previewKey}).`);
   if (localPreviewServer) {
     p.log.message(`Local live preview: ${localPreviewServer.url}`);
   }
   p.log.message(`Sharable preview: ${previewUrl}`);
 
-  p.log.message("Watching for changes — press Ctrl+C to stop.");
+  p.log.message("Watching for changes \u2014 press Ctrl+C to stop.");
 
   // ── File watcher ──────────────────────────────────────────────────────────
   /** @type {Map<string, NodeJS.Timeout>} */
@@ -238,7 +223,7 @@ export const dev = async () => {
 
       if (!fileStat || !fileStat.isFile()) {
         if (!fileStat) {
-          console.log(`✕ ${relativePath}`);
+          console.log(`\u2715 ${relativePath}`);
           const result = await deleteFileWithRetries(
             apiBaseUrl,
             apiKey,
@@ -262,7 +247,7 @@ export const dev = async () => {
         return;
       }
 
-      console.log(`↑ ${relativePath}`);
+      console.log(`\u2191 ${relativePath}`);
       if (fileStat.size > MAX_SYNC_FILE_SIZE_BYTES) {
         p.log.warn(
           `     Skipping ${relativePath}: file is ${(fileStat.size / (1024 * 1024)).toFixed(1)} MB (limit ${(MAX_SYNC_FILE_SIZE_BYTES / (1024 * 1024)).toFixed(0)} MB).`,
@@ -317,8 +302,10 @@ export const dev = async () => {
 
     watcher.close();
     for (const timer of debounceMap.values()) clearTimeout(timer);
-    if (localPreviewServer) await localPreviewServer.close();
-    if (buildCleanup) await buildCleanup();
+
+    await runCleanupStep("Local preview shutdown", () => localPreviewServer?.close());
+    await runCleanupStep("Build watcher shutdown", buildCleanup);
+
     p.outro("Dev mode stopped.");
     process.exit(0);
   };

package/lib/local-preview.mjs

@@ -210,7 +210,11 @@ export const startLocalPreviewServer = async ({
   const upstreamOrigin = new URL(apiBaseUrl);
   const previewOrigin = new URL(`${upstreamOrigin.protocol}//${previewHostname}`);
   const sseClients = new Set();
+  const sockets = new Set();
+  const upstreamRequests = new Set();
   let reloadTimer = null;
+  let closed = false;
+  let closePromise = null;
 
   const server = createServer(async (request, response) => {
     if (!request.url) {
@@ -256,6 +260,8 @@ export const startLocalPreviewServer = async ({
     }
 
     const targetUrl = new URL(requestUrl.pathname + requestUrl.search, upstreamOrigin);
+    const upstreamRequest = new AbortController();
+    upstreamRequests.add(upstreamRequest);
 
     try {
       const body = await readRequestBody(request);
@@ -264,10 +270,14 @@ export const startLocalPreviewServer = async ({
         headers: createForwardHeaders(request, previewHostname),
         body,
         redirect: "manual",
-        signal: AbortSignal.timeout(PROXY_TIMEOUT_MS),
+        signal: AbortSignal.any([
+          AbortSignal.timeout(PROXY_TIMEOUT_MS),
+          upstreamRequest.signal,
+        ]),
       });
 
       if (isHtmlResponse(upstreamResponse.headers)) {
+        if (closed || response.destroyed) return;
         const html = injectLiveReloadScript(await upstreamResponse.text());
         writeResponseHeaders(upstreamResponse, response, {
           localOrigin,
@@ -286,6 +296,7 @@ export const startLocalPreviewServer = async ({
         previewOrigin,
         upstreamOrigin,
       });
+      if (closed || response.destroyed) return;
       response.statusCode = upstreamResponse.status;
 
       if (!upstreamResponse.body) {
@@ -300,12 +311,29 @@ export const startLocalPreviewServer = async ({
       });
       proxyStream.pipe(response);
     } catch (error) {
-      const statusCode = error.statusCode ?? 502;
+      if (response.destroyed || response.writableEnded) return;
+
+      const wasAbort = error?.name === "AbortError" || error?.name === "TimeoutError";
+      if (closed && wasAbort) {
+        response.destroy();
+        return;
+      }
+
+      const statusCode = error.statusCode ?? (error?.name === "TimeoutError" ? 504 : 502);
       response.writeHead(statusCode, { "content-type": "text/plain; charset=utf-8" });
       response.end(`Local preview proxy error: ${error.message}`);
+    } finally {
+      upstreamRequests.delete(upstreamRequest);
     }
   });
 
+  server.on("connection", (socket) => {
+    sockets.add(socket);
+    socket.on("close", () => {
+      sockets.delete(socket);
+    });
+  });
+
   const heartbeat = setInterval(() => {
     for (const client of sseClients) {
       client.write(": ping\n\n");
@@ -327,24 +355,39 @@ export const startLocalPreviewServer = async ({
       }, RELOAD_DEBOUNCE_MS);
     },
     async close() {
-      if (reloadTimer) clearTimeout(reloadTimer);
-      clearInterval(heartbeat);
+      if (closePromise) return closePromise;
+      closed = true;
 
-      for (const client of sseClients) {
-        client.end();
-      }
-      sseClients.clear();
+      closePromise = new Promise((resolve, reject) => {
+        if (reloadTimer) clearTimeout(reloadTimer);
+        clearInterval(heartbeat);
+
+        for (const client of sseClients) {
+          client.end();
+        }
+        sseClients.clear();
+
+        for (const upstreamRequest of upstreamRequests) {
+          upstreamRequest.abort();
+        }
 
-      await new Promise((resolve, reject) => {
         server.close((error) => {
-          if (error) {
+          if (error && error.code !== "ERR_SERVER_NOT_RUNNING") {
             reject(error);
             return;
           }
 
           resolve();
         });
+
+        server.closeIdleConnections?.();
+        server.closeAllConnections?.();
+        for (const socket of sockets) {
+          socket.destroy();
+        }
       });
+
+      return closePromise;
     },
   };
 };

package/lib/preview.mjs

@@ -1,6 +1,6 @@
 import * as p from "@clack/prompts";
 import { loadConfigOrFail, writeConfig } from "./config.mjs";
-import { apiFetch } from "./api.mjs";
+import { apiFetch, fetchPreview } from "./api.mjs";
 
 export const buildPreviewUrl = (apiBaseUrl, previewHostname) => {
   const base = new URL(apiBaseUrl);
@@ -8,6 +8,47 @@ export const buildPreviewUrl = (apiBaseUrl, previewHostname) => {
   return `${base.protocol}//${previewHostname}${!hasExplicitPort && base.port ? `:${base.port}` : ""}/`;
 };
 
+const formatShortDateTime = (value) => {
+  if (!value) return "Unknown";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return "Unknown";
+
+  const months = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+  ];
+  const month = months[date.getMonth()];
+  const day = date.getDate();
+  const hours = String(date.getHours()).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  return `${month} ${day} ${hours}:${minutes}`;
+};
+
+export const getPreviewDisplayName = (preview) =>
+  preview.name || `${formatShortDateTime(preview.createdAt)} preview (no name)`;
+
+export const getPreviewUrl = (apiBaseUrl, preview) =>
+  buildPreviewUrl(apiBaseUrl, preview.previewHostname);
+
+export const fetchPreviewDetails = async (
+  apiBaseUrl,
+  apiKey,
+  storeId,
+  previewKey,
+) => {
+  const result = await fetchPreview(apiBaseUrl, apiKey, storeId, previewKey);
+  if (!result.ok) return result;
+
+  return {
+    ok: true,
+    data: {
+      preview: result.data,
+      displayName: getPreviewDisplayName(result.data),
+      url: getPreviewUrl(apiBaseUrl, result.data),
+    },
+  };
+};
+
 /**
  * @param {Array<any>} previews
  * @param {string | undefined} previewKey
@@ -42,18 +83,10 @@ export const createPreview = async (apiBaseUrl, apiKey, storeId, name) => {
       `/api/v2/stores/${storeId}/theme-previews`,
       {
         method: "POST",
-        body: JSON.stringify({ name: name ?? "Dev" }),
+        body: JSON.stringify({ name: name ?? "" }),
       },
     );
 
-    if (response.status === 409) {
-      const body = await response.json().catch(() => ({}));
-      const message =
-        body?.error?.message ??
-        "A preview already exists for this store. Delete it first with: tiendu preview delete";
-      return { ok: false, error: message };
-    }
-
     if (!response.ok) {
       const body = await response.text().catch(() => "");
       return {
@@ -158,6 +191,116 @@ export const publishPreview = async (
   }
 };
 
+// ---------------------------------------------------------------------------
+// Shared interactive preview picker
+// ---------------------------------------------------------------------------
+
+const CREATE_NEW_VALUE = "__create_new__";
+
+/**
+ * Interactively resolve a preview key. Uses attached key if valid, otherwise
+ * prompts the user to pick an existing preview or create a new one.
+ *
+ * @param {{ config: import("./config.mjs").TienduConfig, credentials: import("./config.mjs").TienduCredentials }} opts
+ * @returns {Promise<string>} The resolved preview key
+ */
+export const resolvePreviewKeyInteractively = async ({ config, credentials }) => {
+  const { apiBaseUrl, storeId } = config;
+  const { apiKey } = credentials;
+
+  // 1. Validate stored key
+  if (config.previewKey) {
+    const result = await fetchPreview(apiBaseUrl, apiKey, storeId, config.previewKey);
+    if (result.ok) {
+      return config.previewKey;
+    }
+
+    p.log.warn(`Stored preview ${config.previewKey} was not found. Please select a preview.`);
+    const { previewKey: _, ...rest } = config;
+    await writeConfig(rest);
+  } else {
+    p.log.warn("No preview attached.");
+  }
+
+  // 2. List previews
+  const listResult = await listPreviews(apiBaseUrl, apiKey, storeId);
+  if (!listResult.ok) {
+    p.log.error(listResult.error);
+    process.exit(1);
+  }
+
+  const previews = listResult.data;
+
+  if (previews.length === 0) {
+    p.log.info("No previews found for this store.");
+  }
+
+  // 3. Show picker
+  const options = [
+    ...previews.map((preview) => ({
+      value: preview.previewKey,
+      label: getPreviewDisplayName(preview),
+      hint: preview.previewKey,
+    })),
+    {
+      value: CREATE_NEW_VALUE,
+      label: "Create a new preview",
+    },
+  ];
+
+  const selected = await p.select({
+    message: "Select a preview",
+    options,
+  });
+
+  if (p.isCancel(selected)) {
+    p.cancel("Cancelled.");
+    process.exit(0);
+  }
+
+  // 4. Handle create new
+  if (selected === CREATE_NEW_VALUE) {
+    const nameInput = await p.text({
+      message: "Preview name (optional)",
+      placeholder: "Press Enter to skip",
+      defaultValue: "",
+    });
+
+    if (p.isCancel(nameInput)) {
+      p.cancel("Cancelled.");
+      process.exit(0);
+    }
+
+    const name = (nameInput ?? "").trim();
+    const spinner = p.spinner();
+    spinner.start("Creating preview...");
+
+    const createResult = await createPreview(apiBaseUrl, apiKey, storeId, name);
+    if (!createResult.ok) {
+      spinner.stop("Failed to create preview.", 1);
+      p.log.error(createResult.error);
+      process.exit(1);
+    }
+
+    const preview = createResult.data;
+    const displayName = getPreviewDisplayName(preview);
+    const url = getPreviewUrl(apiBaseUrl, preview);
+    spinner.stop(`Preview "${displayName}" created (${preview.previewKey})`);
+    p.log.message(`  ${url}`);
+
+    await writeConfig({ ...config, previewKey: preview.previewKey });
+    return preview.previewKey;
+  }
+
+  // 5. Attach to selected preview
+  await writeConfig({ ...config, previewKey: selected });
+  const selectedPreview = previews.find((p) => p.previewKey === selected);
+  const displayName = selectedPreview ? getPreviewDisplayName(selectedPreview) : selected;
+  p.log.success(`Attached to "${displayName}" (${selected})`);
+
+  return selected;
+};
+
 // ---------------------------------------------------------------------------
 // CLI commands
 // ---------------------------------------------------------------------------
@@ -182,8 +325,10 @@ export const previewCreate = async (name) => {
   }
 
   const preview = result.data;
-  const url = buildPreviewUrl(config.apiBaseUrl, preview.previewHostname);
-  spinner.stop(`Preview created: ${url}`);
+  const url = getPreviewUrl(config.apiBaseUrl, preview);
+  const displayName = getPreviewDisplayName(preview);
+  spinner.stop(`Preview "${displayName}" created (${preview.previewKey})`);
+  p.log.message(`  ${url}`);
 
   await writeConfig({ ...config, previewKey: preview.previewKey });
 };
@@ -215,14 +360,15 @@ export const previewList = async () => {
     `${result.data.length} preview${result.data.length === 1 ? "" : "s"}:`,
   );
 
-  const activePreview = resolveActivePreview(result.data, config.previewKey);
-
   for (const preview of result.data) {
-    const active =
-      activePreview?.previewKey === preview.previewKey ? " ← active" : "";
+    const isAttached = config.previewKey === preview.previewKey;
+    const indicator = isAttached ? "  \u2190 attached" : "";
     const url = buildPreviewUrl(config.apiBaseUrl, preview.previewHostname);
-    p.log.message(`  ${preview.name}  ${url}${active}`);
+    const displayName = getPreviewDisplayName(preview);
+    p.log.message(`  ${displayName}  ${url}${indicator}`);
   }
+
+  p.log.info("Tip: run tiendu preview attach <key> to switch previews.");
 };
 
 const formatRelativeDate = (value) => {
@@ -245,67 +391,119 @@ const formatRelativeDate = (value) => {
 export const previewShow = async () => {
   const { config, credentials } = await loadConfigOrFail();
 
-  const result = await listPreviews(
+  if (!config.previewKey) {
+    p.log.warn("No preview attached. Run tiendu preview list or tiendu preview create.");
+    process.exit(0);
+  }
+
+  const result = await fetchPreview(
     config.apiBaseUrl,
     credentials.apiKey,
     config.storeId,
+    config.previewKey,
   );
 
   if (!result.ok) {
-    p.log.error(result.error);
-    process.exit(1);
-  }
-
-  const preview = resolveActivePreview(result.data, config.previewKey);
-  if (!preview) {
-    p.log.error(
-      result.data.length === 0
-        ? "No previews found for this store."
-        : "Run tiendu preview list to inspect available previews.",
-    );
+    p.log.warn(`Stored preview ${config.previewKey} was not found.`);
+    p.log.info("Run tiendu preview list to see available previews.");
     process.exit(1);
   }
 
-  const url = buildPreviewUrl(config.apiBaseUrl, preview.previewHostname);
+  const preview = result.data;
+  const url = getPreviewUrl(config.apiBaseUrl, preview);
+  const displayName = getPreviewDisplayName(preview);
 
   p.note(
     [
-      `Name: ${preview.name || "Unnamed preview"}`,
+      `Name: ${displayName}`,
+      `Key: ${preview.previewKey}`,
       `URL: ${url}`,
       `Created: ${formatRelativeDate(preview.createdAt)}`,
     ].join("\n"),
-    "Active preview",
+    "Attached preview",
   );
 };
 
-export const previewDelete = async () => {
+export const previewAttach = async (keyArg) => {
   const { config, credentials } = await loadConfigOrFail();
 
-  const listResult = await listPreviews(
+  if (!keyArg) {
+    await resolvePreviewKeyInteractively({ config, credentials });
+    return;
+  }
+
+  const spinner = p.spinner();
+  spinner.start("Validating preview...");
+
+  const result = await fetchPreview(
     config.apiBaseUrl,
     credentials.apiKey,
     config.storeId,
+    keyArg,
   );
-  if (!listResult.ok) {
-    p.log.error(listResult.error);
+
+  if (!result.ok) {
+    spinner.stop("Preview not found.", 1);
+    p.log.error("Preview not found. Run tiendu preview list to see available previews.");
     process.exit(1);
   }
 
-  const activePreview = resolveActivePreview(
-    listResult.data,
-    config.previewKey,
+  const preview = result.data;
+  const url = getPreviewUrl(config.apiBaseUrl, preview);
+  const displayName = getPreviewDisplayName(preview);
+  spinner.stop(`Attached to preview "${displayName}" (${preview.previewKey})`);
+  p.log.message(`  ${url}`);
+
+  await writeConfig({ ...config, previewKey: preview.previewKey });
+};
+
+export const previewDetach = async () => {
+  const { config } = await loadConfigOrFail();
+
+  if (!config.previewKey) {
+    p.log.warn("No preview is currently attached.");
+    process.exit(0);
+  }
+
+  const detachedKey = config.previewKey;
+  const { previewKey: _, ...rest } = config;
+  await writeConfig(rest);
+
+  p.log.success(`Detached from preview ${detachedKey}. No active preview.`);
+};
+
+export const previewDelete = async (keyArg) => {
+  const { config, credentials } = await loadConfigOrFail();
+
+  let previewKey = keyArg;
+
+  if (!previewKey) {
+    if (!config.previewKey) {
+      p.log.warn("No preview attached and no key provided.");
+      p.log.info("Run tiendu preview delete <key> or tiendu preview attach first.");
+      process.exit(1);
+    }
+    previewKey = config.previewKey;
+  }
+
+  // Fetch preview to show its name in the confirmation
+  const fetchResult = await fetchPreview(
+    config.apiBaseUrl,
+    credentials.apiKey,
+    config.storeId,
+    previewKey,
   );
-  if (!activePreview) {
-    p.log.error(
-      listResult.data.length === 0
-        ? "No previews found for this store."
-        : "Could not determine the active preview. Run tiendu preview list first.",
-    );
+
+  if (!fetchResult.ok) {
+    p.log.error(`Preview ${previewKey} not found.`);
     process.exit(1);
   }
 
+  const displayName = getPreviewDisplayName(fetchResult.data);
+  const url = getPreviewUrl(config.apiBaseUrl, fetchResult.data);
+
   const confirmed = await p.confirm({
-    message: `Delete preview ${activePreview.previewKey}?`,
+    message: `Delete preview ${previewKey} "${displayName}" (${url})?`,
   });
 
   if (p.isCancel(confirmed) || !confirmed) {
@@ -320,7 +518,7 @@ export const previewDelete = async () => {
     config.apiBaseUrl,
     credentials.apiKey,
     config.storeId,
-    activePreview.previewKey,
+    previewKey,
   );
 
   if (!result.ok) {
@@ -331,40 +529,38 @@ export const previewDelete = async () => {
 
   spinner.stop("Preview deleted.");
 
-  const { previewKey, ...rest } = config;
-  await writeConfig(rest);
+  if (config.previewKey === previewKey) {
+    const { previewKey: _, ...rest } = config;
+    await writeConfig(rest);
+  }
 };
 
 export const previewOpen = async () => {
   const { config, credentials } = await loadConfigOrFail();
 
+  if (!config.previewKey) {
+    p.log.warn("No preview attached. Run tiendu preview attach or tiendu preview create.");
+    process.exit(1);
+  }
+
   const spinner = p.spinner();
   spinner.start("Fetching preview URL...");
 
-  const result = await listPreviews(
+  const result = await fetchPreview(
     config.apiBaseUrl,
     credentials.apiKey,
     config.storeId,
+    config.previewKey,
   );
 
   if (!result.ok) {
-    spinner.stop("Failed to fetch previews.", 1);
-    p.log.error(result.error);
+    spinner.stop("Preview not found.", 1);
+    p.log.error("Stored preview was not found. Run tiendu preview list.");
     process.exit(1);
   }
 
-  const preview = resolveActivePreview(result.data, config.previewKey);
-  if (!preview) {
-    spinner.stop("Could not determine the active preview.", 1);
-    p.log.error(
-      result.data.length === 0
-        ? "No previews found for this store."
-        : "Run tiendu preview list and then set or recreate the preview.",
-    );
-    process.exit(1);
-  }
-
-  const url = buildPreviewUrl(config.apiBaseUrl, preview.previewHostname);
+  const preview = result.data;
+  const url = getPreviewUrl(config.apiBaseUrl, preview);
   spinner.stop(`Opening ${url}`);
 
   const { spawn } = await import("node:child_process");

package/lib/publish.mjs

@@ -1,18 +1,35 @@
 import * as p from "@clack/prompts";
-import { loadConfigOrFail, writeConfig, isBuiltTheme } from "./config.mjs";
-import { publishPreview } from "./preview.mjs";
+import { loadConfigOrFail, isBuiltTheme } from "./config.mjs";
+import {
+  fetchPreviewDetails,
+  publishPreview,
+  resolvePreviewKeyInteractively,
+} from "./preview.mjs";
 import { push } from "./push.mjs";
 
-export const publish = async ({ skipBuild = false } = {}) => {
+export const publish = async ({ skipBuild = false, previewKey: previewKeyArg } = {}) => {
   const { config, credentials } = await loadConfigOrFail();
 
-  if (!config.previewKey) {
-    p.log.error("No active preview. Create one with: tiendu preview create");
-    process.exit(1);
-  }
+  // Resolve preview key: explicit arg > interactive picker
+  const previewKey = previewKeyArg ?? await resolvePreviewKeyInteractively({ config, credentials });
+
+  // Fetch preview to show its name in the confirmation
+  const fetchResult = await fetchPreviewDetails(
+    config.apiBaseUrl,
+    credentials.apiKey,
+    config.storeId,
+    previewKey,
+  );
+
+  const displayName = fetchResult.ok
+    ? fetchResult.data.displayName
+    : previewKey;
+  const previewUrl = fetchResult.ok ? fetchResult.data.url : null;
 
   const confirmed = await p.confirm({
-    message: `Publish preview ${config.previewKey} to the live storefront?`,
+    message: previewUrl
+      ? `Publish preview "${displayName}" (${previewKey}) at ${previewUrl} to the live storefront?`
+      : `Publish preview "${displayName}" (${previewKey}) to the live storefront?`,
   });
 
   if (p.isCancel(confirmed) || !confirmed) {
@@ -26,17 +43,17 @@ export const publish = async ({ skipBuild = false } = {}) => {
         ? "Syncing existing dist/ output to the preview before publishing..."
         : "Building and syncing the latest dist/ output before publishing...",
     );
-    await push({ skipBuild });
+    await push({ skipBuild, previewKey });
   }
 
   const spinner = p.spinner();
-  spinner.start("Publishing preview...");
+  spinner.start("Publishing preview to live storefront...");
 
   const result = await publishPreview(
     config.apiBaseUrl,
     credentials.apiKey,
     config.storeId,
-    config.previewKey,
+    previewKey,
   );
 
   if (!result.ok) {
@@ -45,10 +62,8 @@ export const publish = async ({ skipBuild = false } = {}) => {
     process.exit(1);
   }
 
-  spinner.stop("Preview published. Your live storefront has been updated.");
-  p.log.info("All previews for this store have been removed.");
-
-  // Remove preview key from config
-  const { previewKey, ...rest } = config;
-  await writeConfig(rest);
+  spinner.stop(`Preview ${previewKey} published. Your live storefront has been updated.`);
+  if (previewUrl) {
+    p.log.message(`  ${previewUrl}`);
+  }
 };

package/lib/pull.mjs

@@ -1,6 +1,7 @@
 import * as p from "@clack/prompts";
 import { loadConfigOrFail, isBuiltTheme, getDistDir } from "./config.mjs";
-import { downloadStorefrontArchive } from "./api.mjs";
+import { downloadStorefrontArchive, downloadPreviewArchive } from "./api.mjs";
+import { fetchPreviewDetails } from "./preview.mjs";
 import { extractZip } from "./zip.mjs";
 
 /** @param {number} bytes */
@@ -10,32 +11,56 @@ const formatBytes = (bytes) => {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 };
 
-export const pull = async () => {
+export const pull = async ({ previewKey } = {}) => {
   const { config, credentials } = await loadConfigOrFail();
+  const previewDetails = previewKey
+    ? await fetchPreviewDetails(
+        config.apiBaseUrl,
+        credentials.apiKey,
+        config.storeId,
+        previewKey,
+      )
+    : null;
 
   const spinner = p.spinner();
-  spinner.start(`Downloading theme from store #${config.storeId}...`);
+  const isPreviewPull = Boolean(previewKey);
 
-  const result = await downloadStorefrontArchive(
-    config.apiBaseUrl,
-    credentials.apiKey,
-    config.storeId,
+  spinner.start(
+    isPreviewPull
+      ? `Downloading preview ${previewKey} from store #${config.storeId}...`
+      : `Downloading live theme from store #${config.storeId}...`,
   );
 
+  const result = isPreviewPull
+    ? await downloadPreviewArchive(
+        config.apiBaseUrl,
+        credentials.apiKey,
+        config.storeId,
+        previewKey,
+      )
+    : await downloadStorefrontArchive(
+        config.apiBaseUrl,
+        credentials.apiKey,
+        config.storeId,
+      );
+
   if (!result.ok) {
     spinner.stop("Download failed.", 1);
     p.log.error(result.error);
     process.exit(1);
   }
 
-  spinner.stop(
-    `Archive received (${formatBytes(result.data.length)}). Extracting...`,
-  );
+  spinner.message(`Extracting archive (${formatBytes(result.data.length)})...`);
 
   const outputDir = (await isBuiltTheme()) ? getDistDir() : process.cwd();
   const extractedFiles = await extractZip(result.data, outputDir);
 
-  p.log.success(
-    `${extractedFiles.length} file${extractedFiles.length === 1 ? "" : "s"} extracted.`,
+  const suffix = isPreviewPull ? ` from preview ${previewKey}` : "";
+  spinner.stop(
+    `${extractedFiles.length} file${extractedFiles.length === 1 ? "" : "s"} extracted${suffix}.`,
   );
+
+  if (previewDetails?.ok) {
+    p.log.message(`  ${previewDetails.data.url}`);
+  }
 };

package/lib/push.mjs

@@ -3,6 +3,10 @@ import { loadConfigOrFail, isBuiltTheme, getDistDir } from "./config.mjs";
 import { uploadPreviewZip } from "./api.mjs";
 import { createZipFromDirectory } from "./archive.mjs";
 import { build } from "./build.mjs";
+import {
+  fetchPreviewDetails,
+  resolvePreviewKeyInteractively,
+} from "./preview.mjs";
 import { retryAsync } from "./retry.mjs";
 
 /** @param {number} bytes */
@@ -19,11 +23,11 @@ export const pushPreparedDirectoryToPreview = async ({
   previewKey,
   rootDir,
   spinner,
-  packMessage = "Packing files...",
+  compressMessage = "Compressing files...",
   uploadMessage,
   retryMessage,
 }) => {
-  spinner.message(packMessage);
+  spinner.message(compressMessage);
 
   const zipBuffer = await createZipFromDirectory(rootDir);
   spinner.message(
@@ -45,14 +49,9 @@ export const pushPreparedDirectoryToPreview = async ({
   );
 };
 
-export const push = async ({ skipBuild = false } = {}) => {
+export const push = async ({ skipBuild = false, previewKey: previewKeyArg } = {}) => {
   const { config, credentials } = await loadConfigOrFail();
 
-  if (!config.previewKey) {
-    p.log.error("No active preview. Create one with: tiendu preview create");
-    process.exit(1);
-  }
-
   const builtTheme = await isBuiltTheme();
 
   if (builtTheme && !skipBuild) {
@@ -62,15 +61,29 @@ export const push = async ({ skipBuild = false } = {}) => {
     }
   }
 
+  // Resolve preview key: explicit arg > interactive picker
+  const previewKey = previewKeyArg ?? await resolvePreviewKeyInteractively({ config, credentials });
+  const previewDetails = await fetchPreviewDetails(
+    config.apiBaseUrl,
+    credentials.apiKey,
+    config.storeId,
+    previewKey,
+  );
+
+  if (!previewDetails.ok) {
+    p.log.error(`Preview ${previewKey} not found.`);
+    process.exit(1);
+  }
+
   const rootDir = builtTheme ? getDistDir() : process.cwd();
   const spinner = p.spinner();
-  spinner.start("Packing files...");
+  spinner.start("Compressing files...");
 
   const result = await pushPreparedDirectoryToPreview({
     apiBaseUrl: config.apiBaseUrl,
     apiKey: credentials.apiKey,
     storeId: config.storeId,
-    previewKey: config.previewKey,
+    previewKey,
     rootDir,
     spinner,
   });
@@ -81,5 +94,6 @@ export const push = async ({ skipBuild = false } = {}) => {
     process.exit(1);
   }
 
-  spinner.stop("Files uploaded to preview.");
+  spinner.stop(`Files uploaded to preview ${previewKey}.`);
+  p.log.message(`  ${previewDetails.data.url}`);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiendu",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "CLI para desarrollar y publicar temas en Tiendu",
   "type": "module",
   "bin": {