tiendu 0.8.1 → 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,8 @@ 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.
 
 ---
 
@@ -116,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
 ```
 
 ---
@@ -138,10 +142,13 @@ Builds or stages the current theme into its deployable output directory (`dist/`
 
 ```bash
 tiendu build
-tiendu build --skip-instances
+tiendu build --override-state
 ```
 
-- Use `--skip-instances` to omit template JSON, section group JSON, and `config/settings_data.json` from `dist/`. This is useful when you want to preserve the existing page/section instances on the preview.
+- By default, `build` omits editor-managed state files from `dist/`.
+- Use `--override-state` to include template JSON, section group JSON, and `config/settings_data.json` in `dist/`.
+- `--include-instances` is still accepted as a deprecated alias for `--override-state`.
+- `--skip-instances` is still accepted as a deprecated alias for the default preserve behavior.
 
 The build:
 
@@ -170,15 +177,15 @@ The main development command.
 
 ```bash
 tiendu dev
-tiendu dev --skip-instances
+tiendu dev --override-state
 ```
 
-- Use `--skip-instances` to sync everything except template JSON, section group JSON, and `config/settings_data.json`. Existing instances on the preview are preserved.
+- By default, `dev` preserves template JSON, section group JSON, and `config/settings_data.json` on the preview so theme editor changes are not overwritten.
+- Use `--override-state` to sync those state files from your local project too.
 - 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
 
@@ -195,10 +202,11 @@ Zips and uploads `dist/` to the active preview, replacing its content entirely.
 tiendu push
 tiendu push --skip-build
 tiendu push --skip-build --non-interactive
-tiendu push --skip-instances
+tiendu push --override-state
 ```
 
-- Use `--skip-instances` to upload everything except template JSON, section group JSON, and `config/settings_data.json`. Existing instances on the preview are preserved.
+- By default, `push` uploads code/assets while preserving editor-managed state on the preview.
+- Use `--override-state` to upload local template JSON, section group JSON, and `config/settings_data.json`.
 
 ---
 
@@ -213,13 +221,28 @@ Publishes the active preview to the live storefront. Visitors will see the new t
 tiendu publish
 tiendu publish --skip-build
 tiendu publish --skip-build --non-interactive
