create-magic-storefront 0.3.1 → 0.4.0

package/README.md

@@ -17,7 +17,7 @@ npx create-magic-storefront check [directory]
 Fails (exit 1, one line per finding) when the storefront uses the SDK outside its public API:
 
 - `DEEP_IMPORT` — an `@magicstoreai/*` import other than `@magicstoreai/storefront-client`,
-  `@magicstoreai/hydrogen`, `@magicstoreai/hydrogen/core`, `/server` or `/seo` (a `src/` or `dist/`
+  `@magicstoreai/hydrogen`, `@magicstoreai/hydrogen/core`, `/server`, `/seo` or `/theme` (a `src/` or `dist/`
   path, an unexported subpath, the SDK's sources in this repository);
 - `RAW_API_CALL` — a string that spells out an endpoint (`/api/v2/storefront/…`) instead of calling
   it through the client. The bare base URL handed to `createStorefrontClient` is fine.
@@ -30,3 +30,20 @@ Fails (exit 1, one line per finding) when the storefront uses the SDK outside it
 
 `node_modules`, build output and `.d.ts` files are skipped. In this repository `pnpm guard` runs it on
 `examples/starter` (CI too).
+
+## Themes
+
+```bash
+npx create-magic-storefront theme check [directory]   # sections, templates, defaults, copy in components
+npx create-magic-storefront theme build [directory]   # the manifest → .magicstore/theme.json
+npx create-magic-storefront theme push [directory]    # send it to the shop (UNPUBLISHED; --publish to go live)
+npx create-magic-storefront theme dev [directory]     # push to DEVELOPMENT on every change under theme/
+```
+
+The theme is `theme/index.ts` (`defineTheme`) of the storefront and the files of `theme/sections/`, loaded
+with the storefront's own SDK. `check` fails on a section file that is not registered
+(`SECTION_NOT_REGISTERED`), an invalid template or a text setting without a default in every locale
+(`--locales`, default `en,ru,uz`); copy written into a component is a warning (`HARDCODED_COPY`), an error
+with `--strict`. `push` and `dev` need `MAGICSTORE_THEME_TOKEN` — the theme deploy token (`mtt_…`), never a
+storefront token — and `MAGICSTORE_SHOP_DOMAIN` or `MAGICSTORE_API_URL`, from the environment or
+`.env.local`; only the token's prefix is printed. Guide: [docs/themes.md](../../docs/themes.md).

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { dirname, relative as relative2, resolve as resolve3 } from "path";
+import { readFileSync as readFileSync5 } from "fs";
+import { dirname, relative as relative3, resolve as resolve6 } from "path";
 import { createInterface } from "readline/promises";
 import { fileURLToPath } from "url";
 import { parseArgs } from "util";
@@ -15,7 +15,8 @@ var PUBLIC_ENTRY_POINTS = [
   "@magicstoreai/hydrogen",
   "@magicstoreai/hydrogen/core",
   "@magicstoreai/hydrogen/server",
-  "@magicstoreai/hydrogen/seo"
+  "@magicstoreai/hydrogen/seo",
+  "@magicstoreai/hydrogen/theme"
 ];
 var SOURCE_EXTENSIONS = /\.(?:[cm]?[jt]sx?)$/;
 var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set([
@@ -175,21 +176,523 @@ function envFile(example, options) {
   }).join("\n");
 }
 
+// src/theme-commands.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync4, watch, writeFileSync as writeFileSync3 } from "fs";
+import { join as join5, resolve as resolve5 } from "path";
+
+// src/theme-check.ts
+import { readFileSync as readFileSync3 } from "fs";
+import { createRequire as createRequire2 } from "module";
+import { join as join4, resolve as resolve4 } from "path";
+
+// src/theme-load.ts
+import { existsSync as existsSync2, mkdirSync, readdirSync as readdirSync3, rmSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3, relative as relative2, resolve as resolve3 } from "path";
+import { createRequire } from "module";
+import { build } from "esbuild";
+var OUTPUT_DIRECTORY = ".magicstore";
+var THEME_ENTRY = "theme/index.ts";
+var SECTIONS_DIRECTORY = "theme/sections";
+var ThemeLoadError = class extends Error {
+  name = "ThemeLoadError";
+};
+var STUBBED_MODULES = ["server-only", "client-only"];
+var stubs = {
+  name: "magicstore-stubs",
+  setup(builder) {
+    const filter = new RegExp(`^(?:${STUBBED_MODULES.join("|")})$`);
+    builder.onResolve({ filter }, (args) => ({ path: args.path, namespace: "magicstore-stub" }));
+    builder.onLoad({ filter: /.*/, namespace: "magicstore-stub" }, () => ({ contents: "" }));
+  }
+};
+function sectionSourceFiles(directory) {
+  const sections = resolve3(directory, SECTIONS_DIRECTORY);
+  if (!existsSync2(sections)) {
+    return [];
+  }
+  return readdirSync3(sections, { withFileTypes: true }).filter((entry) => entry.isFile() && /\.[cm]?[jt]sx?$/.test(entry.name)).filter((entry) => !/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(entry.name)).map((entry) => join3(sections, entry.name)).sort();
+}
+async function loadProject(directory) {
+  const root = resolve3(directory);
+  const entry = resolve3(root, THEME_ENTRY);
+  if (!existsSync2(entry)) {
+    throw new ThemeLoadError(
+      `${THEME_ENTRY} not found in ${root}: a theme starts with defineTheme there.`
+    );
+  }
+  const files = sectionSourceFiles(root);
+  const lines = [
+    `import * as entry from ${JSON.stringify(entry)};`,
+    ...files.map((file, index) => `import * as s${index} from ${JSON.stringify(file)};`),
+    `export const theme = entry.default ?? entry.theme;`,
+    `export const sections = [${files.map((_, index) => `s${index}`).join(", ")}];`,
+    `export * as sdk from '@magicstoreai/hydrogen/theme';`,
+    `export * as client from '@magicstoreai/storefront-client';`
+  ];
+  const staging = resolve3(root, OUTPUT_DIRECTORY);
+  mkdirSync(staging, { recursive: true });
+  const bundlePath = join3(staging, `theme-loader-${process.pid}-${Date.now()}.cjs`);
+  try {
+    const result = await build({
+      stdin: {
+        contents: lines.join("\n"),
+        resolveDir: root,
+        loader: "ts",
+        sourcefile: "theme-loader.ts"
+      },
+      absWorkingDir: root,
+      bundle: true,
+      write: false,
+      platform: "node",
+      // CommonJS: Node's require resolves packages without an exports map (`next/link`), and loads
+      // ESM-only ones too (require(esm), Node 22.12+).
+      format: "cjs",
+      target: "node22",
+      jsx: "automatic",
+      packages: "external",
+      loader: { ".css": "empty" },
+      plugins: [stubs],
+      logLevel: "silent"
+    });
+    writeFileSync2(bundlePath, result.outputFiles[0].text);
+  } catch (error) {
+    const messages = error.errors;
+    const detail = messages ? messages.map((m) => m.location ? `${m.location.file}:${m.location.line}: ${m.text}` : m.text).join("\n") : String(error);
+    throw new ThemeLoadError(`The theme does not compile:
+${detail}`);
+  }
+  let loaded;
+  try {
+    const load = createRequire(bundlePath);
+    loaded = load(bundlePath);
+    delete load.cache[bundlePath];
+  } catch (error) {
+    throw new ThemeLoadError(
+      `Loading the theme failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  } finally {
+    rmSync(bundlePath, { force: true });
+  }
+  const theme2 = loaded.theme;
+  if (typeof theme2 !== "object" || theme2 === null || !Array.isArray(theme2.sections)) {
+    throw new ThemeLoadError(
+      `${THEME_ENTRY} must export the theme: \`export default defineTheme({ \u2026 })\`.`
+    );
+  }
+  const sectionFiles = files.map((file, index) => ({
+    file: relative2(root, file).split("\\").join("/"),
+    types: Object.values(loaded.sections[index] ?? {}).filter((value) => loaded.sdk.isSectionDefinition(value)).map((section) => section.type)
+  }));
+  return { theme: theme2, sdk: loaded.sdk, client: loaded.client, sectionFiles };
+}
+
+// src/theme-check.ts
+var DEFAULT_LOCALES = ["en", "ru", "uz"];
+var TEXT_TYPES = /* @__PURE__ */ new Set(["TEXT", "TEXTAREA", "RICHTEXT"]);
+var COPY_ATTRIBUTES = /* @__PURE__ */ new Set(["alt", "aria-label", "placeholder", "title"]);
+var OPT_OUT = "theme-copy-ok";
+async function checkTheme(directory, options = {}) {
+  const project = await loadProject(directory);
+  const { theme: theme2, sdk, sectionFiles } = project;
+  const issues = [];
+  for (const [name, template] of Object.entries(theme2.templates)) {
+    for (const issue of sdk.validateTemplate(template, theme2, { template: name })) {
+      issues.push({ severity: "error", ...issue, path: `templates.${name}.${issue.path}` });
+    }
+  }
+  const registered = new Set(theme2.sections.map((section) => section.type));
+  for (const { file, types } of sectionFiles) {
+    for (const type of types.filter((t) => !registered.has(t))) {
+      issues.push({
+        severity: "error",
+        path: file,
+        code: "SECTION_NOT_REGISTERED",
+        message: `the section "${type}" is defined here but not listed in defineTheme({ sections }) in theme/index.ts, so it is never pushed or rendered.`
+      });
+    }
+  }
+  issues.push(...missingDefaults(theme2, options.locales ?? DEFAULT_LOCALES));
+  issues.push(
+    ...hardcodedCopy(
+      directory,
+      sectionFiles.map((section) => section.file),
+      options.strict ? "error" : "warning"
+    )
+  );
+  return { project, manifest: sdk.buildManifest(theme2), issues };
+}
+function missingDefaults(theme2, locales) {
+  const issues = [];
+  const visit = (settings, path) => {
+    (settings ?? []).forEach((setting, index) => {
+      if (!TEXT_TYPES.has(setting.type)) {
+        return;
+      }
+      const at = `${path}.${index}.default`;
+      const value = setting.default;
+      let problem = null;
+      if (value === void 0) {
+        problem = "has no default";
+      } else if (typeof value === "string") {
+        problem = value === "" ? null : "has one default for every language";
+      } else if (typeof value === "object" && value !== null) {
+        const missing = locales.filter((locale) => !(locale in value));
+        problem = missing.length > 0 ? `has no default in ${missing.join(", ")}` : null;
+      }
+      if (problem !== null) {
+        issues.push({
+          severity: "warning",
+          path: at,
+          code: "MISSING_DEFAULT",
+          message: `the text setting "${setting.id}" ${problem}: give a default in ${locales.join(", ")}.`
+        });
+      }
+    });
+  };
+  visit(theme2.settings, "settings");
+  theme2.sections.forEach((section, index) => {
+    visit(section.settings, `sections.${index}.settings`);
+    (section.blocks ?? []).forEach(
+      (block, blockIndex) => visit(block.settings, `sections.${index}.blocks.${blockIndex}.settings`)
+    );
+  });
+  return issues;
+}
+function loadTypeScript(directory) {
+  try {
+    return createRequire2(join4(resolve4(directory), "package.json"))("typescript");
+  } catch {
+    return null;
+  }
+}
+function hardcodedCopy(directory, files, severity) {
+  if (files.length === 0) {
+    return [];
+  }
+  const ts = loadTypeScript(directory);
+  if (ts === null) {
+    return [
+      {
+        severity: "warning",
+        path: "theme/sections",
+        code: "HARDCODED_COPY",
+        message: "not checked: install typescript in the storefront to check section copy."
+      }
+    ];
+  }
+  const issues = [];
+  for (const file of files) {
+    const text = readFileSync3(resolve4(directory, file), "utf8");
+    const lines = text.split("\n");
+    const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const report = (node, copy) => {
+      const line = source.getLineAndCharacterOfPosition(node.getStart(source)).line;
+      if (lines[line]?.includes(OPT_OUT) || lines[line - 1]?.includes(OPT_OUT)) {
+        return;
+      }
+      issues.push({
+        severity,
+        path: `${file}:${line + 1}`,
+        code: "HARDCODED_COPY",
+        message: `"${copy}" is copy the merchant cannot edit: put it in a TEXT setting with a default (or mark it ${OPT_OUT}).`
+      });
+    };
+    const visit = (node) => {
+      if (ts.isJsxText(node)) {
+        const copy = node.text.trim().replace(/\s+/g, " ");
+        if (new RegExp("\\p{L}", "u").test(copy)) {
+          report(node, copy);
+        }
+      } else if (ts.isJsxAttribute(node) && COPY_ATTRIBUTES.has(node.name.getText(source))) {
+        const initializer = node.initializer;
+        const literal = initializer === void 0 ? void 0 : ts.isStringLiteral(initializer) ? initializer : ts.isJsxExpression(initializer) && initializer.expression !== void 0 && ts.isStringLiteralLike(initializer.expression) ? initializer.expression : void 0;
+        if (literal !== void 0 && new RegExp("\\p{L}", "u").test(literal.text)) {
+          report(node, literal.text);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(source);
+  }
+  return issues;
+}
+function formatIssue(issue) {
+  const level = issue.severity === "warning" ? " (warning)" : "";
+  return `${issue.path}: ${issue.code}${level} ${issue.message}`;
+}
+
+// src/theme-commands.ts
+var processReporter = {
+  out: (line) => process.stdout.write(`${line}
+`),
+  err: (line) => process.stderr.write(`${line}
+`)
+};
+var CommandFailed = class extends Error {
+  name = "CommandFailed";
+};
+function summary(manifest) {
+  const templates = Object.keys(manifest.templates).length;
+  return `theme ${manifest.name}@${manifest.version}: ${manifest.sections.length} sections, ${templates} templates`;
+}
+async function checked(directory, options, reporter) {
+  let result;
+  try {
+    result = await checkTheme(directory, options);
+  } catch (error) {
+    if (error instanceof ThemeLoadError) {
+      throw new CommandFailed(error.message);
+    }
+    throw error;
+  }
+  for (const issue of result.issues) {
+    reporter.err(formatIssue(issue));
+  }
+  const errors = result.issues.filter((issue) => issue.severity === "error").length;
+  if (errors > 0) {
+    throw new CommandFailed(`${errors} theme error(s).`);
+  }
+  return result;
+}
+async function themeCheck(directory, options = {}, reporter = processReporter) {
+  const result = await checked(directory, options, reporter);
+  reporter.out(summary(result.manifest));
+  return result;
+}
+async function themeBuild(directory, options = {}, reporter = processReporter) {
+  const result = await checked(directory, options, reporter);
+  const output = resolve5(directory, OUTPUT_DIRECTORY);
+  mkdirSync2(output, { recursive: true });
+  writeFileSync3(join5(output, "theme.json"), `${JSON.stringify(result.manifest, null, 2)}
+`);
+  reporter.out(`${summary(result.manifest)} \u2192 ${OUTPUT_DIRECTORY}/theme.json`);
+  return result;
+}
+function storefrontEnv(directory, environment = process.env) {
+  const values = {};
+  for (const name of [".env", ".env.local"]) {
+    const file = resolve5(directory, name);
+    if (!existsSync3(file)) {
+      continue;
+    }
+    for (const line of readFileSync4(file, "utf8").split("\n")) {
+      const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+      if (match) {
+        values[match[1]] = match[2].replace(/^(['"])(.*)\1$/, "$2");
+      }
+    }
+  }
+  for (const [key, value] of Object.entries(environment)) {
+    if (value !== void 0 && value !== "") {
+      values[key] = value;
+    }
+  }
+  return values;
+}
+function fileForField(field, project, manifest) {
+  const [head, index] = field.split(".");
+  if (head === "sections" && index !== void 0) {
+    const type = manifest.sections[Number(index)]?.type;
+    const file = project.sectionFiles.find(
+      (section) => type !== void 0 && section.types.includes(type)
+    );
+    return file?.file ?? THEME_ENTRY;
+  }
+  if (head === "templates" && index !== void 0) {
+    return `theme/templates/${index}.json`;
+  }
+  if (head === "settings") {
+    return "theme/settings.ts";
+  }
+  return THEME_ENTRY;
+}
+function tokenPrefix(token) {
+  return `${token.slice(0, 12)}\u2026`;
+}
+async function themePush(directory, options = {}, reporter = processReporter) {
+  const env = storefrontEnv(directory, options.environment);
+  const token = env.MAGICSTORE_THEME_TOKEN;
+  if (!token) {
+    throw new CommandFailed(
+      "Set MAGICSTORE_THEME_TOKEN (the theme deploy token, mtt_\u2026, from Shop settings \u2192 Storefront API)."
+    );
+  }
+  if (!token.startsWith("mtt_")) {
+    throw new CommandFailed(
+      token.startsWith("msf_") ? "MAGICSTORE_THEME_TOKEN holds a storefront access token (msf_\u2026). Pushing needs the theme deploy token (mtt_\u2026)." : "MAGICSTORE_THEME_TOKEN is not a theme deploy token (mtt_\u2026)."
+    );
+  }
+  const shopDomain = env.MAGICSTORE_SHOP_DOMAIN;
+  const baseUrl = env.MAGICSTORE_API_URL;
+  if (!shopDomain && !baseUrl) {
+    throw new CommandFailed("Set MAGICSTORE_SHOP_DOMAIN or MAGICSTORE_API_URL.");
+  }
+  const started = Date.now();
+  const { project, manifest } = await checked(directory, options, reporter);
+  if (options.verbose) {
+    reporter.out(`checked in ${Date.now() - started} ms`);
+  }
+  const baseFetch = options.fetch ?? globalThis.fetch;
+  const fetch = async (input, init) => {
+    const request = input instanceof Request ? input : new Request(input, init);
+    const url = new URL(request.url);
+    const sent = Date.now();
+    const response = await baseFetch(request);
+    if (options.verbose) {
+      reporter.out(
+        `${request.method} ${url.origin}${url.pathname} \u2192 ${response.status} in ${Date.now() - sent} ms`
+      );
+    }
+    return response;
+  };
+  const client = project.client.createStorefrontClient({
+    ...baseUrl ? { baseUrl } : { shopDomain },
+    fetch
+  });
+  const role = options.role ?? "UNPUBLISHED";
+  if (options.verbose) {
+    reporter.out(`pushing as ${role} with ${tokenPrefix(token)}`);
+  }
+  try {
+    const { data } = await client.themePush({
+      query: { role },
+      header: { "X-Theme-Token": token },
+      body: manifest
+    });
+    reporter.out(
+      `pushed ${data.name}@${data.version} (${data.role}): ${data.sectionCount} sections`
+    );
+    for (const orphan of data.orphaned) {
+      reporter.err(
+        `templates.${orphan.template}.sections.${orphan.sectionId}: ORPHANED (warning) the stored section of type "${orphan.type}" is hidden: this theme no longer declares that type.`
+      );
+    }
+    return { pushed: data, manifest };
+  } catch (error) {
+    if (!(error instanceof project.client.MagicStoreError)) {
+      throw error;
+    }
+    for (const fieldError of error.errors) {
+      reporter.err(
+        `${fileForField(fieldError.field, project, manifest)}: ${fieldError.field} ${fieldError.code} ${fieldError.message}`
+      );
+    }
+    const hint = error.code === "THEME_VERSION_CONFLICT" ? ` Bump version in ${THEME_ENTRY} (it is ${manifest.version}).` : "";
+    const message = `themePush failed: ${error.code} ${error.detail}${hint} (request ${error.requestId})`;
+    throw new CommandFailed(message);
+  }
+}
+function themeDev(directory, options = {}, reporter = processReporter) {
+  let timer;
+  let running = false;
+  let again = false;
+  let lastTypes = null;
+  const cycle = async () => {
+    if (running) {
+      again = true;
+      return;
+    }
+    running = true;
+    try {
+      const silent = { out: () => {
+      }, err: reporter.err };
+      const { pushed, manifest } = await themePush(
+        directory,
+        { ...options, role: "DEVELOPMENT" },
+        silent
+      );
+      const types = manifest.sections.map((section) => section.type);
+      const changes = lastTypes === null ? [] : [
+        ...types.filter((type) => !lastTypes.includes(type)).map((type) => `+${type}`),
+        ...lastTypes.filter((type) => !types.includes(type)).map((type) => `-${type}`)
+      ];
+      lastTypes = types;
+      reporter.out(
+        [`pushed v${pushed.version}`, `${pushed.sectionCount} sections`, ...changes].join(", ")
+      );
+    } catch (error) {
+      reporter.err(error instanceof Error ? error.message : String(error));
+    } finally {
+      running = false;
+      if (again) {
+        again = false;
+        void cycle();
+      }
+    }
+  };
+  const watcher = watch(resolve5(directory, "theme"), { recursive: true }, () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => void cycle(), 500);
+  });
+  void cycle();
+  reporter.out("watching theme/ \u2014 pushing to DEVELOPMENT on every change");
+  return {
+    close() {
+      clearTimeout(timer);
+      watcher.close();
+    }
+  };
+}
+
 // src/index.ts
 var HELP = `Usage: create-magic-storefront [directory] [options]
        create-magic-storefront check [directory]
+       create-magic-storefront theme build|check|push|dev [directory] [options]
 
 Scaffolds a Next.js storefront on the MagicStore Storefront API v2.
 
 check verifies that a storefront uses the SDK only through its public entry points
 (no deep @magicstoreai/* imports, no hand-written /api/v2/storefront/... calls).
 
+theme check loads theme/index.ts and checks its sections and templates; theme build also writes
+.magicstore/theme.json; theme push sends it to the shop (MAGICSTORE_THEME_TOKEN, mtt_\u2026, and
+MAGICSTORE_SHOP_DOMAIN or MAGICSTORE_API_URL, from the environment or .env.local); theme dev pushes
+to the DEVELOPMENT role on every change under theme/.
+
 Options:
   --shop <domain>     the shop's storefront domain (shop.example.uz)
   --token <token>     a storefront access token that lists this site's origin (optional)
   --locale <locale>   the language pages render in (default: ru)
+  --strict            theme: copy hardcoded in a section component is an error, not a warning
+  --locales <list>    theme: locales every text default needs (default: en,ru,uz)
+  --publish           theme push: make the version live at once (default: unpublished)
+  --role <role>       theme push: published, unpublished or development
+  --verbose           theme push: print the request URL and timings
   -h, --help          show this help
 `;
+var ROLES = {
+  published: "PUBLISHED",
+  unpublished: "UNPUBLISHED",
+  development: "DEVELOPMENT"
+};
+async function theme(command, directory, values) {
+  const role = values.publish ? "PUBLISHED" : values.role ? ROLES[values.role.toLowerCase()] : void 0;
+  if (values.role && role === void 0) {
+    throw new Error(`--role must be one of ${Object.keys(ROLES).join(", ")}.`);
+  }
+  const options = {
+    ...values.strict ? { strict: true } : {},
+    ...values.locales ? { locales: values.locales.split(",").map((locale) => locale.trim()) } : {},
+    ...values.verbose ? { verbose: true } : {},
+    ...role ? { role } : {}
+  };
+  switch (command) {
+    case "check":
+      await themeCheck(directory, options);
+      return;
+    case "build":
+      await themeBuild(directory, options);
+      return;
+    case "push":
+      await themePush(directory, options);
+      return;
+    case "dev":
+      themeDev(directory, options);
+      return;
+    default:
+      throw new Error("Usage: create-magic-storefront theme build|check|push|dev [directory]");
+  }
+}
 function check(directory) {
   const violations = checkPublicApi(directory);
   if (violations.length > 0) {
@@ -206,6 +709,11 @@ async function main() {
       shop: { type: "string" },
       token: { type: "string" },
       locale: { type: "string" },
+      strict: { type: "boolean" },
+      locales: { type: "string" },
+      publish: { type: "boolean" },
+      role: { type: "string" },
+      verbose: { type: "boolean" },
       help: { type: "boolean", short: "h" }
     }
   });
@@ -217,6 +725,10 @@ async function main() {
     check(positionals[1] ?? ".");
     return;
   }
+  if (positionals[0] === "theme") {
+    await theme(positionals[1], positionals[2] ?? ".", values);
+    return;
+  }
   const interactive = process.stdin.isTTY === true;
   const ask = async (question, fallback) => {
     if (!interactive) {
@@ -229,21 +741,23 @@ async function main() {
   };
   const directory = positionals[0] ?? await ask("Directory", "magic-storefront");
   const shopDomain = values.shop ?? await ask("Shop domain", "");
-  const root = resolve3(dirname(fileURLToPath(import.meta.url)), "..");
-  const own = JSON.parse(readFileSync3(resolve3(root, "package.json"), "utf8"));
+  const root = resolve6(dirname(fileURLToPath(import.meta.url)), "..");
+  const own = JSON.parse(readFileSync5(resolve6(root, "package.json"), "utf8"));
   const { directory: created } = scaffold({
     directory,
-    templateDirectory: resolve3(root, "template"),
-    // The SDK is released together with this CLI: same version.
+    templateDirectory: resolve6(root, "template"),
+    // The SDK is released together with this CLI: same version. The storefront keeps the CLI for
+    // its `theme` commands.
     sdkVersions: {
       "@magicstoreai/hydrogen": own.version,
-      "@magicstoreai/storefront-client": own.version
+      "@magicstoreai/storefront-client": own.version,
+      "create-magic-storefront": own.version
     },
     shopDomain: shopDomain || void 0,
     storefrontToken: values.token,
     locale: values.locale
   });
-  const where = relative2(process.cwd(), created) || ".";
+  const where = relative3(process.cwd(), created) || ".";
   process.stdout.write(`
 Created ${where}.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-magic-storefront",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Scaffold a Next.js storefront on the MagicStore Storefront API v2",
   "license": "MIT",
   "type": "module",
@@ -14,8 +14,14 @@
   "engines": {
     "node": ">=22.12"
   },
+  "dependencies": {
+    "esbuild": "^0.27.0"
+  },
   "devDependencies": {
+    "@magicstoreai/hydrogen": "0.4.0",
+    "@magicstoreai/storefront-client": "0.4.0",
     "@types/node": "^26.6.2",
+    "react": "^19.3.0",
     "tsup": "^8.5.1",
     "typescript": "5.9.3",
     "vitest": "^5.0.1"