@feeef.dev/cli 0.2.0 → 0.2.1

package/dist/index.js

@@ -89,22 +89,22 @@ function createClient(opts = {}) {
   if (requireAuth && !token) {
     throw new Error("Not signed in. Run: feeef signin");
   }
-  const http2 = createHttp(baseURL, token);
+  const http3 = createHttp(baseURL, token);
   const ff = new FeeeF({
     apiKey: token || "",
     baseURL,
-    client: http2,
+    client: http3,
     cache: false
   });
-  return { ff, http: http2, cfg, baseURL, token };
+  return { ff, http: http3, cfg, baseURL, token };
 }
 async function signinWithPassword(input) {
   const baseURL = (input.apiUrl || defaultApiUrl()).replace(/\/$/, "");
-  const http2 = createHttp(baseURL, void 0);
+  const http3 = createHttp(baseURL, void 0);
   const ff = new FeeeF({
     apiKey: "",
     baseURL,
-    client: http2,
+    client: http3,
     cache: false
   });
   const auth = await ff.users.signin({
@@ -604,14 +604,14 @@ function resolveThemeDir(dirArg) {
   if (dirArg) {
     const abs = path2.resolve(dirArg);
     if (!fs2.existsSync(abs)) {
-      throw new Error(`Theme directory not found: ${abs}`);
+      throw new Error(`Template directory not found: ${abs}`);
     }
     return findThemeRoot(abs) || abs;
   }
   const fromCwd = findThemeRoot(process.cwd());
   if (fromCwd) return fromCwd;
   throw new Error(
-    "No theme found. Run inside a theme folder (feeef.template.json) or: feeef template init"
+    "No template found. Run inside a template folder (feeef.template.json) or: feeef template init"
   );
 }
 
@@ -938,6 +938,13 @@ async function loadBuild() {
   }
   return import(pathToFileURL(buildPath).href);
 }
+async function loadSmoke() {
+  const smokePath = path5.join(templateKitRoot(), "lib", "smoke.mjs");
+  if (!fs4.existsSync(smokePath)) {
+    throw new Error(`template-kit smoke missing at ${smokePath}`);
+  }
+  return import(pathToFileURL(smokePath).href);
+}
 async function loadUnpack() {
   const unpackPath = path5.join(templateKitRoot(), "lib", "unpack.mjs");
   if (!fs4.existsSync(unpackPath)) {
@@ -957,7 +964,7 @@ async function runTemplateBuild(dirArg, opts = {}) {
     const srcDir = resolveThemeDir(dirArg);
     const outPath = path6.join(srcDir, "dist", "data.json");
     const s = spinner2();
-    s.start(opts.checkOnly ? "Checking theme\u2026" : "Building theme\u2026");
+    s.start(opts.checkOnly ? "Checking template\u2026" : "Building template\u2026");
     const { buildTemplate } = await loadBuild();
     const result = buildTemplate({
       srcDir,
@@ -1010,7 +1017,7 @@ function assertStorefrontPath() {
     throw new Error(
       [
         "Lithium storefront not found.",
-        "Set it once (theme repos do not need storefront source inside them):",
+        "Set it once (template repos do not need storefront source inside them):",
         "  feeef config set storefrontPath /path/to/storefront",
         "or:",
         "  export FEEEF_STOREFRONT_PATH=/path/to/storefront"
@@ -1020,6 +1027,85 @@ function assertStorefrontPath() {
   return root;
 }
 
+// src/dev-error-server.ts
+import http2 from "http";
+
+// src/dev-error-format.ts
+function formatFeeefLiveErrorLine(body) {
+  const debug = body.debug || {};
+  const kind = String(body.kind || "error");
+  const message = String(body.message || "unknown");
+  const lines = [
+    `[feeef:custom-live] ${kind}`,
+    debug.sourcePath ? `  path: ${debug.sourcePath}` : null,
+    debug.instanceId ? `  instanceId: ${debug.instanceId}` : null,
+    debug.title ? `  title: ${debug.title}` : null,
+    debug.type ? `  type: ${debug.type}` : null,
+    `  message: ${message}`,
+    body.props && typeof body.props === "object" ? `  props: ${JSON.stringify(body.props)}` : null,
+    body.href ? `  href: ${body.href}` : null
+  ].filter(Boolean);
+  return lines.join("\n");
+}
+
+// src/dev-error-server.ts
+async function startDevErrorServer(opts) {
+  const preferred = opts?.preferredPort ?? (Number(process.env["FEEEF_DEV_ERROR_PORT"]) || 0);
+  const server = http2.createServer((req, res) => {
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+    if (req.method === "GET" && (req.url === "/" || req.url === "/health")) {
+      res.writeHead(200, { "Content-Type": "text/plain" });
+      res.end("feeef-dev-error-ok");
+      return;
+    }
+    if (req.method === "POST" && req.url?.startsWith("/feeef-error")) {
+      const chunks = [];
+      req.on("data", (c) => chunks.push(c));
+      req.on("end", () => {
+        try {
+          const raw = Buffer.concat(chunks).toString("utf8");
+          const body = JSON.parse(raw);
+          const line = formatFeeefLiveErrorLine(body);
+          console.error("\n" + line + "\n");
+          res.writeHead(204);
+          res.end();
+        } catch (e) {
+          console.error("[feeef:custom-live] bad error payload", e);
+          res.writeHead(400);
+          res.end("bad json");
+        }
+      });
+      return;
+    }
+    res.writeHead(404);
+    res.end("not found");
+  });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(preferred, "127.0.0.1", () => resolve());
+  });
+  const addr = server.address();
+  if (!addr || typeof addr === "string") {
+    throw new Error("Failed to bind feeef dev error server");
+  }
+  const port = addr.port;
+  const url = `http://127.0.0.1:${port}`;
+  return {
+    port,
+    url,
+    close: () => new Promise((resolve) => {
+      server.close(() => resolve());
+    })
+  };
+}
+
 // src/commands/template/dev.ts
 function killChildren(children) {
   for (const c of children) {
@@ -1053,7 +1139,7 @@ async function resolveBoundStore(srcDir) {
   });
   if (!storeRef) {
     throw new Error(
-      "No store linked. Run: feeef use <slug>\n(Remote preview pushes a draft to your store \u2014 live theme stays unchanged.)"
+      "No store linked. Run: feeef use <slug>\n(Remote preview pushes a draft to your store \u2014 live template stays unchanged.)"
     );
   }
   const { ff } = createClient({ requireAuth: true });
@@ -1070,10 +1156,21 @@ async function runRemoteDraftPreview(srcDir) {
   const { storeId, slug } = await resolveBoundStore(srcDir);
   const { ff } = createClient({ requireAuth: true });
   const s = spinner2();
-  s.start("Building theme\u2026");
+  s.start("Building template\u2026");
   const { buildTemplate } = await loadBuild();
   buildTemplate({ srcDir, outPath, write: true });
   s.stop("dist ready");
+  const errorServer = await startDevErrorServer();
+  info(`Component errors \u2192 ${pc.cyan(errorServer.url)} (terminal)`);
+  const withDevLog = (previewUrl) => {
+    try {
+      const u = new URL(previewUrl);
+      u.searchParams.set("feeef_dev_log", errorServer.url);
+      return u.toString();
+    } catch {
+      return previewUrl;
+    }
+  };
   let lastPreviewUrl;
   let pushInFlight = false;
   let pushQueued = false;
@@ -1090,8 +1187,8 @@ async function runRemoteDraftPreview(srcDir) {
       }
       const data = JSON.parse(fs6.readFileSync(outPath, "utf8"));
       const result = await ff.stores.putTemplatePreview(storeId, { data });
-      lastPreviewUrl = result.previewUrl;
-      ok(`Draft preview updated \u2192 ${pc.cyan(result.previewUrl)}`);
+      lastPreviewUrl = withDevLog(result.previewUrl);
+      ok(`Draft preview updated \u2192 ${pc.cyan(lastPreviewUrl)}`);
     } catch (e) {
       fail(e);
     } finally {
@@ -1111,12 +1208,13 @@ async function runRemoteDraftPreview(srcDir) {
   }
   note2(
     [
-      `Theme   ${srcDir}`,
-      `Store   ${slug} (${storeId})`,
-      `Preview ${lastPreviewUrl ?? "(pending)"}`,
+      `Template ${srcDir}`,
+      `Store    ${slug} (${storeId})`,
+      `Preview  ${lastPreviewUrl ?? "(pending)"}`,
       "",
       "Live customers still see metadata.templateData.",
       "Exit preview in the browser: banner \u2192 Exit, or /?preview=0",
+      `CustomLive errors print here via ${errorServer.url}`,
       "Stopping the CLI clears the draft."
     ].join("\n"),
     "Remote draft preview"
@@ -1144,6 +1242,10 @@ async function runRemoteDraftPreview(srcDir) {
     watching = false;
     debouncedPush.cancel();
     killChildren([watch]);
+    try {
+      await errorServer.close();
+    } catch {
+    }
     try {
       await ff.stores.clearTemplatePreview(storeId);
       info("Cleared draft preview on server");
@@ -1173,6 +1275,8 @@ async function runLocalStorefrontPreview(srcDir, opts) {
     process.env["FEEEF_STOREFRONT_PATH"] = path8.resolve(opts.storefront);
   }
   const storefrontRoot = assertStorefrontPath();
+  const errorServer = await startDevErrorServer();
+  info(`Component errors \u2192 ${pc.cyan(errorServer.url)} (terminal)`);
   const cfg = loadConfig();
   const storeRef = resolveStoreIdFromProject({
     themeRoot: srcDir,
@@ -1199,16 +1303,26 @@ async function runLocalStorefrontPreview(srcDir, opts) {
     }
   }
   const s = spinner2();
-  s.start("Building theme\u2026");
+  s.start("Building template\u2026");
   const { buildTemplate } = await loadBuild();
   buildTemplate({ srcDir, outPath, write: true });
   s.stop("dist ready");
   const previewHost = slug ? `http://${slug}.localhost.feeef.org:${port}` : `http://localhost:${port}`;
+  const previewWithLog = (() => {
+    try {
+      const u = new URL(previewHost);
+      u.searchParams.set("feeef_dev_log", errorServer.url);
+      return u.toString();
+    } catch {
+      return previewHost;
+    }
+  })();
   note2(
     [
-      `Theme     ${srcDir}`,
+      `Template   ${srcDir}`,
       `Storefront ${storefrontRoot}`,
-      `Preview   ${previewHost}`,
+      `Preview    ${previewWithLog}`,
+      `Errors     ${errorServer.url}`,
       "Internal --local mode (not for public docs)."
     ].join("\n"),
     "Local Next preview"
@@ -1217,6 +1331,7 @@ async function runLocalStorefrontPreview(srcDir, opts) {
     ...process.env,
     FEEEF_TEMPLATE_DATA_PATH: outPath,
     FEEEF_TEMPLATE_LIBRARY_PATH: libraryPath,
+    FEEEF_DEV_LOG_URL: errorServer.url,
     PORT: String(port)
   };
   if (slug) {
@@ -1235,7 +1350,7 @@ async function runLocalStorefrontPreview(srcDir, opts) {
   const children = [watch, next];
   const shutdown = (code = 0) => {
     killChildren(children);
-    process.exit(code);
+    void errorServer.close().finally(() => process.exit(code));
   };
   process.on("SIGINT", () => shutdown(0));
   process.on("SIGTERM", () => shutdown(0));
@@ -1243,7 +1358,7 @@ async function runLocalStorefrontPreview(srcDir, opts) {
   watch.on("exit", (code) => {
     if (code && code !== 0) shutdown(code);
   });
-  ok(`Open ${pc.cyan(previewHost)}`);
+  ok(`Open ${pc.cyan(previewWithLog)}`);
   outro2("Watching \u2014 Ctrl+C to stop");
   await new Promise(() => {
   });
@@ -1324,15 +1439,16 @@ function packageNameFromFolder(name) {
   return name.toLowerCase();
 }
 var DEFAULT_PACKAGE_JSON = {
-  name: "feeef-theme",
+  name: "feeef-template",
   private: true,
   version: "0.1.0",
-  description: "Feeef Lithium theme",
+  description: "Feeef Lithium template",
   type: "module",
   engines: { node: ">=18" },
   scripts: {
     build: "feeef template build",
     check: "feeef template check",
+    test: "feeef template smoke",
     dev: "feeef template dev",
     publish: "feeef template publish",
     typecheck: "tsc --noEmit"
@@ -1448,7 +1564,9 @@ function ensureNodePackage(dest, folderName) {
       pkg.scripts = { ...DEFAULT_PACKAGE_JSON.scripts };
     }
     const scripts = pkg.scripts;
-    if (!scripts.typecheck) scripts.typecheck = "tsc --noEmit";
+    for (const [key, value] of Object.entries(DEFAULT_PACKAGE_JSON.scripts)) {
+      if (!scripts[key]) scripts[key] = value;
+    }
     const devDeps = pkg.devDependencies && typeof pkg.devDependencies === "object" ? pkg.devDependencies : {};
     for (const [name, version] of Object.entries(EDITOR_DEV_DEPS)) {
       if (!devDeps[name]) devDeps[name] = version;
@@ -2028,7 +2146,7 @@ async function initFromPublicTemplate(dest, name, templateId, ff) {
     );
     const { unpackTemplate } = await loadUnpack();
     const unpackSpin = spinner2();
-    unpackSpin.start("Unpacking theme files\u2026");
+    unpackSpin.start("Unpacking template files\u2026");
     const stats = unpackTemplate({
       inputPath: dataPath,
       outDir: dest,
@@ -2101,7 +2219,7 @@ async function runTemplateInit(nameArg, opts = {}) {
       options: [
         {
           value: "blank",
-          label: "Blank theme",
+          label: "Blank template",
           hint: resolveBlankKitGitUrl() ? "git clone official / monorepo kit" : "local scaffold"
         },
         {
@@ -2117,8 +2235,8 @@ async function runTemplateInit(nameArg, opts = {}) {
       ]
     });
     const name = nameArg || await text2({
-      message: "Theme folder name",
-      placeholder: "my-theme",
+      message: "Template folder name",
+      placeholder: "my-template",
       validate: validateFolderName
     });
     const dest = path12.resolve(process.cwd(), name);
@@ -2141,7 +2259,7 @@ async function runTemplateInit(nameArg, opts = {}) {
       info(
         "Next:\n  cd " + name + "\n  feeef signin\n  feeef use\n  npm run build"
       );
-      outro2("Theme scaffold ready");
+      outro2("Template scaffold ready");
       return;
     }
     const { ff } = createClient({ requireAuth: false });
@@ -2159,7 +2277,7 @@ async function runTemplateInit(nameArg, opts = {}) {
     info(
       "Next:\n  cd " + name + "\n  feeef signin\n  feeef use\n  npm run build\n  npm run dev"
     );
-    outro2("Theme cloned and ready");
+    outro2("Template cloned and ready");
   } catch (e) {
     fail(e);
   }
@@ -2242,7 +2360,7 @@ async function runUse(storeArg, opts) {
     const themeRoot = findThemeRoot(process.cwd());
     if (!themeRoot) {
       fail(
-        "No feeef.template.json nearby. Run from a theme folder or feeef template init first."
+        "No feeef.template.json nearby. Run from a template folder or feeef template init first."
       );
     }
     const { ff } = createClient();
@@ -2271,7 +2389,7 @@ async function runUse(storeArg, opts) {
     if (opts.apiUrl) patch.apiUrl = opts.apiUrl;
     const { rcPath } = saveProjectRc(themeRoot, patch);
     saveConfig({ defaultStoreId: storeId });
-    ok(`Linked theme \u2192 store ${slug || storeId}`);
+    ok(`Linked template \u2192 store ${slug || storeId}`);
     info(rcPath);
     outro2("Next: feeef template publish --apply");
   } catch (e) {
@@ -2292,7 +2410,7 @@ var SOURCE_TAG_PREFIX = "feeef-source:";
 async function runTemplatePublish(dirArg, opts) {
   intro2("feeef template publish");
   try {
-    const { ff, http: http2, cfg } = createClient();
+    const { ff, http: http3, cfg } = createClient();
     const srcDir = resolveThemeDir(dirArg);
     const meta = loadTemplateMeta(srcDir);
     const rc = loadProjectRc(srcDir);
@@ -2314,7 +2432,7 @@ async function runTemplatePublish(dirArg, opts) {
     }
     const store = await ff.stores.find({ id: storeId });
     const title = opts.title || rc.title || meta.name || path13.basename(srcDir);
-    info(`Theme  ${srcDir}`);
+    info(`Template  ${srcDir}`);
     info(`Store  ${store.slug || storeId} (${policy})`);
     const outPath = path13.join(srcDir, "dist", "data.json");
     const s = spinner2();
@@ -2500,7 +2618,7 @@ async function runTemplatePublish(dirArg, opts) {
       if (typeof ff.storeTemplates.replaceLocales === "function") {
         await ff.storeTemplates.replaceLocales(templateId, locales);
       } else {
-        await http2.put(`/store_templates/${templateId}/locales`, { locales });
+        await http3.put(`/store_templates/${templateId}/locales`, { locales });
       }
       s.stop(`Locales: ${locales.map((l) => l.locale).join(", ")}`);
     }
@@ -2524,8 +2642,48 @@ async function runTemplatePublish(dirArg, opts) {
   }
 }
 
-// src/commands/template/remove.ts
+// src/commands/template/smoke.ts
 import path14 from "path";
+async function runTemplateSmoke(dirArg, opts = {}) {
+  intro2("feeef template smoke");
+  try {
+    const srcDir = resolveThemeDir(dirArg);
+    const s = spinner2();
+    s.start(
+      opts.noBuild ? "Smoking custom components (existing dist)\u2026" : "Building + smoking custom components\u2026"
+    );
+    const { smokeTheme } = await loadSmoke();
+    const result = await smokeTheme({
+      srcDir,
+      build: !opts.noBuild
+    });
+    s.stop(
+      `Smoked ${result.total} custom component${result.total === 1 ? "" : "s"}`
+    );
+    for (const f of result.failed) {
+      const label = f.item.sourcePath || f.item.instanceId || f.item.loc || "?";
+      warn(`\u2717 ${label}`);
+      console.error(pc.red(`  ${f.error.message}`));
+    }
+    if (result.failed.length) {
+      fail(
+        new Error(
+          `smoke failed \u2014 ${result.failed.length}/${result.total} components`
+        )
+      );
+      return;
+    }
+    ok(
+      `All ${result.passed} custom component${result.passed === 1 ? "" : "s"} rendered`
+    );
+    outro2(path14.relative(process.cwd(), srcDir) || srcDir);
+  } catch (e) {
+    fail(e);
+  }
+}
+
+// src/commands/template/remove.ts
+import path15 from "path";
 async function runTemplateRemovePage(pageId, opts = {}) {
   intro2("feeef template remove page");
   try {
@@ -2544,7 +2702,7 @@ async function runTemplateRemovePage(pageId, opts = {}) {
       }
     }
     const { pageId: id, removedPath } = removePage(themeRoot, pageId);
-    ok(`Removed ${path14.relative(themeRoot, removedPath)}`);
+    ok(`Removed ${path15.relative(themeRoot, removedPath)}`);
     outro2(`Page "${id}" deleted`);
   } catch (err) {
     fail(err instanceof Error ? err.message : String(err));
@@ -2570,7 +2728,7 @@ async function runTemplateRemoveComponent(pageId, componentId, opts = {}) {
     const { removedPath } = removeComponent(themeRoot, pageId, componentId, {
       ...opts.section ? { section: opts.section } : {}
     });
-    ok(`Removed ${path14.relative(themeRoot, removedPath)}`);
+    ok(`Removed ${path15.relative(themeRoot, removedPath)}`);
     outro2("Done");
   } catch (err) {
     fail(err instanceof Error ? err.message : String(err));
@@ -2579,12 +2737,12 @@ async function runTemplateRemoveComponent(pageId, componentId, opts = {}) {
 
 // src/commands/template/watch.ts
 import { spawn as spawn2 } from "child_process";
-import path15 from "path";
+import path16 from "path";
 async function runTemplateWatch(dirArg) {
   intro2("feeef template watch");
   try {
     const srcDir = resolveThemeDir(dirArg);
-    const outPath = path15.join(srcDir, "dist", "data.json");
+    const outPath = path16.join(srcDir, "dist", "data.json");
     const s = spinner2();
     s.start("Initial build\u2026");
     const { buildTemplate } = await loadBuild();
@@ -2612,7 +2770,7 @@ async function runTemplateWatch(dirArg) {
 // src/index.ts
 function createProgram() {
   const program = new Command();
-  program.name("feeef").description("Feeef developer CLI \u2014 themes today, cloud tools tomorrow").version("0.2.0").hook("preAction", (thisCommand) => {
+  program.name("feeef").description("Feeef developer CLI \u2014 templates today, cloud tools tomorrow").version("0.2.0").hook("preAction", (thisCommand) => {
     if (thisCommand.args.length === 0) return;
     banner();
   });
@@ -2640,18 +2798,18 @@ function createProgram() {
     runConfigSet(key, value);
   });
   program.command("use").description(
-    "Link theme to a store (.feeefrc); omit store to pick from your list"
-  ).argument("[store]", "Store id or slug (optional \u2014 interactive picker)").option("--api-url <url>", "API override for this theme").action(async (store, opts) => {
+    "Link template to a store (.feeefrc); omit store to pick from your list"
+  ).argument("[store]", "Store id or slug (optional \u2014 interactive picker)").option("--api-url <url>", "API override for this template").action(async (store, opts) => {
     await runUse(store, opts);
   });
-  program.command("publish").description("Build + publish current theme (alias of template publish)").argument("[dir]", "Theme directory").option("--public", "Policy public (default private)").option("--unlisted", "Policy unlisted").option("--store <id>", "Owner store id").option("--title <title>", "Marketplace title").option("--yes", "Skip prompts").option("--apply", "Install onto the store").option("--no-apply", "Do not install").action(async (dir, opts) => {
+  program.command("publish").description("Build + publish current template (alias of template publish)").argument("[dir]", "Template directory").option("--public", "Policy public (default private)").option("--unlisted", "Policy unlisted").option("--store <id>", "Owner store id").option("--title <title>", "Marketplace title").option("--yes", "Skip prompts").option("--apply", "Install onto the store").option("--no-apply", "Do not install").action(async (dir, opts) => {
     await runTemplatePublish(dir, opts);
   });
   const template = program.command("template").description(
-    "Theme kit: init, add/remove page|component, build, check, watch, dev, publish"
+    "Template kit: init, add/remove page|component, build, check, smoke, watch, dev, publish"
   );
   template.command("init").description(
-    "Scaffold a theme (blank, git kit, or public marketplace)"
+    "Scaffold a template (blank, git kit, or public marketplace)"
   ).argument("[name]", "Folder name").option("--blank", "Use the blank scaffold (skip picker)").option("--from <templateId>", "Clone a public template by id").option("--git <url>", "Clone a kit repo (depth 1), Adonis/Laravel style").option("-q, --search <query>", "Pre-fill marketplace search").action(async (name, opts) => {
     await runTemplateInit(name, {
       blank: opts.blank,
@@ -2660,8 +2818,8 @@ function createProgram() {
       git: opts.git
     });
   });
-  const templateAdd = template.command("add").description("Add a page or component to the current theme");
-  templateAdd.command("page").description("Create pages/<pageId>/ with flat components/ + update manifest").argument("<pageId>", "Page id (e.g. home, checkout, thank_you)").option("--dir <path>", "Theme directory").action(async (pageId, opts) => {
+  const templateAdd = template.command("add").description("Add a page or component to the current template");
+  templateAdd.command("page").description("Create pages/<pageId>/ with flat components/ + update manifest").argument("<pageId>", "Page id (e.g. home, checkout, thank_you)").option("--dir <path>", "Template directory").action(async (pageId, opts) => {
     await runTemplateAddPage(pageId, { dir: opts.dir });
   });
   templateAdd.command("component").description(
@@ -2669,42 +2827,47 @@ function createProgram() {
   ).argument("<pageId>", "Page id").argument("<componentId>", "Component file id (e.g. hero)").option("--title <title>", "meta.title (default: Title Case of id)").option(
     "--section <id>",
     "Legacy: write under sections/<id>/components/ instead of flat"
-  ).option("--dir <path>", "Theme directory").action(async (pageId, componentId, opts) => {
+  ).option("--dir <path>", "Template directory").action(async (pageId, componentId, opts) => {
     await runTemplateAddComponent(pageId, componentId, {
       dir: opts.dir,
       title: opts.title,
       section: opts.section
     });
   });
-  const templateRemove = template.command("remove").description("Remove a page or component from the current theme");
-  templateRemove.command("page").description("Delete pages/<pageId>/ and drop it from feeef.template.json").argument("<pageId>", "Page id").option("-y, --yes", "Skip confirmation").option("--dir <path>", "Theme directory").action(async (pageId, opts) => {
+  const templateRemove = template.command("remove").description("Remove a page or component from the current template");
+  templateRemove.command("page").description("Delete pages/<pageId>/ and drop it from feeef.template.json").argument("<pageId>", "Page id").option("-y, --yes", "Skip confirmation").option("--dir <path>", "Template directory").action(async (pageId, opts) => {
     await runTemplateRemovePage(pageId, { dir: opts.dir, yes: opts.yes });
   });
-  templateRemove.command("component").description("Delete a component file/folder under a page").argument("<pageId>", "Page id").argument("<componentId>", "Component id").option("--section <id>", "Legacy: only search sections/<id>/components/").option("-y, --yes", "Skip confirmation").option("--dir <path>", "Theme directory").action(async (pageId, componentId, opts) => {
+  templateRemove.command("component").description("Delete a component file/folder under a page").argument("<pageId>", "Page id").argument("<componentId>", "Component id").option("--section <id>", "Legacy: only search sections/<id>/components/").option("-y, --yes", "Skip confirmation").option("--dir <path>", "Template directory").action(async (pageId, componentId, opts) => {
     await runTemplateRemoveComponent(pageId, componentId, {
       dir: opts.dir,
       section: opts.section,
       yes: opts.yes
     });
   });
-  template.command("build").description("Compile theme \u2192 dist/data.json").argument("[dir]", "Theme directory").action(async (dir) => {
+  template.command("build").description("Compile template \u2192 dist/data.json").argument("[dir]", "Template directory").action(async (dir) => {
     await runTemplateBuild(dir);
   });
-  template.command("check").description("Validate theme without writing dist").argument("[dir]", "Theme directory").action(async (dir) => {
+  template.command("check").description("Validate template without writing dist").argument("[dir]", "Template directory").action(async (dir) => {
     await runTemplateBuild(dir, { checkOnly: true });
   });
-  template.command("watch").description("Rebuild on file changes").argument("[dir]", "Theme directory").action(async (dir) => {
+  template.command("smoke").description(
+    "Build + SSR-eval every custom App() (catches broken components)"
+  ).argument("[dir]", "Template directory").option("--no-build", "Use existing dist/data.json only").action(async (dir, opts) => {
+    await runTemplateSmoke(dir, { noBuild: Boolean(opts.noBuild) });
+  });
+  template.command("watch").description("Rebuild on file changes").argument("[dir]", "Template directory").action(async (dir) => {
     await runTemplateWatch(dir);
   });
   template.command("dev").description(
-    "Watch + push draft preview to hosted storefront (never overwrites live theme)"
-  ).argument("[dir]", "Theme directory").option("-p, --port <port>", "Local Next port (only with --local)").option("--storefront <path>", "Lithium storefront root (implies --local)").option(
+    "Watch + push draft preview to hosted storefront (never overwrites live template)"
+  ).argument("[dir]", "Template directory").option("-p, --port <port>", "Local Next port (only with --local)").option("--storefront <path>", "Lithium storefront root (implies --local)").option(
     "--local",
     "Employee escape hatch: spawn local Next (requires storefront)"
   ).action(async (dir, opts) => {
     await runTemplateDev(dir, opts);
   });
-  template.command("publish").description("Build, upload components + template + locales, optional install").argument("[dir]", "Theme directory").option("--public", "Policy public (default private)").option("--unlisted", "Policy unlisted").option("--store <id>", "Owner store id").option("--title <title>", "Marketplace title").option("--yes", "Skip prompts").option("--apply", "Install onto the store").option("--no-apply", "Do not install").action(async (dir, opts) => {
+  template.command("publish").description("Build, upload components + template + locales, optional install").argument("[dir]", "Template directory").option("--public", "Policy public (default private)").option("--unlisted", "Policy unlisted").option("--store <id>", "Owner store id").option("--title <title>", "Marketplace title").option("--yes", "Skip prompts").option("--apply", "Install onto the store").option("--no-apply", "Do not install").action(async (dir, opts) => {
     await runTemplatePublish(dir, opts);
   });
   const cloud = program.command("cloud").description("Cloud providers (Azure / GCP / AWS) \u2014 coming soon");