tiendu 0.8.1 → 0.8.2

package/README.md

@@ -69,6 +69,8 @@ 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.
+
 ---
 
 ## Commands
@@ -138,10 +140,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,10 +175,11 @@ 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
@@ -195,10 +201,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 +220,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,6 +21,7 @@ import {
   checkForUpdatesNow,
   getCurrentVersion,
 } from "../lib/update-check.mjs";
+import { resolveIncludeInstances } from "../lib/config.mjs";
 import { configureUi } from "../lib/ui.mjs";
 
 const HELP = `
@@ -32,11 +33,13 @@ Usage:
   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 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
@@ -55,7 +58,10 @@ Global options:
   --non-interactive            Disable prompts, print plain text output, and skip confirmations
   --dir <path>                 Create the project inside a new directory during init
   --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
 
@@ -88,6 +94,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
@@ -133,7 +146,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;
 
@@ -192,23 +210,39 @@ const main = async () => {
   }
 
   if (command === "build") {
-    const result = await build({ skipInstances });
+    const includeInstances = await resolveIncludeInstances({
+      overrideStateFlag,
+      preserveStateFlag,
+    });
+    const result = await build({ includeInstances });
     if (!result.ok) process.exit(1);
     return;
   }
 
   if (command === "push") {
-    await push({ skipBuild, previewKey: positionals[1], skipInstances });
+    const includeInstances = await resolveIncludeInstances({
+      overrideStateFlag,
+      preserveStateFlag,
+    });
+    await push({ skipBuild, previewKey: positionals[1], includeInstances });
     return;
   }
 
   if (command === "dev") {
-    await dev({ skipInstances });
+    const includeInstances = await resolveIncludeInstances({
+      overrideStateFlag,
+      preserveStateFlag,
+    });
+    await dev({ includeInstances });
     return;
   }
 
   if (command === "publish") {
-    await publish({ skipBuild, previewKey: positionals[1], skipInstances });
+    const includeInstances = await resolveIncludeInstances({
+      overrideStateFlag,
+      preserveStateFlag,
+    });
+    await publish({ skipBuild, previewKey: positionals[1], includeInstances });
     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, includeInstances = false) => {
   const extension = path.extname(sourceRelativePath).toLowerCase();
   if (ENTRY_SOURCE_EXTENSIONS.has(extension)) return false;
-  if (skipInstances && isInstanceFile(outputRelativePath)) return false;
+  if (!includeInstances && isInstanceFile(outputRelativePath)) return false;
   return true;
 };
 
@@ -165,7 +165,7 @@ const copyThemeFiles = async (
   distDir,
   themeSourceDirs,
   knownAssetLogicalPaths,
-  skipInstances = false,
+  includeInstances = 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, includeInstances)) 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, includeInstances = 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,
+    includeInstances,
   );
 
   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, includeInstances)) {
               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 getThemeIncludeInstancesConfig = (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 resolveIncludeInstances = 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 getThemeIncludeInstancesConfig(await readThemeConfig());
+};
+
 /** @returns {string} */
 export const getDistDir = () => path.resolve(process.cwd(), "dist");
 

package/lib/dev.mjs

@@ -115,7 +115,7 @@ const deleteFileWithRetries = (
     },
   );
 
-export const dev = async ({ skipInstances = false } = {}) => {
+export const dev = async ({ includeInstances = false } = {}) => {
   const { config, credentials } = await loadConfigOrFail();
   const { apiBaseUrl, storeId } = config;
   const { apiKey } = credentials;
@@ -123,7 +123,7 @@ export const dev = async ({ skipInstances = false } = {}) => {
   let buildCleanup = null;
   let localPreviewServer = null;
 
-  const buildResult = await build({ watch: true, skipInstances });
+  const buildResult = await build({ watch: true, includeInstances });
   if (!buildResult.ok) {
     ui.log.error("Initial build failed. Fix errors and try again.");
     process.exit(1);
@@ -161,7 +161,7 @@ export const dev = async ({ skipInstances = false } = {}) => {
     compressMessage: "Compressing files...",
     retryMessage: (result, nextAttempt) =>
       `Initial push failed. Retrying ${nextAttempt}/${RETRY_ATTEMPTS}... ${result.error}`,
-    skipInstances,
+    includeInstances,
   });
 
   if (!uploadResult.ok) {
@@ -184,6 +184,9 @@ export const dev = async ({ skipInstances = false } = {}) => {
     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"}`,
+  );
 
   ui.log.message("Watching for changes - press Ctrl+C to stop.");
 
@@ -289,7 +292,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 (!includeInstances && isInstanceFile(relativePath)) return;
     queueSync(relativePath);
   });
 

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, skipInstances = false } = {}) => {
+export const publish = async ({ skipBuild = false, previewKey: previewKeyArg, includeInstances = 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, sk
       ? "Syncing existing dist/ output to the preview before publishing..."
       : "Building and syncing the latest dist/ output before publishing...",
   );
-  await push({ skipBuild, previewKey, skipInstances });
+  await push({ skipBuild, previewKey, includeInstances });
 
   const spinner = ui.spinner();
   spinner.start("Publishing preview to live storefront...");

package/lib/push.mjs

@@ -26,11 +26,11 @@ export const pushPreparedDirectoryToPreview = async ({
   compressMessage = "Compressing files...",
   uploadMessage,
   retryMessage,
-  skipInstances = false,
+  includeInstances = false,
 }) => {
   spinner.message(compressMessage);
 
-  const shouldInclude = skipInstances
+  const shouldInclude = !includeInstances
     ? (relativePath) => !isInstanceFile(relativePath)
     : undefined;
 
@@ -40,7 +40,7 @@ export const pushPreparedDirectoryToPreview = async ({
   );
 
   return retryAsync(
-    () => uploadPreviewZip(apiBaseUrl, apiKey, storeId, previewKey, zipBuffer, skipInstances),
+    () => uploadPreviewZip(apiBaseUrl, apiKey, storeId, previewKey, zipBuffer, !includeInstances),
     {
       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, skipInstances = false } = {}) => {
+export const push = async ({ skipBuild = false, previewKey: previewKeyArg, includeInstances = false } = {}) => {
   const { config, credentials } = await loadConfigOrFail();
 
   if (!skipBuild) {
-    const result = await build({ skipInstances });
+    const result = await build({ includeInstances });
     if (!result.ok) {
       process.exit(1);
     }
@@ -89,7 +89,7 @@ export const push = async ({ skipBuild = false, previewKey: previewKeyArg, skipI
     previewKey,
     rootDir,
     spinner,
-    skipInstances,
+    includeInstances,
   });
 
   if (!result.ok) {
@@ -99,5 +99,8 @@ export const push = async ({ skipBuild = false, previewKey: previewKeyArg, skipI
   }
 
   spinner.stop(`Files uploaded to preview ${previewKey}.`);
+  ui.log.message(
+    `Theme state: ${includeInstances ? "overridden from local files" : "preserved from the theme editor"}`,
+  );
   ui.log.message(`  ${previewDetails.data.url}`);
 };

package/package.json

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