tiendu 0.6.1 → 0.8.0

package/README.md

@@ -24,16 +24,18 @@ npm install -g tiendu
 
 ## Quick start
 
-### Buildless theme (simple)
+### Simple theme
 
 ```bash
 mkdir my-theme && cd my-theme
 tiendu init
+tiendu stores list
+tiendu stores set <store-id>
 tiendu pull
 tiendu dev
 ```
 
-### Built theme (TypeScript, npm packages, bundling)
+### Pipeline-enabled theme
 
 Clone the default theme template, connect to your store, and start developing:
 
@@ -41,10 +43,22 @@ Clone the default theme template, connect to your store, and start developing:
 git clone <default-theme-repo> my-theme && cd my-theme
 npm install
 tiendu init
+tiendu stores list
+tiendu stores set <store-id>
 tiendu dev
 ```
 
-`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:
+### Agent-friendly setup
+
+```bash
+tiendu init <api-key> [base-url] --non-interactive
+tiendu stores list --non-interactive
+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:
 
 ```
 http://preview-xxxxxxxxxxxx.tiendu.uy/
@@ -59,24 +73,54 @@ It also starts a local live-preview URL that proxies the preview and auto-reload
 
 ## Commands
 
-### `tiendu init`
+### `tiendu init [apiKey] [baseUrl]`
+
+Initializes a theme project in the current directory.
 
-Initializes a theme project in the current directory. Prompts for your API key, API base URL (defaults to `https://tiendu.uy`), and store ID. Saves configuration to `.cli/`.
+- With no arguments, it runs the interactive setup wizard.
+- With `apiKey` and optional `baseUrl`, it reinitializes the saved config without prompts.
+- If only one store is available, it is selected automatically.
+- If multiple stores are available, leave the store unset and use `tiendu stores list` plus `tiendu stores set <id>`.
 
 ```bash
 tiendu init
+tiendu init <api-key>
+tiendu init <api-key> https://tiendu.uy --non-interactive
 ```
 
 > Add `.cli/` to your `.gitignore` if you version-control your theme — it contains your API key.
 
 ---
 
+### `tiendu stores list`
+
+Lists all stores available for the configured API key and highlights the active one when present.
+
+```bash
+tiendu stores list
+tiendu stores list --non-interactive
+```
+
+---
+
+### `tiendu stores set <storeId>`
+
+Validates the store against the configured API key and saves it as the active store.
+
+```bash
+tiendu stores set 123
+tiendu stores set 123 --non-interactive
+```
+
+---
+
 ### `tiendu pull`
 
-Downloads the current live theme from your store as local files.
+Downloads the current live theme from your store into `dist/`.
 
-- **Buildless themes:** extracts to the current directory.
-- **Built themes** (with `tiendu.config.json`): extracts to `dist/`.
+- `pull` clears `dist/` first.
+- The downloaded archive is then extracted into `dist/`.
+- Your source files, including `src/`, are left untouched.
 
 ```bash
 tiendu pull
@@ -86,19 +130,26 @@ tiendu pull
 
 ### `tiendu build`
 
-Builds a theme into its deployable output directory (`dist/`). Only available for built themes (requires `tiendu.config.json`).
+Builds or stages the current theme into its deployable output directory (`dist/`).
+
+- Theme files and assets are always prepared into `dist/`.
+- Optional pipeline steps are enabled through `tiendu.config.json`.
+- With no config file, or with no enabled pipeline steps, `build` just stages the theme files into `dist/`.
 
 ```bash
 tiendu build
