tiendu 0.8.2 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 Official CLI for [Tiendu](https://tiendu.uy) — develop and publish storefront themes from your local machine.
 
-Download your store's theme, edit files locally, preview changes live with a local auto-reloading URL plus a sharable preview URL, and publish when you're ready — all from the terminal.
+Download your store's theme, edit files locally, preview changes with a sharable preview URL, and publish when you're ready — all from the terminal.
 
 ---
 
@@ -58,7 +58,7 @@ tiendu stores set <store-id> --non-interactive
 
 When `--non-interactive` is passed, the CLI avoids prompts and prints plain text output.
 
-`tiendu dev` creates a remote preview, builds or stages your theme into `dist/`, runs an initial push from that prepared output, and then watches for changes. It prints a local live-preview URL first, plus a sharable preview URL like:
+`tiendu dev` creates or attaches a remote preview, builds or stages your theme into `dist/`, runs an initial push from that prepared output, and then watches for changes. It prints a sharable preview URL like:
 
 ```
 http://preview-xxxxxxxxxxxx.tiendu.uy/
@@ -67,7 +67,6 @@ http://preview-xxxxxxxxxxxx.tiendu.uy/
 The preview renders with the real Tiendu engine — same output as production.
 
 When `tiendu dev` starts, it always re-syncs your current local files to the active preview before watching for changes.
-It also starts a local live-preview URL that proxies the preview and auto-reloads after successful syncs.
 
 By default, the CLI preserves editor-managed theme state so local development does not overwrite changes made in the theme editor. State files are `templates/*.json`, section group files like `sections/header-group.json`, and `config/settings_data.json`. Use `--override-state` when your local state JSON files should override the editor state.
 
@@ -118,14 +117,17 @@ tiendu stores set 123 --non-interactive
 
 ### `tiendu pull`
 
-Downloads the current live theme from your store into `dist/`.
+Downloads the attached preview theme, or the live theme with `--live`, into `dist/` and syncs theme directories to `src/`.
 
 - `pull` clears `dist/` first.
 - The downloaded archive is then extracted into `dist/`.
-- Your source files, including `src/`, are left untouched.
+- Theme directories from the download are synced into `src/`, overwriting local theme files.
+- In interactive mode, the CLI asks before overwriting `src/`.
+- In non-interactive mode, `src/` is overwritten without prompting.
 
 ```bash
 tiendu pull
+tiendu pull --live
 ```
 
 ---
@@ -184,7 +186,6 @@ tiendu dev --override-state
 - Re-syncs the full local theme to the preview on startup
 - Syncs file creates, edits and deletes
 - Retries failed file sync operations up to 3 times before giving up
-- Starts a local live-preview URL on `localhost` that refreshes after successful uploads
 - Handles both text and binary files (images, fonts, etc.)
 - Press `Ctrl+C` to stop
 

package/bin/tiendu.js

@@ -21,18 +21,19 @@ import {
   checkForUpdatesNow,
   getCurrentVersion,
 } from "../lib/update-check.mjs";
-import { resolveIncludeInstances } from "../lib/config.mjs";
+import { resolveOverrideState } from "../lib/config.mjs";
 import { configureUi } from "../lib/ui.mjs";
 
 const HELP = `
 tiendu — Tiendu theme development CLI
 
 Usage:
-  tiendu init [apiKey] [baseUrl] [--dir <path>]
+  tiendu init [apiKey] [baseUrl] [--api-key <key>] [--base-url <url>] [--preview-key <key>] [--dir <path>]
                                Initialize interactively, or reset config with direct credentials
   tiendu stores list           List stores available for the configured API key
   tiendu stores set <storeId>  Select the active store
-  tiendu pull [previewKey]     Download the live theme or a preview into dist/
+  tiendu pull [previewKey] [--live]
+                                Download the attached preview or a specific preview into dist/ and src/
   tiendu build [--override-state]
                                Build or stage the current theme into dist/
   tiendu push [previewKey] [--skip-build] [--override-state]
@@ -57,6 +58,10 @@ Usage:
 Global options:
   --non-interactive            Disable prompts, print plain text output, and skip confirmations
   --dir <path>                 Create the project inside a new directory during init
+  --api-key <key>              Provide an API key to tiendu init (alternative to positional arg)
+  --base-url <url>             Provide a base URL to tiendu init (alternative to positional arg)
+  --preview-key <key>          Attach a preview during tiendu init
+  --live                       Force tiendu pull to download the live theme
   --skip-build                 Reuse the existing dist/ output for push or publish
   --override-state             Sync local theme state JSON and override editor state
   --preserve-state             Preserve editor-managed state JSON (default)
@@ -69,12 +74,16 @@ Init behavior:
   tiendu init                  Interactive setup wizard
   tiendu init <apiKey>         Reset saved config and connect using the default base URL
   tiendu init <apiKey> <url>   Reset saved config and connect using a custom base URL
+  tiendu init --api-key <key> --base-url <url>   Using flags instead of positional args
+  tiendu init --preview-key <key>                Attach a preview directly
   The default base URL points to the Tiendu platform and rarely needs to change.
   If exactly one store is available, it is selected automatically.
-  If multiple stores are available, run tiendu stores list and tiendu stores set <id>.
+  If multiple stores are available, the interactive init will let you choose one.
+  After selecting a store, you can also create or attach a preview.
 
 Agent-friendly setup:
   tiendu init <apiKey> [baseUrl] --non-interactive
+  tiendu init --api-key <key> --base-url <url> --non-interactive
   tiendu stores list --non-interactive
   tiendu stores set <id> --non-interactive
   tiendu pull --non-interactive
@@ -84,8 +93,8 @@ Agent-friendly setup:
 Push and pull behavior:
   build always prepares dist/ as the local deploy artifact.
   push sends a zip of dist/ to the target preview.
-  pull resets dist/ and extracts the downloaded theme there.
-  pull does not delete src/ files.
+  pull downloads from the attached preview by default, or the live theme with --live.
+  pull also syncs downloaded theme directories to src/.
 
 Pipeline behavior:
   tiendu.config.json can enable optional pipeline steps.
@@ -123,13 +132,13 @@ const parseArgv = (argv) => {
       continue;
     }
 
-    if (arg === "--dir") {
+    if (arg === "--dir" || arg === "--api-key" || arg === "--base-url" || arg === "--preview-key") {
       const value = argv[index + 1];
       if (!value || value.startsWith("--")) {
-        console.error("Missing value for --dir.");
+        console.error(`Missing value for ${arg}.`);
         process.exit(1);
       }
-      values.set("dir", value);
+      values.set(arg.slice(2), value);
       index += 1;
       continue;
     }
@@ -182,8 +191,9 @@ const main = async () => {
     const initArgs = positionals.slice(1);
     await init({
       dirArg: values.get("dir"),
-      apiKeyArg: initArgs[0],
-      baseUrlArg: initArgs[1],
+      apiKeyArg: values.get("api-key") ?? initArgs[0],
+      baseUrlArg: values.get("base-url") ?? initArgs[1],
+      previewKeyArg: values.get("preview-key"),
     });
     return;
   }
@@ -205,44 +215,44 @@ const main = async () => {
   }
 
   if (command === "pull") {
-    await pull({ previewKey: positionals[1] });
+    await pull({ previewKey: positionals[1], forceLive: flags.has("--live") });
     return;
   }
 
   if (command === "build") {
-    const includeInstances = await resolveIncludeInstances({
+    const overrideState = await resolveOverrideState({
       overrideStateFlag,
       preserveStateFlag,
     });
-    const result = await build({ includeInstances });
+    const result = await build({ overrideState });
     if (!result.ok) process.exit(1);
     return;
   }
 
   if (command === "push") {
-    const includeInstances = await resolveIncludeInstances({
+    const overrideState = await resolveOverrideState({
       overrideStateFlag,
       preserveStateFlag,
     });
-    await push({ skipBuild, previewKey: positionals[1], includeInstances });
+    await push({ skipBuild, previewKey: positionals[1], overrideState });
     return;
   }
 
   if (command === "dev") {
-    const includeInstances = await resolveIncludeInstances({
+    const overrideState = await resolveOverrideState({
       overrideStateFlag,
       preserveStateFlag,
     });
-    await dev({ includeInstances });
+    await dev({ overrideState });
     return;
   }
 
   if (command === "publish") {
-    const includeInstances = await resolveIncludeInstances({
+    const overrideState = await resolveOverrideState({
       overrideStateFlag,
       preserveStateFlag,
     });
-    await publish({ skipBuild, previewKey: positionals[1], includeInstances });
+    await publish({ skipBuild, previewKey: positionals[1], overrideState });
     return;
   }
 

package/lib/build.mjs

@@ -129,10 +129,10 @@ const rewriteDirectAssetPaths = (source, knownAssetLogicalPaths) =>
     return flattened ? `/assets/${flattened}${suffix}` : match;
   });
 
-const shouldCopyThemeSourceFile = (sourceRelativePath, outputRelativePath, includeInstances = false) => {
+const shouldCopyThemeSourceFile = (sourceRelativePath, outputRelativePath, overrideState = false) => {
   const extension = path.extname(sourceRelativePath).toLowerCase();
   if (ENTRY_SOURCE_EXTENSIONS.has(extension)) return false;
-  if (!includeInstances && isInstanceFile(outputRelativePath)) return false;
+  if (!overrideState && isInstanceFile(outputRelativePath)) return false;
   return true;
 };
 
@@ -165,7 +165,7 @@ const copyThemeFiles = async (
   distDir,
   themeSourceDirs,
   knownAssetLogicalPaths,
-  includeInstances = false,
+  overrideState = false,
 ) => {
   for (const sourceDir of themeSourceDirs) {
     const absoluteSourceDir = path.join(rootDir, sourceDir.sourceRelativeDir);
@@ -181,7 +181,7 @@ const copyThemeFiles = async (
         sourceDir.outputRelativeDir,
         nestedRelativePath,
       );
-      if (!shouldCopyThemeSourceFile(sourceRelativePath, outputRelativePath, includeInstances)) continue;
+      if (!shouldCopyThemeSourceFile(sourceRelativePath, outputRelativePath, overrideState)) continue;
       await copyThemeSourceFile(
         rootDir,
         distDir,
@@ -261,7 +261,7 @@ const runEntryBuilds = async (jsBuildOptions, cssBuildOptions) => {
  * @param {{ watch?: boolean }} options
  * @returns {Promise<{ ok: boolean, cleanup?: () => Promise<void> }>}
  */
-export const build = async ({ watch: watchMode = false, includeInstances = false } = {}) => {
+export const build = async ({ watch: watchMode = false, overrideState = false } = {}) => {
   const rootDir = process.cwd();
   const distDir = path.join(rootDir, "dist");
 
@@ -324,7 +324,7 @@ export const build = async ({ watch: watchMode = false, includeInstances = false
     distDir,
     themeSourceDirs,
     knownAssetLogicalPaths,
-    includeInstances,
+    overrideState,
   );
 
   if (cssCount > 0 && pipeline.postcss) {
@@ -512,7 +512,7 @@ export const build = async ({ watch: watchMode = false, includeInstances = false
         const timer = setTimeout(async () => {
           debounceMap.delete(sourceRelativePath);
           try {
-            if (!shouldCopyThemeSourceFile(sourceRelativePath, outputRelativePath, includeInstances)) {
+            if (!shouldCopyThemeSourceFile(sourceRelativePath, outputRelativePath, overrideState)) {
               return;
             }
 

package/lib/config.mjs

@@ -153,7 +153,7 @@ export const readThemePipelineConfig = async () =>
  * @param {TienduThemeConfig | null} themeConfig
  * @returns {boolean}
  */
-export const getThemeIncludeInstancesConfig = (themeConfig) => {
+export const getThemeOverrideStateConfig = (themeConfig) => {
   if (themeConfig?.sync?.state !== undefined) return themeConfig.sync.state;
   if (themeConfig?.sync?.instances === "include") return true;
   if (themeConfig?.sync?.instances === "preserve") return false;
@@ -165,7 +165,7 @@ export const getThemeIncludeInstancesConfig = (themeConfig) => {
  * @param {{ overrideStateFlag?: boolean, preserveStateFlag?: boolean }} [options]
  * @returns {Promise<boolean>}
  */
-export const resolveIncludeInstances = async ({
+export const resolveOverrideState = async ({
   overrideStateFlag = false,
   preserveStateFlag = false,
 } = {}) => {
@@ -178,7 +178,7 @@ export const resolveIncludeInstances = async ({
   if (overrideStateFlag) return true;
   if (preserveStateFlag) return false;
 
-  return getThemeIncludeInstancesConfig(await readThemeConfig());
+  return getThemeOverrideStateConfig(await readThemeConfig());
 };
 
 /** @returns {string} */

package/lib/dev.mjs

@@ -12,7 +12,6 @@ import {
 } from "./api.mjs";
 import { build, isInstanceFile } from "./build.mjs";
 import { isDotfile } from "./fs-utils.mjs";
-import { startLocalPreviewServer } from "./local-preview.mjs";
 import { pushPreparedDirectoryToPreview } from "./push.mjs";
 import { retryAsync } from "./retry.mjs";
 import * as ui from "./ui.mjs";
@@ -115,15 +114,14 @@ const deleteFileWithRetries = (
     },
   );
 
-export const dev = async ({ includeInstances = false } = {}) => {
+export const dev = async ({ overrideState = false } = {}) => {
   const { config, credentials } = await loadConfigOrFail();
   const { apiBaseUrl, storeId } = config;
   const { apiKey } = credentials;
   const rootDir = getDistDir();
   let buildCleanup = null;
-  let localPreviewServer = null;
 
-  const buildResult = await build({ watch: true, includeInstances });
+  const buildResult = await build({ watch: true, overrideState });
   if (!buildResult.ok) {
     ui.log.error("Initial build failed. Fix errors and try again.");
     process.exit(1);
@@ -133,7 +131,7 @@ export const dev = async ({ includeInstances = false } = {}) => {
   // Resolve preview via shared interactive picker
   const previewKey = await resolvePreviewKeyInteractively({ config, credentials });
 
-  // Fetch preview to get hostname for local proxy
+  // Fetch preview details for user-facing URLs.
   const previewResult = await fetchPreviewDetails(
     apiBaseUrl,
     apiKey,
@@ -145,7 +143,6 @@ export const dev = async ({ includeInstances = false } = {}) => {
     process.exit(1);
   }
 
-  const previewHostname = previewResult.data.preview.previewHostname;
   const previewUrl = previewResult.data.url;
 
   const spinner = ui.spinner();
@@ -161,7 +158,7 @@ export const dev = async ({ includeInstances = false } = {}) => {
     compressMessage: "Compressing files...",
     retryMessage: (result, nextAttempt) =>
       `Initial push failed. Retrying ${nextAttempt}/${RETRY_ATTEMPTS}... ${result.error}`,
-    includeInstances,
+    overrideState,
   });
 
   if (!uploadResult.ok) {
@@ -170,22 +167,13 @@ export const dev = async ({ includeInstances = false } = {}) => {
     process.exit(1);
   }
 
-  try {
-    localPreviewServer = await startLocalPreviewServer({
-      apiBaseUrl,
-      previewHostname,
-    });
-  } catch (error) {
-    ui.log.warn(`Could not start local live preview: ${error.message}`);
-  }
-
   spinner.stop(`Preview ready (${previewKey}).`);
-  if (localPreviewServer) {
-    ui.log.message(`Local live preview: ${localPreviewServer.url}`);
-  }
   ui.log.message(`Sharable preview: ${previewUrl}`);
   ui.log.message(
-    `Theme state: ${includeInstances ? "overridden from local files" : "preserved from the theme editor"}`,
+    `Theme editor: ${apiBaseUrl}/admin/tiendas/${storeId}/tema/personalizar?preview=${previewKey}`,
+  );
+  ui.log.message(
+    `Theme state: ${overrideState ? "overridden from local files" : "preserved from the theme editor"}`,
   );
 
   ui.log.message("Watching for changes - press Ctrl+C to stop.");
@@ -239,8 +227,6 @@ export const dev = async ({ includeInstances = false } = {}) => {
 
           if (!result.ok) {
             ui.log.warn(`     Failed to delete after ${RETRY_ATTEMPTS} attempts: ${result.error}`);
-          } else {
-            localPreviewServer?.notifyReload();
           }
         }
 
@@ -272,8 +258,6 @@ export const dev = async ({ includeInstances = false } = {}) => {
 
       if (!result.ok) {
         ui.log.warn(`     Failed to upload after ${RETRY_ATTEMPTS} attempts: ${result.error}`);
-      } else {
-        localPreviewServer?.notifyReload();
       }
     } catch (error) {
       ui.log.warn(`     Error processing ${relativePath}: ${error.message}`);
@@ -292,7 +276,7 @@ export const dev = async ({ includeInstances = false } = {}) => {
     if (shouldIgnoreWatchedPath(filename, true)) return;
 
     const relativePath = filename.split(path.sep).join("/");
-    if (!includeInstances && isInstanceFile(relativePath)) return;
+    if (!overrideState && isInstanceFile(relativePath)) return;
     queueSync(relativePath);
   });
 
@@ -304,7 +288,6 @@ export const dev = async ({ includeInstances = false } = {}) => {
     watcher.close();
     for (const timer of debounceMap.values()) clearTimeout(timer);
 
-    await runCleanupStep("Local preview shutdown", () => localPreviewServer?.close());
     await runCleanupStep("Build watcher shutdown", buildCleanup);
 
     ui.outro("Dev mode stopped.");

package/lib/init.mjs

@@ -1,8 +1,10 @@
-import { mkdir, access } from "node:fs/promises";
+import { mkdir, readdir } from "node:fs/promises";
 import path from "node:path";
 import { readConfig, readCredentials, writeConfig, writeCredentials } from "./config.mjs";
-import { fetchUserStores } from "./api.mjs";
+import { fetchUserStores, fetchPreview } from "./api.mjs";
 import { formatInitSummary } from "./stores.mjs";
+import { listPreviews, createPreview, getPreviewDisplayName, getPreviewUrl } from "./preview.mjs";
+import { pull } from "./pull.mjs";
 import * as ui from "./ui.mjs";
 
 const DEFAULT_API_BASE_URL = "https://tiendu.uy";
@@ -21,19 +23,52 @@ const resolveBaseUrlOrFail = (baseUrlArg) => {
   return candidate;
 };
 
-const prepareWorkDir = async (dirArg) => {
-  if (!dirArg) return;
+const checkTargetDir = async (dirArg) => {
+  if (dirArg) {
+    const targetDir = path.resolve(process.cwd(), dirArg);
+    try {
+      const entries = await readdir(targetDir);
+      const hasContent = entries.filter((n) => !n.startsWith(".")).length > 0;
+      if (hasContent && !ui.isInteractive()) {
+        ui.log.error(`Directory "${dirArg}" already exists and is not empty.`);
+        process.exit(1);
+      }
 
-  const targetDir = path.resolve(process.cwd(), dirArg);
+      if (hasContent) {
+        const confirmed = await ui.confirm({
+          message: `Directory "${dirArg}" already exists. Overwrite its contents?`,
+        });
+        if (ui.isCancel(confirmed) || !confirmed) {
+          ui.cancel("Setup cancelled.");
+          process.exit(0);
+        }
+      }
+    } catch {
+      // Directory doesn't exist — fine
+    }
+    return;
+  }
 
   try {
-    await access(targetDir);
-    ui.cancel(`Directory "${dirArg}" already exists.`);
-    process.exit(1);
+    const entries = await readdir(process.cwd());
+    const hasContent = entries.filter((n) => !n.startsWith(".") && n !== ".cli").length > 0;
+    if (hasContent && ui.isInteractive()) {
+      const confirmed = await ui.confirm({
+        message: "Current directory is not empty. Overwrite its contents?",
+      });
+      if (ui.isCancel(confirmed) || !confirmed) {
+        ui.cancel("Setup cancelled.");
+        process.exit(0);
+      }
+    }
   } catch {
-    // Safe to create the target directory.
+    // Can't happen for cwd
   }
+};
 
+const enterTargetDir = async (dirArg) => {
+  if (!dirArg) return;
+  const targetDir = path.resolve(process.cwd(), dirArg);
   await mkdir(targetDir, { recursive: true });
   process.chdir(targetDir);
 };
@@ -108,9 +143,7 @@ const collectDirectInputs = (apiKeyArg, baseUrlArg) => {
   };
 };
 
-export const init = async ({ dirArg, apiKeyArg, baseUrlArg } = {}) => {
-  await prepareWorkDir(dirArg);
-
+export const init = async ({ dirArg, apiKeyArg, baseUrlArg, previewKeyArg } = {}) => {
   const existingConfig = await readConfig();
   const existingCredentials = await readCredentials();
   const hasExistingSetup = Boolean(existingConfig || existingCredentials);
@@ -121,7 +154,7 @@ export const init = async ({ dirArg, apiKeyArg, baseUrlArg } = {}) => {
     process.exit(1);
   }
 
-  if (!directMode) {
+  if (!directMode && !dirArg) {
     await ensureResetAllowed(hasExistingSetup);
   }
 
@@ -146,20 +179,156 @@ export const init = async ({ dirArg, apiKeyArg, baseUrlArg } = {}) => {
     process.exit(1);
   }
 
-  const selectedStore = stores.length === 1 ? stores[0] : null;
-  spinner.stop(`Connected to Tiendu. ${stores.length} store${stores.length === 1 ? "" : "s"} available.`);
+  let selectedStore = stores.length === 1 ? stores[0] : null;
+
+  if (!selectedStore && ui.isInteractive()) {
+    spinner.stop(`Connected to Tiendu. ${stores.length} stores available.`);
+
+    const storeOptions = stores.map((store) => ({
+      value: store.id,
+      label: store.name,
+      hint: `ID: ${store.id}`,
+    }));
+
+    const chosen = await ui.select({
+      message: "Select a store",
+      options: storeOptions,
+    });
+
+    if (ui.isCancel(chosen)) {
+      ui.cancel("Setup cancelled.");
+      process.exit(1);
+    }
+
+    selectedStore = stores.find((s) => s.id === chosen) ?? null;
+  }
+
+  if (selectedStore || stores.length === 1) {
+    spinner.stop(
+      `Connected to Tiendu. ${stores.length} store${stores.length === 1 ? "" : "s"} available.`,
+    );
+  } else {
+    spinner.stop(
+      `Connected to Tiendu. ${stores.length} stores available.`,
+    );
+  }
+
+  let previewKey = null;
+
+  if (previewKeyArg && selectedStore) {
+    const result = await fetchPreview(apiBaseUrl, apiKey, selectedStore.id, previewKeyArg);
+    if (result.ok) {
+      previewKey = previewKeyArg;
+      const url = getPreviewUrl(apiBaseUrl, result.data);
+      const displayName = getPreviewDisplayName(result.data);
+      ui.log.message(`Preview "${displayName}" (${previewKey})`);
+      ui.log.message(`  ${url}`);
+    } else {
+      ui.log.error(`Preview ${previewKeyArg} not found.`);
+      process.exit(1);
+    }
+  } else if (selectedStore && ui.isInteractive()) {
+    const listResult = await listPreviews(apiBaseUrl, apiKey, selectedStore.id);
+    let previews = [];
+    if (listResult.ok) {
+      previews = listResult.data;
+    }
+
+    const LIVE_VALUE = "__live__";
+    const CREATE_NEW_VALUE = "__create_new__";
+
+    const options = [
+      {
+        value: LIVE_VALUE,
+        label: "Live theme",
+        hint: "No preview — work directly with the live storefront",
+      },
+      ...previews.map((p) => ({
+        value: p.previewKey,
+        label: `${getPreviewDisplayName(p)} (${p.previewKey})`,
+      })),
+      { value: CREATE_NEW_VALUE, label: "Create a new preview" },
+    ];
+
+    const chosen = await ui.select({
+      message: "Select a preview",
+      options,
+    });
+
+    if (ui.isCancel(chosen)) {
+      ui.cancel("Setup cancelled.");
+      process.exit(1);
+    }
+
+    if (chosen === LIVE_VALUE) {
+      // Live theme — no preview key
+    } else if (chosen === CREATE_NEW_VALUE) {
+      const nameInput = await ui.text({
+        message: "Preview name (optional)",
+        placeholder: "Press Enter to skip",
+        defaultValue: "",
+      });
+
+      if (ui.isCancel(nameInput)) {
+        ui.cancel("Setup cancelled.");
+        process.exit(1);
+      }
+
+      const name = (nameInput ?? "").trim();
+      const createSpinner = ui.spinner();
+      createSpinner.start("Creating preview...");
+
+      const createResult = await createPreview(
+        apiBaseUrl,
+        apiKey,
+        selectedStore.id,
+        name,
+      );
+
+      if (!createResult.ok) {
+        createSpinner.stop("Failed to create preview.", 1);
+        ui.log.error(createResult.error);
+        process.exit(1);
+      }
+
+      const preview = createResult.data;
+      previewKey = preview.previewKey;
+      const url = getPreviewUrl(apiBaseUrl, preview);
+      const displayName = getPreviewDisplayName(preview);
+      createSpinner.stop(`Preview "${displayName}" created (${previewKey})`);
+      ui.log.message(`  ${url}`);
+    } else {
+      const selectedPreview = previews.find((p) => p.previewKey === chosen);
+      previewKey = chosen;
+      if (selectedPreview) {
+        const displayName = getPreviewDisplayName(selectedPreview);
+        const url = getPreviewUrl(apiBaseUrl, selectedPreview);
+        ui.log.message(`Preview "${displayName}" (${previewKey})`);
+        ui.log.message(`  ${url}`);
+      }
+    }
+  }
+
+  await checkTargetDir(dirArg);
+  await enterTargetDir(dirArg);
 
   await writeCredentials({ apiKey });
   await writeConfig({
     apiBaseUrl,
     ...(selectedStore ? { storeId: selectedStore.id } : {}),
+    ...(previewKey ? { previewKey } : {}),
   });
 
+  if (selectedStore) {
+    await pull({ previewKey: previewKey || undefined, confirmSourceSync: false });
+  }
+
   const summary = formatInitSummary({
     apiBaseUrl,
     usedDefaultBaseUrl,
     stores,
     selectedStore,
+    previewKey,
   });
 
   if (ui.isInteractive()) {

package/lib/preview.mjs

@@ -429,12 +429,14 @@ export const previewShow = async () => {
   const preview = result.data;
   const url = getPreviewUrl(config.apiBaseUrl, preview);
   const displayName = getPreviewDisplayName(preview);
+  const editorUrl = `${config.apiBaseUrl}/admin/tiendas/${config.storeId}/tema/personalizar?preview=${preview.previewKey}`;
 
   ui.note(
     [
       `Name: ${displayName}`,
       `Key: ${preview.previewKey}`,
       `URL: ${url}`,
+      `Editor: ${editorUrl}`,
       `Created: ${formatRelativeDate(preview.createdAt)}`,
     ].join("\n"),
     "Attached preview",

package/lib/publish.mjs

@@ -7,7 +7,7 @@ import {
 import { push } from "./push.mjs";
 import * as ui from "./ui.mjs";
 
-export const publish = async ({ skipBuild = false, previewKey: previewKeyArg, includeInstances = false } = {}) => {
+export const publish = async ({ skipBuild = false, previewKey: previewKeyArg, overrideState = false } = {}) => {
   const { config, credentials } = await loadConfigOrFail();
 
   // Resolve preview key: explicit arg > interactive picker
@@ -42,7 +42,7 @@ export const publish = async ({ skipBuild = false, previewKey: previewKeyArg, in
       ? "Syncing existing dist/ output to the preview before publishing..."
       : "Building and syncing the latest dist/ output before publishing...",
   );
-  await push({ skipBuild, previewKey, includeInstances });
+  await push({ skipBuild, previewKey, overrideState });
 
   const spinner = ui.spinner();
   spinner.start("Publishing preview to live storefront...");

package/lib/pull.mjs

@@ -1,4 +1,5 @@
-import { mkdir, rm } from "node:fs/promises";
+import { cp, mkdir, readdir, rm } from "node:fs/promises";
+import path from "node:path";
 import { getDistDir, loadConfigOrFail } from "./config.mjs";
 import { downloadStorefrontArchive, downloadPreviewArchive } from "./api.mjs";
 import { fetchPreviewDetails } from "./preview.mjs";
@@ -12,8 +13,52 @@ const formatBytes = (bytes) => {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 };
 
-export const pull = async ({ previewKey } = {}) => {
+const syncDistToSrc = async (distDir) => {
+  const rootDir = path.resolve(distDir, "..");
+  const srcDir = path.join(rootDir, "src");
+  let entries;
+
+  try {
+    entries = await readdir(distDir, { withFileTypes: true });
+  } catch {
+    return 0;
+  }
+
+  const distDirs = entries.filter(
+    (entry) => entry.isDirectory() && !entry.name.startsWith("."),
+  );
+
+  let synced = 0;
+
+  for (const dir of distDirs) {
+    const distSubDir = path.join(distDir, dir.name);
+    const srcDest = path.join(srcDir, dir.name);
+    const rootDest = path.join(rootDir, dir.name);
+
+    await rm(srcDest, { recursive: true, force: true });
+
+    if (srcDest !== rootDest) {
+      await rm(rootDest, { recursive: true, force: true });
+    }
+
+    await cp(distSubDir, srcDest, { recursive: true });
+    synced++;
+  }
+
+  return synced;
+};
+
+export const pull = async ({ previewKey, forceLive = false, confirmSourceSync = true } = {}) => {
   const { config, credentials } = await loadConfigOrFail();
+
+  if (!previewKey && !forceLive && config.previewKey) {
+    previewKey = config.previewKey;
+  }
+
+  if (forceLive) {
+    previewKey = undefined;
+  }
+
   const previewDetails = previewKey
     ? await fetchPreviewDetails(
         config.apiBaseUrl,
@@ -63,6 +108,23 @@ export const pull = async ({ previewKey } = {}) => {
     `${extractedFiles.length} file${extractedFiles.length === 1 ? "" : "s"} extracted${suffix}.`,
   );
 
+  if (confirmSourceSync && ui.isInteractive()) {
+    const confirmed = await ui.confirm({
+      message: "Sync downloaded theme directories to src/? This overwrites local theme files.",
+    });
+
+    if (ui.isCancel(confirmed) || !confirmed) {
+      ui.cancel("Source sync cancelled. dist/ was updated.");
+      return;
+    }
+  }
+
+  spinner.start("Syncing dist to src...");
+  const syncedDirs = await syncDistToSrc(outputDir);
+  spinner.stop(
+    `${syncedDirs} director${syncedDirs === 1 ? "y" : "ies"} synced to src/.`,
+  );
+
   if (previewDetails?.ok) {
     ui.log.message(`  ${previewDetails.data.url}`);
   }

package/lib/push.mjs

@@ -26,11 +26,11 @@ export const pushPreparedDirectoryToPreview = async ({
   compressMessage = "Compressing files...",
   uploadMessage,
   retryMessage,
-  includeInstances = false,
+  overrideState = false,
 }) => {
   spinner.message(compressMessage);
 
-  const shouldInclude = !includeInstances
+  const shouldInclude = !overrideState
     ? (relativePath) => !isInstanceFile(relativePath)
     : undefined;
 
@@ -40,7 +40,7 @@ export const pushPreparedDirectoryToPreview = async ({
   );
 
   return retryAsync(
-    () => uploadPreviewZip(apiBaseUrl, apiKey, storeId, previewKey, zipBuffer, !includeInstances),
+    () => uploadPreviewZip(apiBaseUrl, apiKey, storeId, previewKey, zipBuffer, !overrideState),
     {
       attempts: 3,
       shouldRetry: (uploadResult) => !uploadResult.ok && Boolean(uploadResult.retriable),
@@ -54,11 +54,11 @@ export const pushPreparedDirectoryToPreview = async ({
   );
 };
 
-export const push = async ({ skipBuild = false, previewKey: previewKeyArg, includeInstances = false } = {}) => {
+export const push = async ({ skipBuild = false, previewKey: previewKeyArg, overrideState = false } = {}) => {
   const { config, credentials } = await loadConfigOrFail();
 
   if (!skipBuild) {
-    const result = await build({ includeInstances });
+    const result = await build({ overrideState });
     if (!result.ok) {
       process.exit(1);
     }
@@ -89,7 +89,7 @@ export const push = async ({ skipBuild = false, previewKey: previewKeyArg, inclu
     previewKey,
     rootDir,
     spinner,
-    includeInstances,
+    overrideState,
   });
 
   if (!result.ok) {
@@ -100,7 +100,7 @@ export const push = async ({ skipBuild = false, previewKey: previewKeyArg, inclu
 
   spinner.stop(`Files uploaded to preview ${previewKey}.`);
   ui.log.message(
-    `Theme state: ${includeInstances ? "overridden from local files" : "preserved from the theme editor"}`,
+    `Theme state: ${overrideState ? "overridden from local files" : "preserved from the theme editor"}`,
   );
   ui.log.message(`  ${previewDetails.data.url}`);
 };

package/lib/stores.mjs

@@ -66,7 +66,7 @@ export const storesSet = async (storeIdArg) => {
   spinner.stop(`Active store set to ${selectedStore.name} (ID: ${selectedStore.id}).`);
 };
 
-export const formatInitSummary = ({ apiBaseUrl, usedDefaultBaseUrl, stores, selectedStore }) => {
+export const formatInitSummary = ({ apiBaseUrl, usedDefaultBaseUrl, stores, selectedStore, previewKey }) => {
   const lines = ["Status: Connected."];
 
   if (usedDefaultBaseUrl) {
@@ -76,7 +76,12 @@ export const formatInitSummary = ({ apiBaseUrl, usedDefaultBaseUrl, stores, sele
   }
 
   if (selectedStore) {
-    lines.push(`Store: ${selectedStore.name} (ID: ${selectedStore.id}) [auto-selected]`);
+    lines.push(`Store: ${selectedStore.name} (ID: ${selectedStore.id})${stores.length === 1 ? " [auto-selected]" : ""}`);
+    if (previewKey) {
+      lines.push(`Preview: ${previewKey} [attached]`);
+    } else {
+      lines.push("Preview: live theme (no preview attached)");
+    }
     return lines.join("\n");
   }
 

package/package.json

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

package/lib/local-preview.mjs

@@ -1,393 +0,0 @@
-import { createServer } from "node:http";
-import { Readable } from "node:stream";
-
-const DEFAULT_PORT = 9292;
-const MAX_PORT_ATTEMPTS = 20;
-const MAX_SSE_CLIENTS = 20;
-const RELOAD_DEBOUNCE_MS = 150;
-const HEARTBEAT_INTERVAL_MS = 15_000;
-const PROXY_TIMEOUT_MS = 30_000;
-const MAX_PROXY_REQUEST_BODY_BYTES = 2 * 1024 * 1024;
-
-const LIVE_RELOAD_PATH = "/__tiendu__/livereload.js";
-const EVENTS_PATH = "/__tiendu__/events";
-
-const LIVE_RELOAD_SCRIPT = `const source = new EventSource(${JSON.stringify(EVENTS_PATH)});
-let reloadTimer = null;
-
-source.addEventListener("reload", () => {
-  if (reloadTimer) clearTimeout(reloadTimer);
-  reloadTimer = setTimeout(() => window.location.reload(), 60);
-});
-`;
-
-const HOP_BY_HOP_HEADERS = new Set([
-  "connection",
-  "keep-alive",
-  "proxy-authenticate",
-  "proxy-authorization",
-  "te",
-  "trailer",
-  "transfer-encoding",
-  "upgrade",
-]);
-
-const readRequestBody = async (request) => {
-  const chunks = [];
-  let totalBytes = 0;
-
-  for await (const chunk of request) {
-    totalBytes += chunk.length;
-    if (totalBytes > MAX_PROXY_REQUEST_BODY_BYTES) {
-      const error = new Error("Local preview request body is too large.");
-      error.statusCode = 413;
-      throw error;
-    }
-
-    chunks.push(chunk);
-  }
-
-  if (chunks.length === 0) return undefined;
-  return Buffer.concat(chunks);
-};
-
-const createForwardHeaders = (request, previewHostname) => {
-  const headers = new Headers();
-
-  for (const [name, value] of Object.entries(request.headers)) {
-    if (value == null) continue;
-
-    const normalizedName = name.toLowerCase();
-    if (
-      HOP_BY_HOP_HEADERS.has(normalizedName) ||
-      normalizedName === "host" ||
-      normalizedName === "origin" ||
-      normalizedName === "referer" ||
-      normalizedName === "content-length"
-    ) {
-      continue;
-    }
-
-    if (Array.isArray(value)) {
-      for (const entry of value) {
-        headers.append(name, entry);
-      }
-      continue;
-    }
-
-    headers.set(name, value);
-  }
-
-  headers.set("host", previewHostname);
-  headers.set("x-forwarded-host", previewHostname);
-
-  return headers;
-};
-
-const isHtmlResponse = (headers) =>
-  (headers.get("content-type") ?? "").toLowerCase().includes("text/html");
-
-const isHtmlDocument = (html) => /<html\b|<!doctype\s+html/i.test(html);
-
-const injectLiveReloadScript = (html) => {
-  if (html.includes(LIVE_RELOAD_PATH)) return html;
-  if (!isHtmlDocument(html)) return html;
-
-  const scriptTag = `<script type="module" src="${LIVE_RELOAD_PATH}"></script>`;
-
-  if (html.includes("</head>")) {
-    return html.replace("</head>", `${scriptTag}</head>`);
-  }
-
-  if (html.includes("</body>")) {
-    return html.replace("</body>", `${scriptTag}</body>`);
-  }
-
-  return `${html}${scriptTag}`;
-};
-
-const rewriteSetCookie = (cookieValue) =>
-  cookieValue
-    .replace(/;\s*Secure/gi, "")
-    .replace(/;\s*Domain=[^;]+/gi, "");
-
-const rewriteLocationHeader = (locationValue, localOrigin, previewOrigin, upstreamOrigin) => {
-  if (!locationValue) return null;
-
-  try {
-    const locationUrl = new URL(locationValue, previewOrigin);
-    if (
-      locationUrl.origin === previewOrigin.origin ||
-      locationUrl.origin === upstreamOrigin.origin
-    ) {
-      return `${localOrigin.origin}${locationUrl.pathname}${locationUrl.search}${locationUrl.hash}`;
-    }
-
-    return locationValue;
-  } catch {
-    return locationValue;
-  }
-};
-
-const writeResponseHeaders = (response, serverResponse, context) => {
-  const { localOrigin, previewOrigin, upstreamOrigin } = context;
-
-  for (const [name, value] of response.headers) {
-    const normalizedName = name.toLowerCase();
-    if (
-      HOP_BY_HOP_HEADERS.has(normalizedName) ||
-      normalizedName === "content-length" ||
-      normalizedName === "content-encoding" ||
-      normalizedName === "set-cookie"
-    ) {
-      continue;
-    }
-
-    if (normalizedName === "location") {
-      const rewritten = rewriteLocationHeader(
-        value,
-        localOrigin,
-        previewOrigin,
-        upstreamOrigin,
-      );
-      if (rewritten) serverResponse.setHeader(name, rewritten);
-      continue;
-    }
-
-    serverResponse.setHeader(name, value);
-  }
-
-  const setCookies = response.headers.getSetCookie?.() ?? [];
-  if (setCookies.length > 0) {
-    serverResponse.setHeader(
-      "set-cookie",
-      setCookies.map(rewriteSetCookie),
-    );
-  }
-};
-
-const listenOnAvailablePort = (server, preferredPort) =>
-  new Promise((resolve, reject) => {
-    let currentPort = preferredPort;
-
-    const tryListen = () => {
-      const onError = (error) => {
-        server.off("listening", onListening);
-
-        if (error?.code === "EADDRINUSE" && currentPort < preferredPort + MAX_PORT_ATTEMPTS) {
-          currentPort += 1;
-          tryListen();
-          return;
-        }
-
-        reject(error);
-      };
-
-      const onListening = () => {
-        server.off("error", onError);
-        const address = server.address();
-        if (!address || typeof address === "string") {
-          reject(new Error("Could not determine local preview port."));
-          return;
-        }
-
-        resolve(address.port);
-      };
-
-      server.once("error", onError);
-      server.once("listening", onListening);
-      server.listen(currentPort, "localhost");
-    };
-
-    tryListen();
-  });
-
-export const startLocalPreviewServer = async ({
-  apiBaseUrl,
-  previewHostname,
-  port = DEFAULT_PORT,
-}) => {
-  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) {
-      response.writeHead(400);
-      response.end("Missing request URL");
-      return;
-    }
-
-    const localOrigin = new URL(`http://${request.headers.host ?? `127.0.0.1:${port}`}`);
-    const requestUrl = new URL(request.url, localOrigin);
-
-    if (requestUrl.pathname === LIVE_RELOAD_PATH) {
-      response.writeHead(200, {
-        "content-type": "application/javascript; charset=utf-8",
-        "cache-control": "no-store",
-      });
-      response.end(LIVE_RELOAD_SCRIPT);
-      return;
-    }
-
-    if (requestUrl.pathname === EVENTS_PATH) {
-      response.writeHead(200, {
-        "content-type": "text/event-stream; charset=utf-8",
-        "cache-control": "no-store",
-        connection: "keep-alive",
-      });
-      response.write("event: connected\ndata: ok\n\n");
-
-      if (sseClients.size >= MAX_SSE_CLIENTS) {
-        const oldestClient = sseClients.values().next().value;
-        oldestClient?.end();
-        if (oldestClient) {
-          sseClients.delete(oldestClient);
-        }
-      }
-
-      sseClients.add(response);
-
-      request.on("close", () => {
-        sseClients.delete(response);
-      });
-      return;
-    }
-
-    const targetUrl = new URL(requestUrl.pathname + requestUrl.search, upstreamOrigin);
-    const upstreamRequest = new AbortController();
-    upstreamRequests.add(upstreamRequest);
-
-    try {
-      const body = await readRequestBody(request);
-      const upstreamResponse = await fetch(targetUrl, {
-        method: request.method,
-        headers: createForwardHeaders(request, previewHostname),
-        body,
-        redirect: "manual",
-        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,
-          previewOrigin,
-          upstreamOrigin,
-        });
-        response.statusCode = upstreamResponse.status;
-        response.setHeader("cache-control", "no-store");
-        response.setHeader("content-length", Buffer.byteLength(html, "utf-8"));
-        response.end(html);
-        return;
-      }
-
-      writeResponseHeaders(upstreamResponse, response, {
-        localOrigin,
-        previewOrigin,
-        upstreamOrigin,
-      });
-      if (closed || response.destroyed) return;
-      response.statusCode = upstreamResponse.status;
-
-      if (!upstreamResponse.body) {
-        response.end();
-        return;
-      }
-
-      const proxyStream = Readable.fromWeb(upstreamResponse.body);
-      proxyStream.on("error", (error) => {
-        console.warn(`Local preview proxy stream error: ${error.message}`);
-        response.destroy(error);
-      });
-      proxyStream.pipe(response);
-    } catch (error) {
-      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");
-    }
-  }, HEARTBEAT_INTERVAL_MS);
-
-  const boundPort = await listenOnAvailablePort(server, port);
-
-  return {
-    url: `http://localhost:${boundPort}/`,
-    notifyReload() {
-      if (reloadTimer) clearTimeout(reloadTimer);
-
-      reloadTimer = setTimeout(() => {
-        reloadTimer = null;
-        for (const client of sseClients) {
-          client.write("event: reload\ndata: now\n\n");
-        }
-      }, RELOAD_DEBOUNCE_MS);
-    },
-    async close() {
-      if (closePromise) return closePromise;
-      closed = true;
-
-      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();
-        }
-
-        server.close((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;
-    },
-  };
-};