tiendu 0.4.0 → 0.6.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 shareable URL, and publish when you're ready — all from the terminal.
+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.
 
 ---
 
@@ -44,7 +44,7 @@ tiendu init
 tiendu dev
 ```
 
-`tiendu dev` creates a remote preview, builds your source files, uploads the output, and watches for changes. It prints a shareable URL like:
+`tiendu dev` creates a remote preview, builds your source files, runs an initial push from the prepared output, and then watches for changes. It prints a local live-preview URL first, plus a sharable preview URL like:
 
 ```
 http://preview-xxxxxxxxxxxx.tiendu.uy/
@@ -52,6 +52,9 @@ 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.
+
 ---
 
 ## Commands
@@ -91,9 +94,13 @@ tiendu build
 
 The build:
 
-1. Copies theme files (`layout/`, `templates/`, `snippets/`, `assets/`) to `dist/`
-2. Discovers entry points in `src/layout/` and `src/templates/`
-3. Bundles JS/TS and CSS via esbuild into `dist/assets/`
+1. Copies theme files from `src/layout/`, `src/templates/`, and `src/snippets/` to `dist/`
+2. Flattens static files from `src/assets/` into `dist/assets/`
+3. Discovers entry points in `src/layout/` and `src/templates/`
+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:
 
@@ -115,7 +122,10 @@ tiendu dev
 ```
 
 - Prints the preview URL on start
+- 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
 
@@ -272,26 +282,59 @@ my-theme/
 ├── .gitignore
 ├── src/
 │   ├── layout/
+│   │   ├── theme.liquid  # copied to dist/layout/theme.liquid
 │   │   ├── theme.ts      # layout TS entry → layout-theme.bundle.js
 │   │   └── theme.css     # layout CSS entry → layout-theme.bundle.css
 │   ├── templates/
+│   │   ├── product.liquid # copied to dist/templates/product.liquid
 │   │   ├── product.ts    # template TS entry → template-product.bundle.js
 │   │   └── product.css   # template CSS entry → template-product.bundle.css
+│   ├── snippets/         # Liquid snippets copied to dist/snippets/
+│   ├── assets/           # source assets → flattened into dist/assets/
 │   ├── lib/              # shared modules (bundled into entries, not served)
 │   └── css/              # shared CSS (imported by entry CSS)
-├── layout/               # Liquid layouts
-├── templates/            # Liquid templates
-├── snippets/             # Liquid snippets
-├── assets/               # static assets (SVGs, images, fonts)
 └── dist/                 # build output (gitignored, uploaded to Tiendu)
 ```
 
 ### How it works
 
-1. Source JS/TS/CSS in `src/` is bundled by esbuild into `dist/assets/`
-2. Liquid files and static assets are copied from root to `dist/`
-3. `dist/` is what gets uploaded — it looks like a normal Tiendu theme
-4. Liquid templates reference bundles via `asset_url` (e.g. `{{ 'layout-theme.bundle.js' | asset_url | script_tag }}`)
+1. Source assets in `src/assets/` are flattened into `dist/assets/` (`payment-methods/visa.svg` becomes `payment-methods___visa.svg`)
+2. Source JS/TS/CSS in `src/` is bundled by esbuild into `dist/assets/`
+3. CSS entries also run through your local PostCSS pipeline when configured
+4. Liquid files are copied from `src/` to `dist/`
+5. `dist/` is what gets uploaded — it looks like a normal Tiendu theme
+6. Liquid templates reference bundles and assets via `asset_url` (e.g. `{{ 'layout-theme.bundle.js' | asset_url | script_tag }}` or `{{ 'payment-methods/visa.svg' | asset_url }}`)
+
+### Tailwind v4
+
+Built themes can use Tailwind v4 in CSS entry files.
+
+Install it in your theme project:
+
+```bash
+npm install -D tailwindcss @tailwindcss/postcss postcss
+```
+
+Then import Tailwind from a CSS entry such as `src/layout/theme.css`:
+
+```css
+@import "tailwindcss";
+```
+
+You can either:
+
+- rely on Tiendu CLI's automatic Tailwind detection when `@tailwindcss/postcss` is installed, or
+- add a local `postcss.config.mjs` / `postcss.config.js` / `postcss.config.cjs` / `postcss.config.json`
+
+Example `postcss.config.mjs`:
+
+```js
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+```
 
 ### tiendu.config.json
 

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/bin/tiendu.mjs