+tiendu build --skip-instances
 ```
 
+- 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.
+
 The build:
 
-1. Copies theme files from `src/layout/`, `src/templates/`, and `src/snippets/` to `dist/`
+1. Copies theme files from `src/layout/`, `src/templates/`, `src/sections/`, `src/blocks/`, `src/snippets/`, and `src/config/` 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)
+3. Optionally discovers script and style entry points in `src/layout/` and `src/templates/`
+4. Optionally compiles JS/TS and CSS into `dist/assets/`
+5. Optionally runs project PostCSS plugins for compiled CSS entries
 
 For TypeScript source, extensionless relative imports such as `import { initHeaderCart } from '../lib/scripts/cart'` are supported and recommended.
 
@@ -114,13 +165,15 @@ Entry naming convention:
 
 The main development command.
 
-- **Buildless themes:** watches the current directory and syncs file changes to the preview.
-- **Built themes:** runs `tiendu build` in watch mode first, then watches `dist/` and syncs changes to the preview.
+- Runs `tiendu build` in watch mode first.
+- Watches `dist/` and syncs changes to the preview.
 
 ```bash
 tiendu dev
+tiendu dev --skip-instances
 ```
 
+- Use `--skip-instances` to sync everything except template JSON, section group JSON, and `config/settings_data.json`. Existing instances on the preview are preserved.
 - Prints the preview URL on start
 - Re-syncs the full local theme to the preview on startup
 - Syncs file creates, edits and deletes
@@ -133,17 +186,19 @@ tiendu dev
 
 ### `tiendu push`
 
-Zips and uploads files to the active preview, replacing its content entirely.
+Zips and uploads `dist/` to the active preview, replacing its content entirely.
 
-- **Buildless themes:** uploads from the current directory.
-- **Built themes:** runs `tiendu build` first, then uploads from `dist/`.
+- By default it runs `tiendu build` first.
+- Use `--skip-build` to upload the existing `dist/` artifact without rebuilding.
 
 ```bash
 tiendu push
 tiendu push --skip-build
+tiendu push --skip-build --non-interactive
+tiendu push --skip-instances
 ```
 
-Use `--skip-build` to upload the existing `dist/` output without rebuilding.
+- Use `--skip-instances` to upload everything except template JSON, section group JSON, and `config/settings_data.json`. Existing instances on the preview are preserved.
 
 ---
 
@@ -151,15 +206,19 @@ Use `--skip-build` to upload the existing `dist/` output without rebuilding.
 
 Publishes the active preview to the live storefront. Visitors will see the new theme immediately. All previews for the store are removed after publishing.
 
-- **Buildless themes:** publishes the active preview as-is.
-- **Built themes:** builds the theme, uploads the latest `dist/` output to the preview, then publishes it.
+- By default it runs `tiendu build`, uploads `dist/` to the preview, and then publishes it.
+- Use `--skip-build` to publish after syncing the existing `dist/` output.
 
 ```bash
 tiendu publish
 tiendu publish --skip-build
+tiendu publish --skip-build --non-interactive
+tiendu publish --skip-instances
 ```
 
-Use `--skip-build` to publish after uploading the existing `dist/` output without rebuilding.
+- Use `--skip-instances` to publish everything except template JSON, section group JSON, and `config/settings_data.json`. Existing instances on the preview are preserved.
+
+In non-interactive mode, the publish confirmation is skipped.
 
 ---
 
@@ -211,6 +270,7 @@ Deletes the active preview (both remotely and from your local config).
 
 ```bash
 tiendu preview delete
+tiendu preview delete --non-interactive
 ```
 
 ---
@@ -227,23 +287,27 @@ tiendu preview open
 
 ## Typical workflow
 
-### Buildless
+### Standard
 
 ```
-tiendu init        # one time: connect to your store
-tiendu pull        # one time: download the live theme
+tiendu init        # one time: connect to your Tiendu account
+tiendu stores list # one time: see available stores
+tiendu stores set  # one time: select the store to work on
+tiendu pull        # one time: refresh dist/ from the live theme
 
-tiendu dev         # develop: edit locally, see changes live at the preview URL
+tiendu dev         # develop: build/stage into dist/, sync preview updates live
 
 tiendu publish     # when ready: push to the live storefront
 ```
 
-### Built theme
+### Pipeline-enabled
 
 ```
 git clone <template-repo> my-theme
 cd my-theme && npm install
