@sudajs/cli 0.5.5 → 0.6.1

package/dist/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import { createHash } from 'crypto';
-import fs, { mkdir, writeFile, readFile, stat, readdir } from 'fs/promises';
+import fs, { copyFile, mkdir, readdir, writeFile, stat, readFile, rm } from 'fs/promises';
 import { createRequire } from 'module';
 import path2 from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createAgentPageSchemaOutput, checkThemeModule, formatThemeCheckResult, createThemeAgentManifest, validateAgentPageContentWithManifest, agentValidationResultSchema, createPageDataFromAgentContent, findAgentSection, createAgentComponentSchemaOutput, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
+import { createThemeAgentManifest, createAgentPageSchemaOutput, checkThemeModule, formatThemeCheckResult, validateAgentPageContentWithManifest, agentValidationResultSchema, createPageDataFromAgentContent, findAgentSection, createAgentComponentSchemaOutput, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
 import { themeManifestSchema, FileSystemThemeRegistry } from '@sudajs/theme-engine/server';
 import { Command } from 'commander';
-import { build, context } from 'esbuild';
+import { build } from 'esbuild';
 import { z } from 'zod';
 import os from 'os';
 
@@ -213,6 +213,8 @@ var createProjectOutputSchema = z.object({
   defaultDomain: z.string().nullable(),
   dashboardUrl: z.string()
 });
+var packageRoot = path2.resolve(path2.dirname(fileURLToPath(import.meta.url)), "..");
+var themeTemplateRoot = path2.join(packageRoot, "templates", "theme");
 function createHostReactShimPlugin() {
   return {
     name: "suda-host-react-shim",
@@ -472,29 +474,34 @@ async function validateTheme(root) {
   }
   return result;
 }
-async function runCommand(command, args, cwd) {
-  const { spawn } = await import('child_process');
-  await new Promise((resolve, reject) => {
-    const child = spawn(command, args, { cwd, stdio: "inherit" });
-    child.on("error", reject);
-    child.on("exit", (code) => {
-      if (code === 0) {
-        resolve();
-      } else {
-        reject(new Error(`${command} ${args.join(" ")} exited with ${code ?? "unknown"}.`));
-      }
-    });
-  });
-}
-async function runThemePackageBuild(root) {
-  const packageJson = await readJson(
-    path2.join(root, "package.json")
+var VITE_CONFIG_FILES = [
+  "vite.config.ts",
+  "vite.config.mts",
+  "vite.config.js",
+  "vite.config.mjs"
+];
+async function findViteConfig(root) {
+  for (const file of VITE_CONFIG_FILES) {
+    const candidate = path2.join(root, file);
+    if (await pathExists(candidate)) {
+      return candidate;
+    }
+  }
+  throw new Error(
+    `Missing vite.config.* in ${root}. Suda theme projects must use the Vite template; run \`suda theme init\` or migrate this theme to Vite.`
   );
-  const buildScript = packageJson.scripts?.build;
-  if (!buildScript || buildScript.includes("suda theme") || buildScript.includes("suda-theme")) {
-    return;
+}
+async function loadThemeVite(root) {
+  const themeRequire = createRequire(path2.join(root, "package.json"));
+  let viteEntry;
+  try {
+    viteEntry = themeRequire.resolve("vite");
+  } catch {
+    throw new Error(
+      `Vite is required for Suda theme projects. Install it in ${root}: \`pnpm add -D vite @vitejs/plugin-react tailwindcss @tailwindcss/postcss postcss\`.`
+    );
   }
-  await runCommand("pnpm", ["--dir", root, "run", "build"], process.cwd());
+  return await import(pathToFileURL(viteEntry).href);
 }
 async function findClientEntry(root) {
   const candidates = [
@@ -517,14 +524,74 @@ async function findServerEntry(root) {
   }
   throw new Error(`Missing server entry. Add src/index.ts(x) in ${root}.`);
 }
-async function buildServerBundle(root) {
-  const entryPoint = await findServerEntry(root);
+function isThemeExternal(id) {
+  return id === "react" || id.startsWith("react/") || id === "react-dom" || id.startsWith("react-dom/") || id === "@puckeditor/core" || id.startsWith("@puckeditor/core/") || id === "@sudajs/theme-engine" || id.startsWith("@sudajs/theme-engine/");
+}
+async function buildViteTheme(root) {
+  const viteConfig = await findViteConfig(root);
+  const vite = await loadThemeVite(root);
+  const serverEntry = await findServerEntry(root);
+  const stylesEntry = path2.join(root, "src", "styles.css");
+  if (!await pathExists(stylesEntry)) {
+    throw new Error(`Missing ${stylesEntry}. Vite Suda themes must define src/styles.css.`);
+  }
+  await rm(path2.join(root, "dist"), { recursive: true, force: true });
+  await rm(path2.join(root, ".suda-build"), { recursive: true, force: true });
+  await vite.build({
+    root,
+    configFile: viteConfig,
+    configLoader: "runner",
+    cacheDir: path2.join(root, ".suda-build", "vite-cache"),
+    publicDir: false,
+    build: {
+      emptyOutDir: false,
+      outDir: path2.join(root, "dist"),
+      sourcemap: false,
+      ssr: serverEntry,
+      rollupOptions: {
+        external: isThemeExternal,
+        output: {
+          entryFileNames: "index.js",
+          chunkFileNames: "chunks/[name]-[hash].js",
+          assetFileNames: "assets/[name]-[hash][extname]"
+        }
+      }
+    }
+  });
+  await vite.build({
+    root,
+    configFile: viteConfig,
+    configLoader: "runner",
+    cacheDir: path2.join(root, ".suda-build", "vite-cache"),
+    publicDir: false,
+    build: {
+      emptyOutDir: false,
+      outDir: path2.join(root, ".suda-build", "styles"),
+      sourcemap: false,
+      rollupOptions: {
+        input: stylesEntry,
+        output: {
+          entryFileNames: "style-entry.js",
+          chunkFileNames: "chunks/[name]-[hash].js",
+          assetFileNames: "assets/[name]-[hash][extname]"
+        }
+      }
+    }
+  });
+}
+async function buildClientRuntime(root, minify) {
+  const entryPoint = await findClientEntry(root);
+  if (!await pathExists(entryPoint)) {
+    throw new Error(`Missing client entry: ${entryPoint}`);
+  }
+  await mkdir(path2.join(root, "dist"), { recursive: true });
+  const hostReactShimPlugin = createHostReactShimPlugin();
   await build({
     bundle: true,
     entryPoints: [entryPoint],
     external: [
       "react",
-      "react/jsx-runtime",
+      "react/*",
       "react-dom",
       "react-dom/*",
       "@puckeditor/core",
@@ -534,31 +601,7 @@ async function buildServerBundle(root) {
     ],
     format: "esm",
     jsx: "automatic",
-    minify: false,
-    outfile: path2.join(root, "dist", "index.js"),
-    platform: "node",
-    sourcemap: false,
-    target: "es2022",
-    treeShaking: true
-  });
-}
-async function buildTheme(root, skipThemeBuild) {
-  if (!skipThemeBuild) {
-    await runThemePackageBuild(root);
-  }
-  await buildServerBundle(root);
-  const entryPoint = await findClientEntry(root);
-  if (!await pathExists(entryPoint)) {
-    throw new Error(`Missing client entry: ${entryPoint}`);
-  }
-  await mkdir(path2.join(root, "dist"), { recursive: true });
-  const hostReactShimPlugin = createHostReactShimPlugin();
-  await build({
-    bundle: true,
-    entryPoints: [entryPoint],
-    format: "esm",
-    jsx: "automatic",
-    minify: true,
+    minify,
     outfile: path2.join(root, "dist", "runtime.client.js"),
     platform: "browser",
     plugins: [hostReactShimPlugin],
@@ -566,71 +609,233 @@ async function buildTheme(root, skipThemeBuild) {
     target: "es2022",
     treeShaking: true
   });
+}
+async function withPreservedNodeEnv(run) {
+  const previous = process.env.NODE_ENV;
+  try {
+    return await run();
+  } finally {
+    if (previous === void 0) {
+      delete process.env.NODE_ENV;
+    } else {
+      process.env.NODE_ENV = previous;
+    }
+  }
+}
+async function buildTheme(root) {
+  return withPreservedNodeEnv(async () => {
+    await buildViteTheme(root);
+    await buildClientRuntime(root, true);
+    return finalizeTheme(root);
+  });
+}
+async function finalizeTheme(root) {
+  await findViteConfig(root);
+  await finalizeStylesheet(root);
   const validated = await validateTheme(root);
   await writeThemeArtifacts(validated);
   return validateTheme(root);
 }
-function runThemeCheck(theme) {
+async function finalizeStylesheet(root) {
+  const builtStylesDir = path2.join(root, ".suda-build", "styles");
+  const cssFiles = [
+    ...await collectFiles(root, builtStylesDir),
+    ...await collectFiles(root, path2.join(root, "dist"))
+  ];
+  const cssFile = cssFiles.find((file) => file.relativePath.endsWith(".css"));
+  if (!cssFile) {
+    throw new Error(
+      `Vite did not emit a stylesheet from src/styles.css. Check ${path2.join(root, "vite.config.ts")} and Tailwind/PostCSS configuration.`
+    );
+  }
+  await copyFile(cssFile.absolutePath, path2.join(root, "styles.css"));
+  const assetsDir = path2.join(builtStylesDir, "assets");
+  if (await pathExists(assetsDir)) {
+    await mkdir(path2.join(root, "assets"), { recursive: true });
+    await copyDirectory(assetsDir, path2.join(root, "assets"));
+  }
+}
+async function copyDirectory(source, destination) {
+  const children = await readdir(source, { withFileTypes: true });
+  await mkdir(destination, { recursive: true });
+  for (const child of children) {
+    const sourcePath = path2.join(source, child.name);
+    const destinationPath = path2.join(destination, child.name);
+    if (child.isDirectory()) {
+      await copyDirectory(sourcePath, destinationPath);
+      continue;
+    }
+    await copyFile(sourcePath, destinationPath);
+  }
+}
+var THEME_CHECK_WHITE_LABEL = {
+  visible: true,
+  text: "Powered by <strong>\u901F\u642D\u4E91</strong>",
+  href: "https://www.sudayun.cn"
+};
+var THEME_CHECK_ICP = {
+  text: "\u4EACICP\u590712345678\u53F7",
+  href: "https://beian.miit.gov.cn/"
+};
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function findAnchorTagByHref(html, href) {
+  const pattern = new RegExp(
+    `<a\\b[^>]*href=(['"])${escapeRegExp(href)}\\1[^>]*>`,
+    "i"
+  );
+  return html.match(pattern)?.[0] ?? null;
+}
+function runFooterContractCheck(theme, renderer) {
+  const pageData = theme.module.starterPages[0]?.data ?? { root: { props: {} }, content: [] };
+  const metadata = {
+    resolveAssetUrl: createPreviewAssetResolver(renderer.resolveAssetPath),
+    whiteLabel: THEME_CHECK_WHITE_LABEL,
+    icp: THEME_CHECK_ICP
+  };
+  const html = renderer.renderToString(
+    renderer.createElement(renderer.ThemeRender, {
+      theme: theme.module,
+      pageData,
+      layoutData: theme.module.defaultLayout,
+      metadata
+    })
+  );
+  const issues = [];
+  if (!html.includes("Powered by") || !html.includes("\u901F\u642D\u4E91")) {
+    issues.push("Footer must render metadata.whiteLabel.text when whiteLabel.visible is true.");
+  }
+  if (!html.includes(THEME_CHECK_ICP.text)) {
+    issues.push("Footer must render metadata.icp.text when ICP metadata is present.");
+  }
+  for (const href of [THEME_CHECK_WHITE_LABEL.href, THEME_CHECK_ICP.href]) {
+    const anchorTag = findAnchorTagByHref(html, href);
+    if (!anchorTag) {
+      issues.push(`Footer must render an anchor tag for ${href}.`);
+      continue;
+    }
+    if (!/\btarget=(['"])_blank\1/i.test(anchorTag)) {
+      issues.push(`Footer link ${href} must render with target="_blank".`);
+    }
+  }
+  return issues;
+}
+var __testUtils = {
+  findAnchorTagByHref
+};
+async function runThemeCheck(theme) {
   const result = checkThemeModule(theme.module);
-  const text = formatThemeCheckResult(result);
-  if (result.ok) {
+  const footerIssues = result.ok ? runFooterContractCheck(theme, await loadThemeScopedRenderer(theme.root)) : [];
+  const ok = result.ok && footerIssues.length === 0;
+  const lines = [formatThemeCheckResult(result)];
+  if (footerIssues.length === 0 && result.ok) {
+    lines.push("Footer contract check passed: whiteLabel and ICP metadata render correctly.");
+  } else if (footerIssues.length > 0) {
+    for (const issue of footerIssues) {
+      lines.push(`  error  layoutConfig.footerContract: ${issue}`);
+    }
+    lines.push(`Footer contract check: ${footerIssues.length} error(s).`);
+  }
+  const text = lines.join("\n");
+  if (ok) {
     console.log(text);
   } else {
     console.error(text);
   }
-  return result.ok;
+  return ok;
 }
-async function watchTheme(root, skipThemeBuild, port) {
-  if (!skipThemeBuild) {
-    await runThemePackageBuild(root);
-  }
-  await buildServerBundle(root);
-  const theme = await validateTheme(root);
-  const entryPoint = await findClientEntry(root);
-  await mkdir(path2.join(root, "dist"), { recursive: true });
-  const hostReactShimPlugin = createHostReactShimPlugin();
-  const watchLogPlugin = createWatchLogPlugin("runtime.client.js");
-  const context$1 = await context({
-    bundle: true,
-    entryPoints: [entryPoint],
-    format: "esm",
-    jsx: "automatic",
-    minify: false,
-    outfile: path2.join(root, "dist", "runtime.client.js"),
-    platform: "browser",
-    plugins: [hostReactShimPlugin, watchLogPlugin],
-    sourcemap: true,
-    target: "es2022",
-    treeShaking: true
+async function watchTheme(root, port) {
+  const viteConfig = await findViteConfig(root);
+  const vite = await loadThemeVite(root);
+  const host = "127.0.0.1";
+  const server = await vite.createServer({
+    root,
+    configFile: viteConfig,
+    configLoader: "runner",
+    cacheDir: path2.join(root, ".suda-build", "vite-cache"),
+    appType: "custom",
+    server: { host, port },
+    plugins: [createSudaPreviewVitePlugin(root)]
   });
-  await context$1.watch();
-  const handle = await startPreviewServer(theme, port);
-  console.log(`watching theme runtime; previewing at ${handle.url}`);
+  await server.listen(port);
+  const url = server.resolvedUrls?.local.find((candidate) => candidate.includes("127.0.0.1")) ?? server.resolvedUrls?.local[0] ?? `http://${host}:${port}/`;
+  console.log(`previewing Vite theme at ${url}`);
   await new Promise(() => void 0);
 }
-function createWatchLogPlugin(label) {
+function createSudaPreviewVitePlugin(root) {
   return {
-    name: "suda-theme-watch-log",
-    setup(build) {
-      let firstBuild = true;
-      build.onEnd((result) => {
-        if (firstBuild) {
-          firstBuild = false;
-          return;
-        }
-        const errorCount = result.errors.length;
-        if (errorCount > 0) {
-          console.log(
-            `rebuild failed (${errorCount} error${errorCount === 1 ? "" : "s"}): ${label}`
-          );
-          return;
-        }
-        const stamp = (/* @__PURE__ */ new Date()).toLocaleTimeString();
-        console.log(`[${stamp}] rebuilt ${label}`);
+    name: "suda-theme-preview",
+    configureServer(server) {
+      server.middlewares.use((request, response, next) => {
+        void (async () => {
+          const url = new URL(request.url ?? "/", "http://localhost");
+          const assetPrefixMatch = url.pathname.match(/^\/api\/themes\/[^/]+\/[^/]+\/assets\/(.+)$/);
+          if (assetPrefixMatch?.[1]) {
+            request.url = `/${assetPrefixMatch[1]}${url.search}`;
+            next();
+            return;
+          }
+          if (url.pathname !== "/" && !url.pathname.startsWith("/pages/")) {
+            next();
+            return;
+          }
+          try {
+            const theme = await loadViteDevTheme(root, server);
+            const renderer = await loadThemeScopedRenderer(root);
+            if (url.pathname === "/") {
+              const fallbackSlug = pickStarterSlug(theme);
+              if (!fallbackSlug) {
+                response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+                response.end("No starter pages declared by this theme.");
+                return;
+              }
+              const requested = url.searchParams.get("page");
+              const activeSlug = requested && findStarterPage(theme, requested) ? requested : fallbackSlug;
+              const html2 = await server.transformIndexHtml(
+                url.pathname,
+                renderPreviewShellHtml(theme, activeSlug)
+              );
+              response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+              response.end(html2);
+              return;
+            }
+            const slug = decodeURIComponent(url.pathname.slice("/pages/".length));
+            const starter = findStarterPage(theme, slug);
+            if (!starter) {
+              response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+              response.end(`Unknown starter page: ${slug}`);
+              return;
+            }
+            const html = await server.transformIndexHtml(
+              url.pathname,
+              renderDevStarterPageHtml(theme, starter, renderer)
+            );
+            response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            response.end(html);
+          } catch (error) {
+            response.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+            response.end(error instanceof Error ? error.stack : String(error));
+          }
+        })();
       });
     }
   };
 }
+async function loadViteDevTheme(root, server) {
+  const imported = await server.ssrLoadModule("/src/index.tsx");
+  if (!imported.default) {
+    throw new Error("src/index.tsx must export a default ThemeModule.");
+  }
+  validateThemeModule(imported.default);
+  return {
+    root,
+    module: imported.default,
+    serverEntryPath: path2.join(root, "src", "index.tsx"),
+    clientEntryPath: null,
+    stylesheetPath: path2.join(root, "src", "styles.css")
+  };
+}
 var PREVIEW_PUBLIC_BASE_PATH = "/api/themes";
 function pickStarterSlug(theme) {
   const pages = theme.module.starterPages;
@@ -676,7 +881,7 @@ async function loadThemeScopedRenderer(themeRoot) {
     extractLayoutChrome: themeEngineServerModule.extractLayoutChrome,
     resolveAssetPath: themeEngineServerModule.resolveAssetPath,
     createElement: reactModule.createElement,
-    renderToStaticMarkup: reactDomServerModule.renderToStaticMarkup
+    renderToString: reactDomServerModule.renderToString
   };
 }
 function renderStarterPageHtml(theme, resolved, page, renderer) {
@@ -684,7 +889,7 @@ function renderStarterPageHtml(theme, resolved, page, renderer) {
   const metadata = {
     resolveAssetUrl: createPreviewAssetResolver(renderer.resolveAssetPath)
   };
-  const body = renderer.renderToStaticMarkup(
+  const body = renderer.renderToString(
     renderer.createElement(renderer.ThemeRender, {
       theme: theme.module,
       pageData: page.data,
@@ -718,6 +923,51 @@ function renderStarterPageHtml(theme, resolved, page, renderer) {
     "</html>"
   ].join("");
 }
+function renderDevStarterPageHtml(theme, page, renderer) {
+  const chrome = renderer.extractLayoutChrome(theme.module.defaultLayout);
+  const metadata = {
+    resolveAssetUrl: (value) => {
+      if (!value) {
+        return value;
+      }
+      if (/^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith("/")) {
+        return value;
+      }
+      if (value.startsWith("themes/")) {
+        const parts = value.split("/");
+        return `/${parts.slice(3).join("/")}`;
+      }
+      return value;
+    }
+  };
+  const body = renderer.renderToString(
+    renderer.createElement(renderer.ThemeRender, {
+      theme: theme.module,
+      pageData: page.data,
+      layoutData: theme.module.defaultLayout,
+      metadata
+    })
+  );
+  const cssVarStyle = Object.entries(chrome.cssVariables).map(([key, value]) => `${key}: ${value};`).join(" ");
+  const customHead = chrome.customHeadCode ?? "";
+  const customBody = chrome.customBodyCode ?? "";
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8" />',
+    '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+    `<title>${escapeHtml(`${theme.module.manifest.name} \u2014 ${page.title}`)}</title>`,
+    '<link rel="stylesheet" href="/src/styles.css" />',
+    customHead,
+    "</head>",
+    `<body${cssVarStyle ? ` style="${cssVarStyle}"` : ""}>`,
+    body,
+    customBody,
+    "</body>",
+    "</html>"
+  ].join("");
+}
 function renderPreviewShellHtml(theme, activeSlug) {
   const items = theme.module.starterPages.map((page) => {
     const slug = page.slug;
@@ -923,7 +1173,7 @@ async function captureScreenshot(theme, options) {
 }
 async function screenshotTheme(root, options) {
   const resolved = resolveScreenshotOptions(root, options);
-  const theme = resolved.skipBuild ? await validateTheme(root) : await buildTheme(root, false);
+  const theme = resolved.skipBuild ? await validateTheme(root) : await buildTheme(root);
   await captureScreenshot(theme, resolved);
 }
 async function loadLocalAgentManifest(root) {
@@ -1460,14 +1710,11 @@ ${lines.join("\n")}`;
   }
   return message;
 }
-async function publishTheme(root, skipBuild, skipCheck, force) {
-  const theme = skipBuild ? await validateTheme(root) : await buildTheme(root, false);
-  await writeThemeArtifacts(theme);
-  if (!skipCheck) {
-    const ok = runThemeCheck(theme);
-    if (!ok) {
-      throw new Error("AI metadata check failed. Fix the errors above or rerun with --skip-check.");
-    }
+async function publishTheme(root, skipBuild, force) {
+  const theme = skipBuild ? await finalizeTheme(root) : await buildTheme(root);
+  const ok = await runThemeCheck(theme);
+  if (!ok) {
+    throw new Error("AI metadata check failed. Fix the errors above.");
   }
   const files = await collectThemeArtifactFiles(theme);
   if (!theme.clientEntryPath) {
@@ -1600,6 +1847,14 @@ async function readCliPackageVersions() {
         resolved = `^${engineVersion}`;
       }
     } catch {
+      const monorepoEnginePkgPath = path2.resolve(path2.dirname(here), "..", "..", "theme-engine", "package.json");
+      const engineRaw = await readFile(monorepoEnginePkgPath, "utf8").catch(() => null);
+      if (engineRaw) {
+        const engineVersion = JSON.parse(engineRaw).version;
+        if (typeof engineVersion === "string" && engineVersion.length > 0) {
+          resolved = `^${engineVersion}`;
+        }
+      }
     }
     if (!resolved) {
       throw new Error(
@@ -1614,720 +1869,43 @@ async function readCliPackageVersions() {
   };
   return cachedCliPackageVersions;
 }
+async function replaceTemplateTokens(filePath, replacements) {
+  let contents = await readFile(filePath, "utf8");
+  for (const [token, value] of Object.entries(replacements)) {
+    contents = contents.split(token).join(value);
+  }
+  await writeFile(filePath, contents);
+}
+async function loadThemeTemplateFile(relativePath) {
+  return readFile(path2.join(themeTemplateRoot, relativePath), "utf8");
+}
 async function initTheme(target) {
   const key = path2.basename(target).replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase();
   const cliPackageVersions = await readCliPackageVersions();
-  await mkdir(path2.join(target, "src"), { recursive: true });
-  await writeFile(
-    path2.join(target, "package.json"),
-    `${JSON.stringify(
-      {
-        name: `@suda-themes/${key}`,
-        version: "0.1.0",
-        private: true,
-        packageManager: "pnpm@11.6.0",
-        type: "module",
-        main: "./dist/index.js",
-        types: "./dist/index.d.ts",
-        scripts: {
-          // `build:src` compiles TypeScript sources to dist/. `build` then runs
-          // `suda theme build --skip-theme-build` so the CLI does not recurse
-          // back into this script (it would otherwise see scripts.build and
-          // call `pnpm run build` again, causing infinite recursion).
-          "build:src": "tsc -p tsconfig.json",
-          build: "pnpm run build:src && suda theme build --theme-root . --skip-theme-build",
-          dev: "suda theme dev --theme-root . --skip-theme-build",
-          typecheck: "tsc -p tsconfig.json --noEmit",
-          validate: "suda theme validate --theme-root ."
-        },
-        devDependencies: {
-          "@puckeditor/core": "^0.21.2",
-          "@sudajs/cli": cliPackageVersions.cli,
-          "@sudajs/theme-engine": cliPackageVersions.themeEngine,
-          "@types/node": "^22.0.0",
-          "@types/react": "^19.0.0",
-          "@types/react-dom": "^19.0.0",
-          react: "^19.0.0",
-          "react-dom": "^19.0.0",
-          typescript: "^5.6.0"
-        },
-        peerDependencies: {
-          "@puckeditor/core": "^0.21.2",
-          // Themes are consumed by hosts (workspace/site/worker) that already
-          // ship a copy of `@sudajs/theme-engine`. Declaring it as a peer means
-          // hosts can patch/minor-bump the engine without forcing every theme
-          // to re-publish, while CLI/dev installs still get a working version
-          // via devDependencies.
-          "@sudajs/theme-engine": cliPackageVersions.themeEngine,
-          react: "^19.0.0",
-          "react-dom": "^19.0.0"
-        }
-      },
-      null,
-      2
-    )}
-`
-  );
-  await writeFile(
-    path2.join(target, "pnpm-workspace.yaml"),
-    `# This is NOT a monorepo marker \u2014 it only exists because pnpm 11 moved
-# project-level settings such as \`allowBuilds\` out of package.json. Without
-# a \`packages:\` field this workspace contains just the current package, so
-# the project remains a standalone single-package theme.
-# See https://pnpm.io/settings and https://pnpm.io/pnpm-workspace_yaml.
-allowBuilds:
-  esbuild: true
-`
-  );
-  await writeFile(
-    path2.join(target, "tsconfig.json"),
-    `${JSON.stringify(
-      {
-        compilerOptions: {
-          target: "ES2022",
-          lib: ["DOM", "DOM.Iterable", "ES2022"],
-          module: "NodeNext",
-          moduleResolution: "NodeNext",
-          jsx: "react-jsx",
-          rootDir: "src",
-          outDir: "dist",
-          declaration: true,
-          declarationMap: true,
-          sourceMap: true,
-          strict: true,
-          noUncheckedIndexedAccess: true,
-          esModuleInterop: true,
-          skipLibCheck: true,
-          forceConsistentCasingInFileNames: true,
-          resolveJsonModule: true,
-          types: ["node"]
-        },
-        // `package.json` is included so `src/index.tsx` can read its `version`
-        // via `import pkg from "../package.json"`. tsc tolerates this with
-        // rootDir pinned because the JSON is resolved as input but not emitted.
-        include: ["src", "package.json"]
-      },
-      null,
-      2
-    )}
-`
-  );
-  await writeFile(
-    path2.join(target, "src", "manifest.ts"),
-    `import type { ThemeSourceManifest } from "@sudajs/theme-engine";
-
-// Source-side manifest \u2014 version is intentionally omitted because the
-// authoritative theme version lives in package.json. \`src/index.tsx\` reads
-// package.json#version and merges it into the published ThemeManifest, so a
-// single \`pnpm changeset version\` (or \`npm version\`) bumps everything.
-export const sourceManifest: ThemeSourceManifest = {
-  key: "${key}",
-  name: "${key}",
-  categories: ["other"],
-  minEngineVersion: "0.0.0",
-  entry: "dist/index.js",
-  clientEntry: "dist/runtime.client.js",
-  // Required. SudaCloud currently hosts SSR themes only; CSR/Hybrid postures
-  // are on the roadmap. Authoring \`renderMode\` is the contract a theme uses
-  // to declare which posture it expects from the host.
-  renderMode: "ssr",
-};
-`
-  );
-  await writeFile(
-    path2.join(target, "src", "theme-asset.ts"),
-    `import { createThemeAssetResolver } from "@sudajs/theme-engine/runtime";
-
-import pkg from "../package.json" with { type: "json" };
-import { sourceManifest } from "./manifest.js";
-
-export const themeAsset = createThemeAssetResolver(sourceManifest.key, pkg.version);
-`
-  );
-  await writeFile(
-    path2.join(target, "src", "sections.tsx"),
-    `import type { SudaComponentConfig } from "@sudajs/theme-engine";
-
-export const Hero: SudaComponentConfig = {
-  label: "Hero",
-  ai: {
-    instructions:
-      "Primary page introduction used to communicate the main value proposition. " +
-      "Place near the beginning of landing, product, service, or campaign pages. " +
-      "Include one concise headline, supporting copy, and one primary call to action. " +
-      "Use at most once per page. Do not use for ordinary section headings or article content.",
-  },
-  fields: {
-    eyebrow: { type: "text", label: "Eyebrow" },
-    title: { type: "text", label: "Title" },
-    description: { type: "textarea", label: "Description" },
-    primaryLabel: { type: "text", label: "Primary button label" },
-    primaryHref: { type: "text", label: "Primary button link" },
-  },
-  defaultProps: {
-    eyebrow: "New theme",
-    title: "Build with SudaCloud",
-    description: "Edit this starter section in the visual editor.",
-    primaryLabel: "Get started",
-    primaryHref: "#contact",
-  },
-  render: ({ eyebrow, title, description, primaryLabel, primaryHref }) => (
-    <section className="${key}-section ${key}-hero">
-      <p className="${key}-eyebrow">{eyebrow}</p>
-      <h1>{title}</h1>
-      <p>{description}</p>
-      <a className="${key}-button" href={primaryHref}>{primaryLabel}</a>
-    </section>
-  ),
-};
-
-export const FeatureGrid: SudaComponentConfig = {
-  label: "Feature grid",
-  ai: {
-    instructions:
-      "Section that lists 3\u20136 short feature or benefit cards explaining what the product or service offers. " +
-      "Place after the hero / introduction and before the final call-to-action. " +
-      "Use when the page needs to communicate multiple distinct value points; do not use for testimonials, FAQs, or step-by-step processes.",
-  },
-  fields: {
-    title: { type: "text", label: "Title" },
-    description: { type: "textarea", label: "Description" },
-    features: {
-      type: "array",
-      label: "Features",
-      arrayFields: {
-        title: { type: "text", label: "Title" },
-        description: { type: "textarea", label: "Description" },
-      },
-    },
-  },
-  defaultProps: {
-    title: "Everything you need to launch",
-    description: "Use this section to explain the core value of the project.",
-    features: [
-      { title: "Fast setup", description: "Start from a clean theme contract." },
-      { title: "Visual editing", description: "Expose content fields through Puck." },
-      { title: "Publish ready", description: "Build and publish with the Suda CLI." },
-    ],
-  },
-  render: ({ title, description, features = [] }) => (
-    <section className="${key}-section">
-      <h2>{title}</h2>
-      <p>{description}</p>
-      <div className="${key}-grid">
-        {features.map((feature: { title?: string; description?: string }, index: number) => (
-          <article className="${key}-card" key={index}>
-            <h3>{feature.title}</h3>
-            <p>{feature.description}</p>
-          </article>
-        ))}
-      </div>
-    </section>
-  ),
-};
-
-export const Testimonial: SudaComponentConfig = {
-  label: "Testimonial",
-  ai: {
-    instructions:
-      "Section that quotes a single customer or expert as social proof. " +
-      "Place mid-page after a feature or value section, or near the end before the final CTA. " +
-      "Do not invent quotes, names, or roles; only use content the user provides.",
-  },
-  fields: {
-    quote: { type: "textarea", label: "Quote" },
-    author: { type: "text", label: "Author" },
-    role: { type: "text", label: "Role" },
-  },
-  defaultProps: {
-    quote: "SudaCloud gives our team a practical editing workflow without giving up theme control.",
-    author: "Alex Chen",
-    role: "Founder",
-  },
-  render: ({ quote, author, role }) => (
-    <section className="${key}-section ${key}-quote">
-      <blockquote>{quote}</blockquote>
-      <p>{author} \xB7 {role}</p>
-    </section>
-  ),
-};
-
-export const CallToAction: SudaComponentConfig = {
-  label: "Call to action",
-  ai: {
-    instructions:
-      "Closing conversion section that invites the visitor to take a specific action (sign up, contact, buy, etc.). " +
-      "Place near the end of the page, after supporting content. " +
-      "Use at most once per page. Do not use as the page's first introduction \u2014 the Hero component fills that role.",
-  },
-  fields: {
-    title: { type: "text", label: "Title" },
-    description: { type: "textarea", label: "Description" },
-    buttonLabel: { type: "text", label: "Button label" },
-    buttonHref: { type: "text", label: "Button link" },
-  },
-  defaultProps: {
-    title: "Ready to build your next page?",
-    description: "Use this section as the final conversion block.",
-    buttonLabel: "Contact us",
-    buttonHref: "#contact",
-  },
-  render: ({ title, description, buttonLabel, buttonHref }) => (
-    <section className="${key}-section ${key}-cta" id="contact">
-      <h2>{title}</h2>
-      <p>{description}</p>
-      <a className="${key}-button" href={buttonHref}>{buttonLabel}</a>
-    </section>
-  ),
-};
-
-export const SECTION_COMPONENTS = { Hero, FeatureGrid, Testimonial, CallToAction };
-`
-  );
-  await writeFile(
-    path2.join(target, "src", "layout.tsx"),
-    `import { getPageSlot } from "@sudajs/theme-engine/runtime";
-import type { Config } from "@puckeditor/core";
-import type { SudaComponentConfig } from "@sudajs/theme-engine";
-import type { ReactElement, ReactNode } from "react";
-
-type PuckExtras = { puck?: { metadata?: Record<string, unknown> } };
-
-export const rootConfig: NonNullable<Config["root"]> = {
-  fields: {
-    siteName: { type: "text", label: "Site name" },
-  },
-  defaultProps: { siteName: "${key}" },
-  render: ({ children, siteName }: { children?: ReactNode; siteName?: string }) => (
-    <div className="${key}-root" data-site-name={siteName}>{children}</div>
-  ),
-};
-
-export const Header: SudaComponentConfig = {
-  label: "Header",
-  ai: {
-    instructions:
-      "Site-wide header rendered at the top of every page. " +
-      "Place once at the top of the layout (not inside page content). " +
-      "Used for branding and primary navigation, not for promotional content.",
-  },
-  fields: { siteName: { type: "text", label: "Site name" } },
-  defaultProps: { siteName: "${key}" },
-  render: ({ siteName }) => <header className="${key}-header">{siteName}</header>,
-};
-
-export const PageOutlet: SudaComponentConfig = {
-  label: "Page outlet",
-  ai: {
-    exclude: true,
-    instructions:
-      "Structural slot where each page's content is injected. " +
-      "Managed by the layout, never created or placed by AI.",
-  },
-  fields: {},
-  defaultProps: {},
-  render: (props: PuckExtras): ReactElement => <>{getPageSlot(props.puck?.metadata)}</>,
-};
-
-export const Footer: SudaComponentConfig = {
-  label: "Footer",
-  ai: {
-    instructions:
-      "Site-wide footer rendered at the bottom of every page. " +
-      "Place once at the end of the layout. " +
-      "Used for legal text, copyright, and secondary links \u2014 not for primary CTAs.",
-  },
-  fields: { text: { type: "text", label: "Text" } },
-  defaultProps: { text: "\xA9 ${key}" },
-  render: ({ text }) => <footer className="${key}-footer">{text}</footer>,
-};
-
-export const LAYOUT_COMPONENTS = { Header, PageOutlet, Footer };
-`
-  );
-  await writeFile(
-    path2.join(target, "src", "config.ts"),
-    `import type { Config, Data } from "@puckeditor/core";
-
-import { LAYOUT_COMPONENTS, rootConfig } from "./layout.js";
-import { SECTION_COMPONENTS } from "./sections.js";
-
-export const pageConfig: Config = {
-  components: SECTION_COMPONENTS,
-};
-
-export const layoutConfig: Config = {
-  root: rootConfig,
-  components: LAYOUT_COMPONENTS,
-};
-
-export const defaultLayout: Data = {
-  root: { props: { siteName: "${key}" } },
-  content: [
-    { type: "Header", props: { id: "Header-1", siteName: "${key}" } },
-    { type: "PageOutlet", props: { id: "PageOutlet-1" } },
-    { type: "Footer", props: { id: "Footer-1", text: "\xA9 ${key}" } },
-  ],
-};
-`
-  );
-  await writeFile(
-    path2.join(target, "src", "templates.ts"),
-    `import type { ThemeStarterPage } from "@sudajs/theme-engine";
-
-export const starterPages: ThemeStarterPage[] = [
-  {
-    slug: "home",
-    title: "Home",
-    isHome: true,
-    data: {
-      root: { props: {} },
-      content: [
-        {
-          type: "Hero",
-          props: {
-            id: "Hero-1",
-            eyebrow: "Starter page",
-            title: "Welcome to ${key}",
-            description: "This page was generated by suda theme init.",
-            primaryLabel: "Explore features",
-            primaryHref: "#features",
-          },
-        },
-        {
-          type: "FeatureGrid",
-          props: {
-            id: "FeatureGrid-1",
-            title: "Designed for editable sites",
-            description: "Starter sections show agents and editors how this theme is structured.",
-            features: [
-              { title: "Typed fields", description: "Each section exposes a clear field schema." },
-              { title: "Starter pages", description: "Templates show realistic section composition." },
-              { title: "CLI workflow", description: "Build, validate, preview, and publish from one tool." },
-            ],
-          },
-        },
-        {
-          type: "CallToAction",
-          props: {
-            id: "CallToAction-1",
-            title: "Launch your first page",
-            description: "Customize this starter template or let an agent generate a new draft.",
-            buttonLabel: "Get in touch",
-            buttonHref: "/contact",
-          },
-        },
-      ],
-    },
-  },
-  {
-    slug: "about",
-    title: "About",
-    data: {
-      root: { props: {} },
-      content: [
-        {
-          type: "Hero",
-          props: {
-            id: "Hero-About",
-            eyebrow: "About",
-            title: "A clean starting point for your story",
-            description: "Use this page to introduce the project, audience, and promise.",
-            primaryLabel: "Contact us",
-            primaryHref: "/contact",
-          },
-        },
-        {
-          type: "Testimonial",
-          props: {
-            id: "Testimonial-About",
-            quote: "This starter theme keeps the editable surface focused and predictable.",
-            author: "SudaCloud",
-            role: "Theme team",
-          },
-        },
-      ],
-    },
-  },
-  {
-    slug: "contact",
-    title: "Contact",
-    data: {
-      root: { props: {} },
-      content: [
-        {
-          type: "Hero",
-          props: {
-            id: "Hero-Contact",
-            eyebrow: "Contact",
-            title: "Let's talk",
-            description: "Tell visitors how to reach you and what happens next.",
-            primaryLabel: "Email us",
-            primaryHref: "mailto:hello@example.com",
-          },
-        },
-        {
-          type: "CallToAction",
-          props: {
-            id: "CallToAction-Contact",
-            title: "Start the conversation",
-            description: "Replace this copy with your preferred contact details or form link.",
-            buttonLabel: "Send an email",
-            buttonHref: "mailto:hello@example.com",
-          },
-        },
-      ],
-    },
-  },
-];
-`
-  );
-  await writeFile(
-    path2.join(target, "src", "index.tsx"),
-    `import type { ThemeManifest, ThemeModule } from "@sudajs/theme-engine";
-
-import pkg from "../package.json" with { type: "json" };
-import { defaultLayout, layoutConfig, pageConfig } from "./config.js";
-import { sourceManifest } from "./manifest.js";
-import { starterPages } from "./templates.js";
-
-// Single source of truth: theme version comes from package.json#version,
-// merged into the source-side manifest. esbuild inlines the JSON import at
-// build time, so the published \`dist/index.js\` is fully self-contained.
-export const manifest: ThemeManifest = { ...sourceManifest, version: pkg.version };
-
-const theme: ThemeModule = {
-  manifest,
-  pageConfig,
-  layoutConfig,
-  defaultLayout,
-  starterPages,
-};
-
-export default theme;
-export { pageConfig, layoutConfig, defaultLayout, starterPages };
-`
-  );
-  await writeFile(
-    path2.join(target, "src", "runtime.client.ts"),
-    '"use client";\n\nimport theme from "./index.js";\n\nexport default theme;\n'
-  );
-  await writeFile(
-    path2.join(target, "styles.css"),
-    `.${key}-root { font-family: Inter, ui-sans-serif, system-ui, sans-serif; color: #111827; background: #ffffff; }
-.${key}-header, .${key}-footer { padding: 20px clamp(20px, 5vw, 64px); border-bottom: 1px solid #e5e7eb; }
-.${key}-footer { border-top: 1px solid #e5e7eb; border-bottom: 0; color: #6b7280; }
-.${key}-section { padding: 64px clamp(20px, 5vw, 64px); }
-.${key}-hero { background: #f8fafc; }
-.${key}-eyebrow { text-transform: uppercase; letter-spacing: 0.08em; font-size: 12px; color: #2563eb; font-weight: 700; }
-.${key}-section h1 { max-width: 780px; font-size: clamp(40px, 7vw, 72px); line-height: 0.95; margin: 0 0 20px; }
-.${key}-section h2 { max-width: 720px; font-size: 36px; line-height: 1.05; margin: 0 0 16px; }
-.${key}-section p { max-width: 680px; line-height: 1.7; color: #4b5563; }
-.${key}-button { display: inline-flex; align-items: center; min-height: 42px; padding: 0 18px; border-radius: 8px; background: #111827; color: #ffffff; text-decoration: none; font-weight: 700; }
-.${key}-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 28px; }
-.${key}-card { border: 1px solid #e5e7eb; border-radius: 8px; padding: 20px; }
-.${key}-quote blockquote { max-width: 780px; font-size: 28px; line-height: 1.25; margin: 0 0 16px; }
-.${key}-cta { background: #111827; color: #ffffff; }
-.${key}-cta p { color: #d1d5db; }
-.${key}-cta .${key}-button { background: #ffffff; color: #111827; }
-`
-  );
-  await writeFile(path2.join(target, ".gitignore"), "node_modules\ndist\n*.tsbuildinfo\n");
-  await writeFile(
-    path2.join(target, "AGENTS.md"),
-    `# Suda Theme Agent Guide
-
-This directory is a Suda theme source project generated by \`suda theme init\`.
-It is a **standalone** npm package \u2014 it does not depend on the SudaCloud monorepo.
-
-## Render mode
-
-This theme contract requires \`renderMode: "ssr"\` in the source manifest
-(\`src/manifest.ts\`). SudaCloud's site runtime currently only supports SSR
-themes; CSR / Hybrid postures are on the roadmap. **Do not** introduce
-client-only entry points or assume browser-only globals at module scope \u2014
-the theme bundle must execute in a Node SSR context.
-
-## What to edit
-
-- Add page sections in \`src/sections.tsx\` and register them in \`SECTION_COMPONENTS\`.
-- Add starter pages in \`src/templates.ts\` to show realistic section combinations.
-- Keep shared site chrome in \`src/layout.tsx\`; \`PageOutlet\` is where page content renders.
-- Keep \`src/index.tsx\` exporting the source \`ThemeModule\`. The final artifact is produced by \`suda theme build\`.
-- All relative imports under \`src/\` MUST include the \`.js\` extension (NodeNext ESM resolution).
-
-## Page content rules
-
-- Agent page files passed to \`suda agent page validate/create\` contain \`content\` and optional \`zones\` only.
-- Every \`content[]\` item must use a section type from \`SECTION_COMPONENTS\`.
-- Every \`content[]\` item must include \`props.id\`.
-- Prefer editing section props over changing render code when generating pages.
-- Do not edit files under \`dist/\`; they are generated.
-
-## AI metadata (required)
-
-Every component (and zone-level layout component) **must** declare \`ai.instructions\`.
-Without it the page-generation agent has no way to know what the component is for,
-and \`suda theme check\` (run automatically before publish) will fail.
-
-### Component-level \`ai\`
-
-Each \`ComponentConfig\` must include:
-
-\`\`\`ts
-import type { SudaComponentConfig } from "@sudajs/theme-engine";
-
-export const Hero: SudaComponentConfig = {
-  label: "Hero",
-  ai: {
-    instructions:
-      "Primary page introduction used to communicate the main value proposition. " +
-      "Place near the beginning of landing or product pages. " +
-      "Include one primary CTA. Use at most once per page. " +
-      "Do not use for ordinary section headings or article content.",
-  },
-  fields: { /* ... */ },
-  defaultProps: { /* ... */ },
-  render: (props) => /* ... */,
-};
-\`\`\`
-
-A good \`instructions\` covers, in plain English:
-
-1. **Purpose** \u2014 what role this component plays on a page.
-2. **Use when** \u2014 page types or scenarios where it should be selected.
-3. **Avoid when** \u2014 situations that look similar but call for a different component.
-4. **Placement** \u2014 where in the page it normally belongs (top, after features, near end, etc.).
-5. **Frequency / composition** \u2014 how many times it can appear, what it must contain, and any adjacency rules.
-
-Write executable, specific sentences (\`Use when...\`, \`Place after...\`, \`Use at most once per page.\`).
-Do **not** describe styling (colors, fonts, spacing) \u2014 those belong to the design system.
-Do **not** write vague filler like "modern", "engaging", "beautiful".
-
-If two components look similar (e.g. Hero vs. PageHeader vs. SectionHeader),
-their \`instructions\` must explicitly differentiate them, otherwise the agent
-will mix them up.
-
-### Hiding a component from AI
-
-Use \`ai.exclude: true\` for internal/debug components or anything the agent
-should never auto-create. Such components remain editable by humans:
-
-\`\`\`ts
-ai: { exclude: true, instructions: "Internal debug block; AI must not create it." }
-\`\`\`
-
-### Field-level \`ai\` (recommended, optional)
-
-Field-level metadata sharpens the generated content but is **not required**.
-Use it when a field's name and type alone don't fully convey the constraints:
-
-\`\`\`ts
-fields: {
-  title: {
-    type: "text",
-    ai: {
-      instructions:
-        "Main value-proposition headline. 4\u201312 words, focus on the visitor benefit, " +
-        "do not repeat the eyebrow or description.",
-      required: true,
-    },
-  },
-  imageUrl: {
-    type: "text",
-    ai: {
-      // Atomic values that cannot render correctly while half-streamed.
-      stream: false,
-      instructions: "Image that supports the section topic. Avoid logos, screenshots, or unrelated decoration.",
-    },
-  },
-}
-\`\`\`
-
-Supported field-level keys: \`instructions\`, \`required\`, \`exclude\`, \`stream\`,
-\`bind\` (delegate to a tool), and \`schema\` (only needed for \`custom\` / \`external\` /
-\`user\` fields whose runtime shape can't be inferred).
-
-### Verifying
-
-\`\`\`bash
-pnpm build              # also runs the AI metadata check
-suda theme check        # run the check on its own
-\`\`\`
-
-Missing component-level \`ai.instructions\` is reported as an **error** and blocks
-the build. Very short or label-repeating instructions are reported as
-**warnings**.
-
-## Useful commands
-
-\`\`\`bash
-pnpm install
-pnpm typecheck
-pnpm build               # tsc + suda theme build --skip-theme-build (runs AI check)
-pnpm validate
-pnpm dev                 # watch and serve local theme artifact files
-suda theme check         # AI metadata check only
-suda agent theme describe local --theme-root .
-suda agent section schema --theme local --section Hero --theme-root .
-suda agent page validate --theme local --input ./page.json --theme-root .
-\`\`\`
-`
-  );
-  await writeFile(
-    path2.join(target, "CLAUDE.md"),
-    `# Claude Code
-
-Read \`AGENTS.md\` first. It is the canonical guide for this Suda theme project.
-`
-  );
-  await writeFile(
-    path2.join(target, "README.md"),
-    `# ${key}
-
-A Suda theme scaffolded with \`suda theme init\`. This is a standalone
-package; it does not need to live inside the SudaCloud monorepo.
-
-This theme targets SudaCloud's SSR runtime (\`renderMode: "ssr"\` in
-\`src/manifest.ts\`); CSR / Hybrid postures are not yet supported by the
-host.
-
-## Setup
-
-\`\`\`bash
-pnpm install
-\`\`\`
-
-## Develop
-
-\`\`\`bash
-pnpm typecheck      # type-check sources
-pnpm build          # tsc + suda theme build (server bundle + client runtime + manifest)
-pnpm dev            # watch the browser runtime and start preview server
-pnpm validate       # validate the dist artifact
-\`\`\`
-
-> \`renderMode\` currently only accepts \`"ssr"\`. \`suda theme validate\` and
-> \`suda theme check\` will reject manifests that omit it or set a different
-> value.
-
-## Agent tooling
-
-\`\`\`bash
-suda agent theme describe local --theme-root .
-suda agent page schema local --theme-root .
-suda agent section schema --theme local --section Hero --theme-root .
-\`\`\`
-
-## Publish
-
-\`\`\`bash
-pnpm build
-suda theme screenshot   # optional: capture dist/preview/desktop.png
-suda theme publish
-\`\`\`
-`
-  );
+  await copyDirectory(themeTemplateRoot, target);
+  const packageJson = JSON.parse(await loadThemeTemplateFile("package.json"));
+  packageJson.name = `@suda-themes/${key}`;
+  packageJson.devDependencies["@sudajs/cli"] = cliPackageVersions.cli;
+  packageJson.devDependencies["@sudajs/theme-engine"] = cliPackageVersions.themeEngine;
+  packageJson.peerDependencies["@sudajs/theme-engine"] = cliPackageVersions.themeEngine;
+  await writeFile(path2.join(target, "package.json"), `${JSON.stringify(packageJson, null, 2)}
+`);
+  const replacements = {
+    "__SUDA_THEME_KEY__": key
+  };
+  const filesToReplace = [
+    "README.md",
+    "src/manifest.ts",
+    "src/theme-asset.ts",
+    "src/sections.tsx",
+    "src/layout.tsx",
+    "src/config.ts",
+    "src/templates.ts",
+    "src/styles.css"
+  ];
+  for (const relativePath of filesToReplace) {
+    await replaceTemplateTokens(path2.join(target, relativePath), replacements);
+  }
   console.log(`created theme scaffold at ${target}`);
 }
 function buildProgram() {
@@ -2346,46 +1924,41 @@ function buildProgram() {
       );
     }
   });
-  theme.command("build").description("Build server dist (via package script) and browser runtime.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-theme-build", "Skip the theme package build script.").option("--skip-check", "Skip the AI metadata check that normally runs after build.").action(async (options) => {
-    const result = await buildTheme(resolveThemeRoot(options), options.skipThemeBuild === true);
+  theme.command("build").description("Build a Vite Suda theme artifact.").option("--theme-root <path>", "Theme source/artifact root.").action(async (options) => {
+    const result = await buildTheme(resolveThemeRoot(options));
     console.log(`built ${result.module.manifest.key}@${result.module.manifest.version}`);
-    if (options.skipCheck !== true) {
-      const ok = runThemeCheck(result);
-      if (!ok) {
-        throw new Error(
-          "AI metadata check failed. Fix the errors above or rerun with --skip-check."
-        );
-      }
+    const ok = await runThemeCheck(result);
+    if (!ok) {
+      throw new Error("AI metadata check failed. Fix the errors above.");
     }
   });
+  theme.command("finalize").description("Finalize an existing Vite build into the Suda theme artifact contract.").option("--theme-root <path>", "Theme source/artifact root.").action(async (options) => {
+    const result = await finalizeTheme(resolveThemeRoot(options));
+    console.log(`finalized ${result.module.manifest.key}@${result.module.manifest.version}`);
+  });
   theme.command("check").description(
     "Run AI metadata checks on a built theme without rebuilding. Reports missing component-level ai.instructions as errors and weak content as warnings."
   ).option("--theme-root <path>", "Theme source/artifact root.").action(async (options) => {
     const theme2 = await validateTheme(resolveThemeRoot(options));
-    const ok = runThemeCheck(theme2);
+    const ok = await runThemeCheck(theme2);
     if (!ok) {
       process.exitCode = 1;
     }
   });
-  theme.command("dev").description("Watch and rebuild the browser runtime, and serve the local theme artifact files.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-theme-build", "Skip the theme package build script.").option("--port <port>", "Preview server port.", "4177").action(async (options) => {
+  theme.command("dev").description("Start the Vite-powered local theme preview.").option("--theme-root <path>", "Theme source/artifact root.").option("--port <port>", "Preview server port.", "4177").action(async (options) => {
     const port = Number(options.port ?? "4177");
-    await watchTheme(
-      resolveThemeRoot(options),
-      options.skipThemeBuild === true,
-      Number.isFinite(port) ? port : 4177
-    );
+    await watchTheme(resolveThemeRoot(options), Number.isFinite(port) ? port : 4177);
   });
   theme.command("screenshot").description("Capture a desktop preview screenshot of the home starter page using Playwright.").option("--theme-root <path>", "Theme source/artifact root.").option("--output <path>", "Output PNG path relative to theme root.").option("--width <px>", "Viewport width in pixels.", "1280").option("--height <px>", "Viewport height in pixels.", "800").option("--port <port>", "Preview server port used during capture.", "4178").option("--skip-build", "Skip rebuilding the theme before capturing.").action(async (options) => {
     await screenshotTheme(resolveThemeRoot(options), options);
   });
-  theme.command("publish").description("Upload artifact to S3 and upsert ThemePackage/ThemeVersion.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-build", "Publish existing dist files without rebuilding.").option("--skip-check", "Skip the AI metadata check that normally runs before upload.").option(
+  theme.command("publish").description("Upload artifact to S3 and upsert ThemePackage/ThemeVersion.").option("--theme-root <path>", "Theme source/artifact root.").option("--skip-build", "Publish existing dist files without rebuilding.").option(
     "--force",
     "Development recovery only: clear the existing themes/<key>/<version>/ prefix and ThemeVersion row before republishing. Re-published clients pinned to this version are unavailable until the new publish completes."
   ).action(async (options) => {
     await publishTheme(
       resolveThemeRoot(options),
       options.skipBuild === true,
-      options.skipCheck === true,
       options.force === true
     );
   });
@@ -2469,6 +2042,6 @@ async function main() {
   await program.parseAsync(argv);
 }
 
-export { buildProgram, main, parseThemeRef };
+export { __testUtils, buildProgram, buildTheme, finalizeTheme, initTheme, main, parseThemeRef, validateTheme, watchTheme };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map