@@ -1,138 +1,3 @@
 #!/usr/bin/env node
 
-import { init } from "../lib/init.mjs";
-import { pull } from "../lib/pull.mjs";
-import { push } from "../lib/push.mjs";
-import { dev } from "../lib/dev.mjs";
-import { publish } from "../lib/publish.mjs";
-import {
-  previewCreate,
-  previewList,
-  previewDelete,
-  previewOpen,
-} from "../lib/preview.mjs";
-import {
-  checkForUpdates,
-  checkForUpdatesNow,
-  getCurrentVersion,
-} from "../lib/update-check.mjs";
-
-const HELP = `
-tiendu — CLI para desarrollar temas de Tiendu
-
-Uso:
-  tiendu init                Inicializar un tema en el directorio actual
-  tiendu pull                Descargar el tema live desde Tiendu
-  tiendu push [--skip-build] Subir archivos locales al preview activo (ZIP)
-  tiendu dev                 Modo desarrollo: watch + sync automático
-  tiendu publish [--skip-build]
-                              Publicar el preview activo al storefront live
-
-  tiendu preview create      Crear un preview remoto
-  tiendu preview list        Listar previews de la tienda
-  tiendu preview delete      Eliminar el preview activo
-  tiendu preview open        Abrir la URL del preview en el navegador
-
-  tiendu check-updates       Buscar una nueva version del CLI
-  tiendu version             Mostrar la version actual del CLI
-
-  tiendu help                Mostrar esta ayuda
-
-  Opciones:
-  --help, -h                 Mostrar esta ayuda
-  --version, -v              Mostrar la version actual del CLI
-`;
-
-const main = async () => {
-  const args = process.argv.slice(2);
-  const command = args[0];
-  const subcommand = args[1];
-  const skipBuild = args.includes("--skip-build");
-
-  if (
-    command === "version" ||
-    command === "--version" ||
-    command === "-v"
-  ) {
-    console.log(getCurrentVersion());
-    process.exit(0);
-  }
-
-  if (
-    !command ||
-    command === "help" ||
-    command === "--help" ||
-    command === "-h"
-  ) {
-    console.log(HELP.trim());
-    process.exit(0);
-  }
-
-  if (command === "check-updates") {
-    await checkForUpdatesNow();
-    return;
-  }
-
-  await checkForUpdates();
-
-  if (command === "init") {
-    await init();
-    return;
-  }
-
-  if (command === "pull") {
-    await pull();
-    return;
-  }
-
-  if (command === "push") {
-    await push({ skipBuild });
-    return;
-  }
-
-  if (command === "dev") {
-    await dev();
-    return;
-  }
-
-  if (command === "publish") {
-    await publish({ skipBuild });
-    return;
-  }
-
-  if (command === "preview") {
-    if (subcommand === "create") {
-      const name = args[2];
-      await previewCreate(name);
-      return;
-    }
-
-    if (subcommand === "list") {
-      await previewList();
-      return;
-    }
-
-    if (subcommand === "delete") {
-      await previewDelete();
-      return;
-    }
-
-    if (subcommand === "open") {
-      await previewOpen();
-      return;
-    }
-
-    console.error(`Subcomando desconocido: preview ${subcommand ?? "(vacío)"}`);
-    console.log(HELP.trim());
-    process.exit(1);
-  }
-
-  console.error(`Comando desconocido: ${command}`);
-  console.log(HELP.trim());
-  process.exit(1);
-};
-
-main().catch((error) => {
-  console.error(error.message || error);
-  process.exit(1);
-});
+import "./tiendu.js";