-tiendu init        # one time: connect to your store
+tiendu init        # one time: connect to your Tiendu account
+tiendu stores list # one time: see available stores
+tiendu stores set  # one time: select the store to work on
 
 tiendu dev         # develop: builds src/, watches dist/, syncs to preview
 
@@ -264,9 +328,13 @@ A **theme preview** is a remote copy of your theme hosted by Tiendu. It renders
 
 ---
 
-## Built themes
+## Pipeline-enabled themes
+
+All themes are staged into `dist/` before upload.
 
-A **built theme** is a theme that uses `tiendu.config.json` to enable the build pipeline. It allows:
+`tiendu.config.json` can optionally enable extra pipeline steps such as script compilation, style compilation, and PostCSS processing.
+
+When pipeline steps are enabled, a theme can use:
 
 - npm packages via a local `package.json`
 - TypeScript (`.ts`) for browser code
@@ -277,7 +345,7 @@ A **built theme** is a theme that uses `tiendu.config.json` to enable the build
 
 ```
 my-theme/
-├── tiendu.config.json    # marks this as a built theme
+├── tiendu.config.json    # optional pipeline flags
 ├── package.json          # npm dependencies
 ├── .gitignore
 ├── src/
@@ -293,21 +361,21 @@ my-theme/
 │   ├── assets/           # source assets → flattened into dist/assets/
 │   ├── lib/              # shared modules (bundled into entries, not served)
 │   └── css/              # shared CSS (imported by entry CSS)
-└── dist/                 # build output (gitignored, uploaded to Tiendu)
+└── dist/                 # staged upload artifact (gitignored, uploaded to Tiendu)
 ```
 
 ### How it works
 
-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/`
+1. Theme files and static assets are staged into `dist/`
+2. Script entries are compiled only when `pipeline.compileScripts` is enabled
+3. Style entries are compiled only when `pipeline.compileStyles` is enabled
+4. PostCSS runs only when `pipeline.postcss` is enabled
 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 }}`)
+6. Liquid templates reference bundles and assets via `asset_url` when compiled entries are used
 
 ### Tailwind v4
 
-Built themes can use Tailwind v4 in CSS entry files.
+Pipeline-enabled themes can use Tailwind v4 in CSS entry files when `pipeline.compileStyles` and `pipeline.postcss` are enabled.
 
 Install it in your theme project:
 