-tiendu publish --skip-instances
+tiendu publish --override-state
 ```
 
-- Use `--skip-instances` to publish everything except template JSON, section group JSON, and `config/settings_data.json`. Existing instances on the preview are preserved.
+- By default, `publish` syncs code/assets before publishing while preserving editor-managed state.
+- Use `--override-state` to publish local template JSON, section group JSON, and `config/settings_data.json`.
 
 In non-interactive mode, the publish confirmation is skipped.
 
+### State sync defaults
+
+You can set the default for a project in `tiendu.config.json`:
+
+```json
+{
+  "sync": {
+    "state": false
+  }
+}
+```
+
+Use `true` when local state JSON files should override editor state by default.
+
 ---
 
 ### `tiendu check-updates`

package/bin/tiendu.js

@@ -21,22 +21,26 @@ import {
   checkForUpdatesNow,
   getCurrentVersion,
 } from "../lib/update-check.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 build                 Build or stage the current theme into dist/
-  tiendu push [previewKey] [--skip-build]
+  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]
                                Upload dist/ to the attached or specified preview
-  tiendu dev                   Start dev mode: auto-sync changes to a live preview URL
-  tiendu publish [previewKey] [--skip-build]
+  tiendu dev [--override-state]
+                               Start dev mode: auto-sync changes to a live preview URL
+  tiendu publish [previewKey] [--skip-build] [--override-state]
                                Build/sync dist/ and publish the preview live
 
   tiendu preview               Show the attached preview details
@@ -54,8 +58,15 @@ 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
-  --skip-instances             Skip template/section group JSON and settings_data.json (preserves existing instances on the preview)
+  --override-state             Sync local theme state JSON and override editor state
+  --preserve-state             Preserve editor-managed state JSON (default)
+  --include-instances          Deprecated alias for --override-state
+  --skip-instances             Deprecated alias for --preserve-state
   --help, -h                   Show this help message
   --version, -v                Show the current CLI version
 
@@ -63,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
@@ -78,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.
@@ -88,6 +103,13 @@ Pipeline behavior:
   pipeline.postcss enables PostCSS for compiled style entries.
   With no config file, or with no enabled pipeline steps, build just stages theme files into dist/.
 
+Theme state behavior:
+  By default, the CLI preserves editor-managed state files: templates/*.json,
+  sections/*.json, and config/settings_data.json.
+  Use --override-state when your local state JSON should overwrite preview/editor state.
+  In tiendu.config.json, set { "sync": { "state": true } } to make local
+  state JSON the project default, or false to keep the safe default explicit.
+
 Typical workflow:
   tiendu init                  Connect to Tiendu and save your credentials
   tiendu stores list           See available stores
@@ -110,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;
     }
@@ -133,7 +155,12 @@ const main = async () => {
   const command = positionals[0];
   const subcommand = positionals[1];
   const skipBuild = flags.has("--skip-build");
-  const skipInstances = flags.has("--skip-instances");
+  const overrideStateFlag =
+    flags.has("--override-state") || flags.has("--include-instances");
+  const preserveStateFlag =
+    flags.has("--preserve-state") ||
+    flags.has("--preserve-instances") ||
+    flags.has("--skip-instances");
   const nonInteractive =
     flags.has("--non-interactive") || !process.stdin.isTTY || !process.stdout.isTTY;
 
@@ -164,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;
   }
@@ -187,28 +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 result = await build({ skipInstances });
+    const overrideState = await resolveOverrideState({
+      overrideStateFlag,
+      preserveStateFlag,
+    });
+    const result = await build({ overrideState });
     if (!result.ok) process.exit(1);
     return;
   }
 
   if (command === "push") {
-    await push({ skipBuild, previewKey: positionals[1], skipInstances });
+    const overrideState = await resolveOverrideState({
+      overrideStateFlag,
+      preserveStateFlag,
+    });
+    await push({ skipBuild, previewKey: positionals[1], overrideState });
     return;
   }
 
   if (command === "dev") {
-    await dev({ skipInstances });
+    const overrideState = await resolveOverrideState({
+      overrideStateFlag,
+      preserveStateFlag,
+    });
+    await dev({ overrideState });
     return;
   }
 
   if (command === "publish") {
-    await publish({ skipBuild, previewKey: positionals[1], skipInstances });
+    const overrideState = await resolveOverrideState({
+      overrideStateFlag,
+      preserveStateFlag,
+    });
+    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, skipInstances = false) => {
+const shouldCopyThemeSourceFile = (sourceRelativePath, outputRelativePath, overrideState = false) => {
   const extension = path.extname(sourceRelativePath).toLowerCase();
   if (ENTRY_SOURCE_EXTENSIONS.has(extension)) return false;
-  if (skipInstances && isInstanceFile(outputRelativePath)) return false;
+  if (!overrideState && isInstanceFile(outputRelativePath)) return false;
   return true;
 };
 
@@ -165,7 +165,7 @@ const copyThemeFiles = async (
   distDir,
   themeSourceDirs,
   knownAssetLogicalPaths,
-  skipInstances = 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, skipInstances)) 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, skipInstances = 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, skipInstances = false }
     distDir,
     themeSourceDirs,
     knownAssetLogicalPaths,
-    skipInstances,
+    overrideState,
   );
 
   if (cssCount > 0 && pipeline.postcss) {
@@ -512,7 +512,7 @@ export const build = async ({ watch: watchMode = false, skipInstances = false }
         const timer = setTimeout(async () => {
           debounceMap.delete(sourceRelativePath);
           try {
-            if (!shouldCopyThemeSourceFile(sourceRelativePath, outputRelativePath, skipInstances)) {
+            if (!shouldCopyThemeSourceFile(sourceRelativePath, outputRelativePath, overrideState)) {
               return;
             }
 

package/lib/config.mjs

@@ -10,7 +10,8 @@ const THEME_CONFIG_FILE = "tiendu.config.json";
  * @typedef {{ storeId?: number, apiBaseUrl: string, previewKey?: string }} TienduConfig
  * @typedef {{ apiKey: string }} TienduCredentials
  * @typedef {{ compileScripts: boolean, compileStyles: boolean, postcss: boolean }} TienduPipelineConfig
- * @typedef {{ pipeline?: Partial<TienduPipelineConfig> }} TienduThemeConfig
+ * @typedef {{ state?: boolean, instances?: "preserve" | "include" }} TienduSyncConfig
+ * @typedef {{ pipeline?: Partial<TienduPipelineConfig>, sync?: TienduSyncConfig, preserveInstances?: boolean }} TienduThemeConfig
  */
 
 const getConfigDir = () => path.resolve(process.cwd(), CONFIG_DIR);
@@ -41,6 +42,35 @@ const validateThemeConfig = (themeConfig) => {
     }
   }
 
+  if (themeConfig.sync !== undefined && !isPlainObject(themeConfig.sync)) {
+    throw new Error('tiendu.config.json: "sync" must be an object.');
+  }
+
+  if (
+    themeConfig.sync?.state !== undefined &&
+    typeof themeConfig.sync.state !== "boolean"
+  ) {
+    throw new Error('tiendu.config.json: "sync.state" must be true or false.');
+  }
+
+  if (
+    themeConfig.sync?.instances !== undefined &&
+    !["preserve", "include"].includes(themeConfig.sync.instances)
+  ) {
+    throw new Error(
+      'tiendu.config.json: "sync.instances" must be "preserve" or "include".',
+    );
+  }
+
+  if (
+    themeConfig.preserveInstances !== undefined &&
+    typeof themeConfig.preserveInstances !== "boolean"
+  ) {
+    throw new Error(
+      'tiendu.config.json: "preserveInstances" must be true or false.',
+    );
+  }
+
   return themeConfig;
 };
 
@@ -119,6 +149,38 @@ export const getThemePipelineConfig = (themeConfig) => ({
 export const readThemePipelineConfig = async () =>
   getThemePipelineConfig(await readThemeConfig());
 
+/**
+ * @param {TienduThemeConfig | null} themeConfig
+ * @returns {boolean}
+ */
+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;
+  if (themeConfig?.preserveInstances === false) return true;
+  return false;
+};
+
+/**
+ * @param {{ overrideStateFlag?: boolean, preserveStateFlag?: boolean }} [options]
+ * @returns {Promise<boolean>}
+ */
+export const resolveOverrideState = async ({
+  overrideStateFlag = false,
+  preserveStateFlag = false,
+} = {}) => {
+  if (overrideStateFlag && preserveStateFlag) {
+    throw new Error(
+      "Use either --override-state or --preserve-state, not both.",
+    );
+  }
+
+  if (overrideStateFlag) return true;
+  if (preserveStateFlag) return false;
+
+  return getThemeOverrideStateConfig(await readThemeConfig());
+};
+
 /** @returns {string} */
 export const getDistDir = () => path.resolve(process.cwd(), "dist");
 

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 ({ skipInstances = 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, skipInstances });
+  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 ({ skipInstances = 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 ({ skipInstances = 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 ({ skipInstances = false } = {}) => {
     compressMessage: "Compressing files...",
     retryMessage: (result, nextAttempt) =>
       `Initial push failed. Retrying ${nextAttempt}/${RETRY_ATTEMPTS}... ${result.error}`,
-    skipInstances,
+    overrideState,
   });
 
   if (!uploadResult.ok) {
@@ -170,20 +167,14 @@ export const dev = async ({ skipInstances = 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 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.");
 
@@ -236,8 +227,6 @@ export const dev = async ({ skipInstances = false } = {}) => {
 
           if (!result.ok) {
             ui.log.warn(`     Failed to delete after ${RETRY_ATTEMPTS} attempts: ${result.error}`);
-          } else {
-            localPreviewServer?.notifyReload();
           }
         }
 
@@ -269,8 +258,6 @@ export const dev = async ({ skipInstances = 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}`);
@@ -289,7 +276,7 @@ export const dev = async ({ skipInstances = false } = {}) => {
     if (shouldIgnoreWatchedPath(filename, true)) return;
 
     const relativePath = filename.split(path.sep).join("/");
-    if (skipInstances && isInstanceFile(relativePath)) return;
+    if (!overrideState && isInstanceFile(relativePath)) return;
     queueSync(relativePath);
   });
 
@@ -301,7 +288,6 @@ export const dev = async ({ skipInstances = 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.");