package/lib/api.mjs

@@ -2,9 +2,14 @@
  * @param {string} apiBaseUrl
  * @param {string} apiKey
  * @param {string} path
- * @param {{ method?: string, body?: string | Buffer | Uint8Array, contentType?: string }} [options]
+ * @param {{ method?: string, body?: string | Buffer | Uint8Array, contentType?: string, signal?: AbortSignal }} [options]
  * @returns {Promise<Response>}
  */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+const isRetriableStatus = (status) =>
+  status === 408 || status === 425 || status === 429 || status >= 500;
+
 export const apiFetch = (apiBaseUrl, apiKey, path, options = {}) => {
   const url = `${apiBaseUrl}${path}`;
   /** @type {Record<string, string>} */
@@ -22,6 +27,7 @@ export const apiFetch = (apiBaseUrl, apiKey, path, options = {}) => {
     method: options.method ?? "GET",
     headers,
     body: options.body,
+    signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
   });
 };
 
@@ -77,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.
  *
@@ -119,76 +166,74 @@ export const downloadStorefrontArchive = async (
 };
 
 /**
- * Upload a zip buffer to a preview, replacing its content.
+ * Download a preview's archive (zip) as a buffer.
  *
  * @param {string} apiBaseUrl
  * @param {string} apiKey
  * @param {number} storeId
  * @param {string} previewKey
- * @param {Buffer} zipBuffer
- * @returns {Promise<{ ok: true } | { ok: false, error: string }>}
+ * @returns {Promise<{ ok: true, data: Buffer } | { ok: false, error: string }>}
  */