@@ -338,15 +406,22 @@ export default {
 
 ### tiendu.config.json
 
-Minimal config — the build conventions are hardcoded:
+Config is optional. When present, you can enable pipeline steps explicitly:
 
 ```json
 {
-  "name": "my-theme",
-  "version": "1.0.0"
+  "pipeline": {
+    "compileScripts": true,
+    "compileStyles": true,
+    "postcss": true
+  }
 }
 ```
 
+Without enabled pipeline steps, the CLI still stages the theme into `dist/`, but it skips compilation and PostCSS.
+
+With no `tiendu.config.json`, the behavior is the same as having all pipeline steps disabled.
+
 ---
 
 ## License

package/bin/tiendu.js

@@ -15,80 +15,140 @@ import {
   previewAttach,
   previewDetach,
 } from "../lib/preview.mjs";
+import { storesList, storesSet } from "../lib/stores.mjs";
 import {
   checkForUpdates,
   checkForUpdatesNow,
   getCurrentVersion,
 } from "../lib/update-check.mjs";
+import { configureUi } from "../lib/ui.mjs";
 
 const HELP = `
 tiendu — Tiendu theme development CLI
 
 Usage:
-  tiendu init [dir]          Set up a theme project (optionally in a new directory)
-  tiendu pull [previewKey]   Download the live theme, or a specific preview's files
-  tiendu build               Build a theme (requires tiendu.config.json)
+  tiendu init [apiKey] [baseUrl] [--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]
-                              Upload files to the attached or specified preview
-  tiendu dev                 Start dev mode: auto-sync changes to a live preview URL
+                               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]
-                              Publish the attached or specified preview to the live storefront
+                               Build/sync dist/ and publish the preview live
 
-  tiendu preview             Show the attached preview details
+  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
+                               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 check-updates         Check npm for a newer CLI version
+  tiendu version               Show the current CLI version
 
-  tiendu --help, -h          Show this help message
-  tiendu --version, -v       Show the current CLI version
+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)
+  --help, -h                   Show this help message
+  --version, -v                Show the current CLI version
+
+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
+  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>.
+
+Agent-friendly setup:
+  tiendu init <apiKey> [baseUrl] --non-interactive
+  tiendu stores list --non-interactive
+  tiendu stores set <id> --non-interactive
+  tiendu pull --non-interactive
+  tiendu push --non-interactive
+  tiendu publish --non-interactive
+
+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.
+
+Pipeline behavior:
+  tiendu.config.json can enable optional pipeline steps.
+  pipeline.compileScripts enables JS/TS entry compilation.
+  pipeline.compileStyles enables CSS entry compilation.
+  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/.
 
 Typical workflow:
-  tiendu init my-store       Set up a new project in ./my-store
-  cd my-store
-  tiendu pull                Download the current live theme
-  tiendu build               Build the theme (for themes with tiendu.config.json)
-  tiendu dev                 Edit locally — preview updates in real time
-  tiendu publish             Ship to the live storefront when ready
+  tiendu init                  Connect to Tiendu and save your credentials
+  tiendu stores list           See available stores
+  tiendu stores set <id>       Select the store you want to work on
+  tiendu pull                  Refresh dist/ from the current live theme
+  tiendu dev                   Edit locally — preview updates in real time
+  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 parseArgv = (argv) => {
+  const flags = new Set();
+  const values = new Map();
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+
+    if (arg === "--dir") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("--")) {
+        console.error("Missing value for --dir.");
+        process.exit(1);
+      }
+      values.set("dir", value);
+      index += 1;
+      continue;
+    }
+
+    flags.add(arg);
+  }
+
+  return { flags, values, positionals };
+};
 
 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");
+  const argv = process.argv.slice(2);
+  const { flags, values, positionals } = parseArgv(argv);
+  const command = positionals[0];
+  const subcommand = positionals[1];
+  const skipBuild = flags.has("--skip-build");
+  const skipInstances = flags.has("--skip-instances");
+  const nonInteractive =
+    flags.has("--non-interactive") || !process.stdin.isTTY || !process.stdout.isTTY;
+
+  configureUi({ nonInteractive });
 
   if (
     command === "version" ||
-    command === "--version" ||
-    command === "-v"
+    argv.includes("--version") ||
+    argv.includes("-v")
   ) {
     console.log(getCurrentVersion());
     process.exit(0);
   }
 
-  if (
-    !command ||
-    command === "--help" ||
-    command === "-h"
-  ) {
+  if (!command || argv.includes("--help") || argv.includes("-h")) {
     console.log(HELP.trim());
     process.exit(0);
   }
@@ -98,40 +158,57 @@ const main = async () => {
     return;
   }
 
-  // Check for updates at most once per day (non-blocking)
   await checkForUpdates();
 
   if (command === "init") {
-    await init(args[1]); // optional directory name
+    const initArgs = positionals.slice(1);
+    await init({
+      dirArg: values.get("dir"),
+      apiKeyArg: initArgs[0],
+      baseUrlArg: initArgs[1],
+    });
     return;
   }
 
+  if (command === "stores") {
+    if (subcommand === "list") {
+      await storesList();
+      return;
+    }
+
+    if (subcommand === "set") {
+      await storesSet(positionals[2]);
+      return;
+    }
+
+    console.error(`Unknown subcommand: stores ${subcommand ?? "(none)"}`);
+    console.log(HELP.trim());
+    process.exit(1);
+  }
+
   if (command === "pull") {
-    const previewKey = extractPositionalArg(restArgs);
-    await pull({ previewKey });
+    await pull({ previewKey: positionals[1] });
     return;
   }
 
   if (command === "build") {
-    const result = await build();
+    const result = await build({ skipInstances });
     if (!result.ok) process.exit(1);
     return;
   }
 
   if (command === "push") {
-    const previewKey = extractPositionalArg(restArgs);
-    await push({ skipBuild, previewKey });
+    await push({ skipBuild, previewKey: positionals[1], skipInstances });
     return;
   }
 
   if (command === "dev") {
-    await dev();
+    await dev({ skipInstances });
     return;
   }
 
   if (command === "publish") {
-    const previewKey = extractPositionalArg(restArgs);
-    await publish({ skipBuild, previewKey });
+    await publish({ skipBuild, previewKey: positionals[1], skipInstances });
     return;
   }
 
@@ -141,7 +218,7 @@ const main = async () => {
       return;
     }
     if (subcommand === "create") {
-      await previewCreate(args[2]);
+      await previewCreate(positionals[2]);
       return;
     }
     if (subcommand === "list") {
@@ -149,7 +226,7 @@ const main = async () => {
       return;
     }
     if (subcommand === "attach") {
-      await previewAttach(args[2]);
+      await previewAttach(positionals[2]);
       return;
     }
     if (subcommand === "detach") {
@@ -157,7 +234,7 @@ const main = async () => {
       return;
     }
     if (subcommand === "delete") {
-      await previewDelete(args[2]);
+      await previewDelete(positionals[2]);
       return;
     }
     if (subcommand === "open") {

package/lib/api.mjs

@@ -219,23 +219,25 @@ export const downloadPreviewArchive = async (
  * @returns {Promise<{ ok: true } | { ok: false, error: string, retriable?: boolean }>}
  */
 export const uploadPreviewZip = async (
-  apiBaseUrl,
-  apiKey,
-  storeId,
-  previewKey,
-  zipBuffer,
+	apiBaseUrl,
+	apiKey,
+	storeId,
+	previewKey,
+	zipBuffer,
+	preserveInstances = false,
 ) => {
-  try {
-    const response = await apiFetch(
-      apiBaseUrl,
-      apiKey,
-      `/api/admin/stores/${storeId}/theme-previews/${previewKey}/upload`,
-      {
-        method: "POST",
-        body: zipBuffer,
-        contentType: "application/zip",
-      },
-    );
+	try {
+		const query = preserveInstances ? "?preserveInstances=true" : "";
+		const response = await apiFetch(
+			apiBaseUrl,
+			apiKey,
+			`/api/admin/stores/${storeId}/theme-previews/${previewKey}/upload${query}`,
+			{
+				method: "POST",
+				body: zipBuffer,
+				contentType: "application/zip",
+			},
+		);
 
     if (!response.ok) {
       const body = await response.text().catch(() => "");

package/lib/archive.mjs

@@ -13,7 +13,7 @@ export const listAllFiles = async (rootDir) => listFilesRecursive(rootDir);
  * @param {string} rootDir
  * @returns {Promise<Buffer>}
  */
-export const createZipFromDirectory = async (rootDir) => {
+export const createZipFromDirectory = async (rootDir, shouldInclude) => {
   const absoluteFiles = await listAllFiles(rootDir);
   /** @type {Record<string, Uint8Array>} */
   const entries = {};
@@ -23,6 +23,7 @@ export const createZipFromDirectory = async (rootDir) => {
       .relative(rootDir, absolutePath)
       .split(path.sep)
       .join("/");
+    if (shouldInclude && !shouldInclude(relativePath)) continue;
     entries[relativePath] = new Uint8Array(await readFile(absolutePath));
   }