-export const uploadPreviewZip = async (
+export const downloadPreviewArchive = async (
   apiBaseUrl,
   apiKey,
   storeId,
   previewKey,
-  zipBuffer,
 ) => {
   try {
     const response = await apiFetch(
       apiBaseUrl,
       apiKey,
-      `/api/admin/stores/${storeId}/theme-previews/${previewKey}/upload`,
-      {
-        method: "POST",
-        body: zipBuffer,
-        contentType: "application/zip",
-      },
+      `/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: `Error del servidor: ${response.status}${body ? ` — ${body}` : ""}`,
+        error: `Server error: ${response.status} ${response.statusText}${body ? ` — ${body}` : ""}`,
       };
     }
 
-    return { ok: true };
+    const arrayBuffer = await response.arrayBuffer();
+    return { ok: true, data: Buffer.from(arrayBuffer) };
   } catch (error) {
-    return { ok: false, error: `No se pudo subir: ${error.message}` };
+    return {
+      ok: false,
+      error: `Could not download preview: ${error.message}`,
+    };
   }
 };
 
 /**
- * Upload a single file to a preview.
+ * Upload a zip buffer to a preview, replacing its content.
  *
  * @param {string} apiBaseUrl
  * @param {string} apiKey
  * @param {number} storeId
  * @param {string} previewKey
- * @param {string} filePath - relative path within the preview
- * @param {string} content - file content
- * @returns {Promise<{ ok: true } | { ok: false, error: string }>}
+ * @param {Buffer} zipBuffer
+ * @returns {Promise<{ ok: true } | { ok: false, error: string, retriable?: boolean }>}
  */
-export const uploadPreviewFile = async (
+export const uploadPreviewZip = async (
   apiBaseUrl,
   apiKey,
   storeId,
   previewKey,
-  filePath,
-  content,
+  zipBuffer,
 ) => {
   try {
-    const query = new URLSearchParams({ path: filePath }).toString();
     const response = await apiFetch(
       apiBaseUrl,
       apiKey,
-      `/api/v2/stores/${storeId}/theme-previews/${previewKey}/file?${query}`,
+      `/api/admin/stores/${storeId}/theme-previews/${previewKey}/upload`,
       {
-        method: "PUT",
-        body: JSON.stringify({ content }),
+        method: "POST",
+        body: zipBuffer,
+        contentType: "application/zip",
       },
     );
 
@@ -196,7 +241,8 @@ export const uploadPreviewFile = async (
       const body = await response.text().catch(() => "");
       return {
         ok: false,
-        error: `Error subiendo ${filePath}: ${response.status}${body ? ` — ${body}` : ""}`,
+        error: `Error del servidor: ${response.status}${body ? ` — ${body}` : ""}`,
+        retriable: isRetriableStatus(response.status),
       };
     }
 
@@ -204,7 +250,8 @@ export const uploadPreviewFile = async (
   } catch (error) {
     return {
       ok: false,
-      error: `Error subiendo ${filePath}: ${error.message}`,
+      error: `No se pudo subir: ${error.message}`,
+      retriable: true,
     };
   }
 };
@@ -219,7 +266,7 @@ export const uploadPreviewFile = async (
  * @param {string} previewKey
  * @param {string} relativePath
  * @param {Buffer} fileBuffer
- * @returns {Promise<{ ok: true } | { ok: false, error: string }>}
+ * @returns {Promise<{ ok: true } | { ok: false, error: string, retriable?: boolean }>}
  */
 export const uploadPreviewFileMultipart = async (
   apiBaseUrl,
@@ -249,6 +296,7 @@ export const uploadPreviewFileMultipart = async (
           Authorization: `Bearer ${apiKey}`,
         },
         body: formData,
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
       },
     );
 
@@ -257,6 +305,7 @@ export const uploadPreviewFileMultipart = async (
       return {
         ok: false,
         error: `Error subiendo ${relativePath}: ${response.status}${body ? ` — ${body}` : ""}`,
+        retriable: isRetriableStatus(response.status),
       };
     }
 
@@ -265,6 +314,7 @@ export const uploadPreviewFileMultipart = async (
     return {
       ok: false,
       error: `Error subiendo ${relativePath}: ${error.message}`,
+      retriable: true,
     };
   }
 };
@@ -277,7 +327,7 @@ export const uploadPreviewFileMultipart = async (
  * @param {number} storeId
  * @param {string} previewKey
  * @param {string} filePath
- * @returns {Promise<{ ok: true } | { ok: false, error: string }>}
+ * @returns {Promise<{ ok: true } | { ok: false, error: string, retriable?: boolean }>}
  */
 export const deletePreviewFile = async (
   apiBaseUrl,
@@ -302,6 +352,7 @@ export const deletePreviewFile = async (
       return {
         ok: false,
         error: `Error eliminando ${filePath}: ${response.status}${body ? ` — ${body}` : ""}`,
+        retriable: isRetriableStatus(response.status),
       };
     }
 
@@ -310,6 +361,7 @@ export const deletePreviewFile = async (
     return {
       ok: false,
       error: `Error eliminando ${filePath}: ${error.message}`,
+      retriable: true,
     };
   }
 };

package/lib/archive.mjs

@@ -0,0 +1,30 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { zipSync } from "fflate";
+import { listFilesRecursive } from "./fs-utils.mjs";
+
+/**
+ * @param {string} rootDir
+ * @returns {Promise<string[]>}
+ */
+export const listAllFiles = async (rootDir) => listFilesRecursive(rootDir);
+
+/**
+ * @param {string} rootDir
+ * @returns {Promise<Buffer>}
+ */
+export const createZipFromDirectory = async (rootDir) => {
+  const absoluteFiles = await listAllFiles(rootDir);
+  /** @type {Record<string, Uint8Array>} */
+  const entries = {};
+
+  for (const absolutePath of absoluteFiles) {
+    const relativePath = path
+      .relative(rootDir, absolutePath)
+      .split(path.sep)
+      .join("/");
+    entries[relativePath] = new Uint8Array(await readFile(absolutePath));
+  }
+
+  return Buffer.from(zipSync(entries, { level: 6 }));
+};