@sudajs/cli 0.10.4 → 0.12.0

package/dist/index.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import { createHash } from 'crypto';
-import fs, { writeFile, stat, readdir, readFile, mkdir, copyFile, rm } from 'fs/promises';
+import fs, { readFile, writeFile, stat, readdir, mkdir, copyFile, rm } from 'fs/promises';
 import { createRequire } from 'module';
 import path2 from 'path';
 import { createInterface } from 'readline/promises';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createThemeAgentManifest, createAgentPageSchemaOutput, checkThemeModule, formatThemeCheckResult, validateAgentPageContentWithManifest, agentValidationResultSchema, findAgentSection, createAgentComponentSchemaOutput, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
+import { themeDesignSystemSchema, createThemeAgentManifest, createSudaPageAgentRuntime, checkThemeModule, formatThemeCheckResult, agentValidationResultSchema, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
 import { themeManifestSchema } from '@sudajs/theme-engine/server';
 import { Command } from 'commander';
 import { build } from 'esbuild';
@@ -402,6 +402,34 @@ var updateContactFormOutputSchema = z.discriminatedUnion("status", [
     contactForm: contactFormViewSchema
   })
 ]);
+var themeSettingsViewSchema = z.object({
+  themeKey: z.string(),
+  themeVersion: z.string(),
+  designSystem: themeDesignSystemSchema,
+  rootProps: z.record(z.unknown()),
+  schema: z.unknown()
+});
+var themeSettingsOutputSchema = z.object({
+  themeSettings: themeSettingsViewSchema
+});
+var updateThemeSettingsInputSchema = z.object({
+  projectId: z.string().min(1),
+  rootProps: z.record(z.unknown()),
+  confirm: z.boolean().optional()
+});
+var updateThemeSettingsOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("needs_confirmation"),
+    projectId: z.string(),
+    impact: z.string(),
+    draft: updateThemeSettingsInputSchema.omit({ confirm: true })
+  }),
+  z.object({
+    status: z.literal("updated"),
+    projectId: z.string(),
+    themeSettings: themeSettingsViewSchema
+  })
+]);
 var PROJECT_NAME_MIN_LENGTH = 1;
 var PROJECT_NAME_MAX_LENGTH = 80;
 var PROJECT_DESCRIPTION_MIN_LENGTH = 1;
@@ -691,6 +719,39 @@ ${issues}`);
   if (!Array.isArray(module.starterPages)) {
     throw new Error("starterPages must be an array.");
   }
+  const result = checkThemeModule(module);
+  if (!result.ok) {
+    throw new Error(formatThemeCheckResult(result));
+  }
+}
+function hasTailwindV4Dependency(dependencies, name) {
+  const value = dependencies?.[name];
+  return typeof value === "string" && /^[~^<>=\s]*4(?:[.\s<>=-]|$)/.test(value.trim());
+}
+async function validateThemeTailwindContract(root) {
+  const packageJsonPath = path2.join(root, "package.json");
+  const packageJson = await readJson(packageJsonPath);
+  const dependencyScopes = [packageJson.dependencies, packageJson.devDependencies];
+  const hasTailwind = dependencyScopes.some(
+    (dependencies) => hasTailwindV4Dependency(dependencies, "tailwindcss")
+  );
+  const hasPostcssPlugin = dependencyScopes.some(
+    (dependencies) => hasTailwindV4Dependency(dependencies, "@tailwindcss/postcss")
+  );
+  if (!hasTailwind) {
+    throw new Error("Suda themes must depend on tailwindcss v4.");
+  }
+  if (!hasPostcssPlugin) {
+    throw new Error("Suda themes must depend on @tailwindcss/postcss v4.");
+  }
+  const stylesEntry = path2.join(root, "src", "styles.css");
+  if (!await pathExists(stylesEntry)) {
+    throw new Error(`Missing ${stylesEntry}. Suda themes must define src/styles.css.`);
+  }
+  const styles = await readFile(stylesEntry, "utf8");
+  if (!styles.includes('@import "tailwindcss";') && !styles.includes("@import 'tailwindcss';")) {
+    throw new Error('src/styles.css must include `@import "tailwindcss";`.');
+  }
 }
 async function validateTheme(root) {
   const packageJsonPath = path2.join(root, "package.json");
@@ -705,6 +766,7 @@ async function validateTheme(root) {
   }
   const module = await loadThemeModule(serverEntryPath);
   validateThemeModule(module);
+  await validateThemeTailwindContract(root);
   await validateThemeLocales(root);
   const result = {
     root,
@@ -1140,12 +1202,15 @@ var __testUtils = {
   performActivateTheme,
   performConfirmedPageOperation,
   performUpdateContactForm,
+  performUpdateThemeSettings,
+  getRemoteThemeSettings,
   renderDevStarterPageHtml,
   resolveDevStarterSlug,
   resolveScreenshotOptions,
   slugifyThemeName,
   validateThemeKey,
   validateThemeName,
+  validateThemeTailwindContract,
   validateThemeLocales,
   toViteModuleUrl,
   updateRemotePageDraft
@@ -1686,16 +1751,16 @@ function printJson(value) {
   console.log(JSON.stringify(value, null, 2));
 }
 function createSectionSchema(manifest, sectionType) {
-  const section = findAgentSection(manifest, sectionType);
-  if (!section) {
+  const section = createSudaPageAgentRuntime(manifest).getSectionSchemaOutput(sectionType);
+  if (section === null) {
     throw new Error(`Unknown section type "${sectionType}".`);
   }
-  return createAgentComponentSchemaOutput(section, "section");
+  return section;
 }
 async function validateAgentPage(themeKey, input, options) {
   const manifest = await fetchAgentManifest(themeKey, options);
   const pageContent = await readJson(path2.resolve(input));
-  const result = validateAgentPageContentWithManifest(pageContent, manifest);
+  const result = createSudaPageAgentRuntime(manifest).validatePageContent(pageContent);
   printJson(agentValidationResultSchema.parse(result));
   if (!result.valid) {
     process.exitCode = 1;
@@ -1707,9 +1772,9 @@ async function createAgentPage(options) {
   }
   const pageContent = await readJson(path2.resolve(options.input));
   const manifest = await fetchAgentManifest(options.theme, options);
-  const validation = validateAgentPageContentWithManifest(pageContent, manifest);
-  if (!validation.valid) {
-    printJson(agentValidationResultSchema.parse(validation));
+  const prepared = createSudaPageAgentRuntime(manifest).preparePageData(pageContent);
+  if (!prepared.validation.valid) {
+    printJson(agentValidationResultSchema.parse(prepared.validation));
     process.exitCode = 1;
     return;
   }
@@ -1879,6 +1944,58 @@ async function performUpdateContactForm(auth, input, fetcher = fetchJson) {
     contactForm
   };
 }
+async function getRemoteThemeSettings(auth, projectId, fetcher = fetchJson) {
+  const response = await fetcher(
+    `${auth.baseUrl}/api/cli/agent/projects/${encodeURIComponent(projectId)}/theme/settings`,
+    { token: auth.token }
+  );
+  return themeSettingsViewSchema.parse(response);
+}
+async function updateRemoteThemeSettings(auth, input, fetcher = fetchJson) {
+  const response = await fetcher(
+    `${auth.baseUrl}/api/cli/agent/projects/${encodeURIComponent(input.projectId)}/theme/settings`,
+    {
+      method: "PATCH",
+      token: auth.token,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ rootProps: input.rootProps })
+    }
+  );
+  return themeSettingsViewSchema.parse(response);
+}
+function describeThemeSettingsUpdate(rootProps) {
+  const keys = Object.keys(rootProps);
+  const parts = keys.map((key) => {
+    if (key !== "designSystem") {
+      return key;
+    }
+    const value = rootProps.designSystem;
+    if (value && typeof value === "object" && !Array.isArray(value) && typeof value.presetId === "string") {
+      const presetId = value.presetId;
+      return `designSystem preset "${presetId}"`;
+    }
+    return "designSystem";
+  });
+  return parts.join(", ") || "no explicit root prop changes";
+}
+async function performUpdateThemeSettings(auth, input, fetcher = fetchJson) {
+  const draft = updateThemeSettingsInputSchema.omit({ confirm: true }).parse(input);
+  const impact = `This will update theme layout root settings for project "${input.projectId}": ${describeThemeSettingsUpdate(input.rootProps)}. Theme settings affect the public site rendering after they are saved.`;
+  if (input.confirm !== true) {
+    return {
+      status: "needs_confirmation",
+      projectId: input.projectId,
+      impact,
+      draft
+    };
+  }
+  const themeSettings = await updateRemoteThemeSettings(auth, input, fetcher);
+  return {
+    status: "updated",
+    projectId: input.projectId,
+    themeSettings
+  };
+}
 async function listAgentProjects() {
   const auth = await requireCliBaseUrl();
   const result = await fetchJson(
@@ -2005,7 +2122,7 @@ async function startMcpServer() {
   server.registerTool(
     "get_page_schema",
     {
-      description: "Return the AI-first output schema for generating Suda page content, including all section schemas. Field schemas include dynamic visibility metadata for Suda visibleIf fields. If the theme has a contact section, generate only the section placement/content props; public form fields and delivery integrations are project contact form settings exposed to themes as metadata.contactForm. Use get_contact_form_settings and update_contact_form_settings for user-approved contact form changes.",
+      description: "Return the schema for configuring existing Suda theme sections as page content. Use only the returned section types, fields, defaultProps, and slot allowedComponents; never create theme source code or new component types. If the theme has a contact section, generate only the section placement/content props; public form fields and delivery integrations are project contact form settings exposed to themes as metadata.contactForm. Use get_contact_form_settings and update_contact_form_settings for user-approved contact form changes.",
       inputSchema: {
         theme: z.string(),
         version: z.string().optional(),
@@ -2017,16 +2134,16 @@ async function startMcpServer() {
     },
     async ({ theme, version, projectId, themeRoot, includeExample }) => {
       const manifest = await fetchAgentManifest(theme, { version, projectId, themeRoot });
-      const structuredContent = createAgentPageSchemaOutput(manifest, {
+      const structuredContent = createSudaPageAgentRuntime(manifest).getPageSchemaOutput({
         includeExample: includeExample === true
       });
-      return mcpStructured("AI-first Suda page content output schema.", structuredContent);
+      return mcpStructured("Suda page content configuration schema.", structuredContent);
     }
   );
   server.registerTool(
     "get_section_schema",
     {
-      description: "Return the AI-first output schema for one section component in a theme. Field schemas include dynamic visibility metadata for Suda visibleIf fields. For contact sections, use the schema for presentation props only and do not hardcode form field metadata, notification channels, webhook URLs, or recipients into page content. Use contact form tools for project-level contact settings.",
+      description: "Return the schema for configuring one existing section in a theme. Use the returned fields, defaultProps, and slot allowedComponents to set props; do not design or add theme components. For contact sections, use the schema for presentation props only and do not hardcode form field metadata, notification channels, webhook URLs, or recipients into page content. Use contact form tools for project-level contact settings.",
       inputSchema: {
         theme: z.string(),
         section: z.string(),
@@ -2039,13 +2156,13 @@ async function startMcpServer() {
     async ({ theme, section, version, projectId, themeRoot }) => {
       const manifest = await fetchAgentManifest(theme, { version, projectId, themeRoot });
       const structuredContent = createSectionSchema(manifest, section);
-      return mcpStructured("AI-first Suda section output schema.", structuredContent);
+      return mcpStructured("Suda section configuration schema.", structuredContent);
     }
   );
   server.registerTool(
     "validate_page_config",
     {
-      description: "Validate AI-generated Suda page content against a theme.",
+      description: "Validate Suda page content JSON against an existing theme schema.",
       inputSchema: {
         theme: z.string(),
         data: z.unknown(),
@@ -2058,7 +2175,7 @@ async function startMcpServer() {
     async ({ theme, data, version, projectId, themeRoot }) => {
       const manifest = await fetchAgentManifest(theme, { version, projectId, themeRoot });
       const structuredContent = agentValidationResultSchema.parse(
-        validateAgentPageContentWithManifest(data, manifest)
+        createSudaPageAgentRuntime(manifest).validatePageContent(data)
       );
       return mcpStructured("Suda page content validation result.", structuredContent);
     }
@@ -2105,10 +2222,52 @@ async function startMcpServer() {
       );
     }
   );
+  server.registerTool(
+    "get_theme_settings",
+    {
+      description: 'Read project theme layout root settings. Use this before planning theme style changes. The result includes manifest.designSystem presets, current rootProps, and the layout root schema. To use a preset, set rootProps.designSystem to { presetId }. To fully customize colors/radius, set rootProps.designSystem to { presetId: "custom", tokens: { colors, radius } } using every token from designSystem.',
+      inputSchema: {
+        projectId: z.string()
+      },
+      outputSchema: themeSettingsOutputSchema.shape
+    },
+    async ({ projectId }) => {
+      const auth = await requireCliBaseUrl();
+      const structuredContent = themeSettingsOutputSchema.parse({
+        themeSettings: await getRemoteThemeSettings(auth, projectId)
+      });
+      return mcpStructured("Suda theme settings.", structuredContent);
+    }
+  );
+  server.registerTool(
+    "update_theme_settings",
+    {
+      description: "Plan or update project theme layout root settings. Use this for choosing a designSystem preset or saving custom design tokens for colors and radius. Conversation flow: first call get_theme_settings, then propose the exact rootProps changes to the user. Call this tool without confirm or with confirm:false to return the impact summary; only call again with confirm:true after the user explicitly agrees. Do not create theme source code or introduce a second token system.",
+      inputSchema: updateThemeSettingsInputSchema.shape,
+      outputSchema: {
+        status: z.enum(["needs_confirmation", "updated"]),
+        projectId: z.string(),
+        impact: z.string().optional(),
+        draft: updateThemeSettingsInputSchema.omit({ confirm: true }).optional(),
+        themeSettings: themeSettingsViewSchema.optional()
+      }
+    },
+    async (input) => {
+      const parsed = updateThemeSettingsInputSchema.parse(input);
+      const auth = await requireCliBaseUrl();
+      const structuredContent = updateThemeSettingsOutputSchema.parse(
+        await performUpdateThemeSettings(auth, parsed)
+      );
+      return mcpStructured(
+        structuredContent.status === "needs_confirmation" ? "Updating these theme settings requires explicit confirmation." : "Updated Suda theme settings.",
+        structuredContent
+      );
+    }
+  );
   server.registerTool(
     "create_page_draft",
     {
-      description: "Create a new workspace page draft from AI-generated Suda page content. When creating a complete website, mark exactly one primary landing page with isHome: true so it becomes the public homepage at `/`. After this tool succeeds, tell the user the page is only a draft, explain that they can review it in the SudaCloud workspace by navigating to Pages, opening the created page, previewing it, then clicking Publish, and ask whether they want you to publish it now. Do not call publish_page until the user explicitly confirms.",
+      description: "Create a new workspace page draft from Suda page content JSON that configures existing theme sections. When creating a complete website, mark exactly one primary landing page with isHome: true so it becomes the public homepage at `/`. After this tool succeeds, tell the user the page is only a draft, explain that they can review it in the SudaCloud workspace by navigating to Pages, opening the created page, previewing it, then clicking Publish, and ask whether they want you to publish it now. Do not call publish_page until the user explicitly confirms.",
       inputSchema: {
         projectId: z.string(),
         title: z.string(),
@@ -2122,14 +2281,14 @@ async function startMcpServer() {
     },
     async ({ projectId, title, slug, isHome, theme, data, version }) => {
       const manifest = await fetchAgentManifest(theme, { version, projectId });
-      const validation = validateAgentPageContentWithManifest(data, manifest);
-      if (!validation.valid) {
+      const prepared = createSudaPageAgentRuntime(manifest).preparePageData(data);
+      if (!prepared.validation.valid) {
         return mcpStructured(
           "Suda page content validation failed. Fix issues before creating a draft.",
           createPageDraftOutputSchema.parse({
             status: "invalid",
             valid: false,
-            issues: validation.issues
+            issues: prepared.validation.issues
           })
         );
       }
@@ -2152,7 +2311,7 @@ async function startMcpServer() {
   server.registerTool(
     "update_page_draft",
     {
-      description: "Update an existing workspace page draft by slug from AI-generated Suda page content.",
+      description: "Update an existing workspace page draft by slug from Suda page content JSON that configures existing theme sections.",
       inputSchema: {
         projectId: z.string(),
         slug: z.string(),
@@ -2164,14 +2323,14 @@ async function startMcpServer() {
     },
     async ({ projectId, slug, theme, data, version }) => {
       const manifest = await fetchAgentManifest(theme, { version, projectId });
-      const validation = validateAgentPageContentWithManifest(data, manifest);
-      if (!validation.valid) {
+      const prepared = createSudaPageAgentRuntime(manifest).preparePageData(data);
+      if (!prepared.validation.valid) {
         return mcpStructured(
           "Suda page content validation failed. Fix issues before updating a draft.",
           updatePageDraftOutputSchema.parse({
             status: "invalid",
             valid: false,
-            issues: validation.issues
+            issues: prepared.validation.issues
           })
         );
       }
@@ -2282,6 +2441,11 @@ async function writeThemeArtifacts(theme) {
   await writeFile(
     path2.join(dist, "starter-pages.json"),
     `${JSON.stringify(theme.module.starterPages, null, 2)}
+`
+  );
+  await writeFile(
+    path2.join(dist, "cms-templates.json"),
+    `${JSON.stringify(theme.module.cmsTemplates, null, 2)}
 `
   );
   await writeFile(
@@ -2800,20 +2964,24 @@ function buildProgram() {
     printJson({ themes });
   });
   const agentTheme = agent.command("theme").description("Inspect a single theme.");
-  agentTheme.command("describe").description("Describe a theme's AI-first page schema.").argument("<theme>", "Theme key.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").option("--example", "Include example page content.").action(async (themeKey, options) => {
+  agentTheme.command("describe").description("Describe a theme's page content configuration schema.").argument("<theme>", "Theme key.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").option("--example", "Include example page content.").action(async (themeKey, options) => {
     const manifest = await fetchAgentManifest(themeKey, options);
     printJson(
-      createAgentPageSchemaOutput(manifest, { includeExample: options.example === true })
+      createSudaPageAgentRuntime(manifest).getPageSchemaOutput({
+        includeExample: options.example === true
+      })
     );
   });
-  const agentPage = agent.command("page").description("AI-first page content tooling.");
-  agentPage.command("schema").description("Print the AI-first page content output schema for a theme.").argument("<theme>", "Theme key.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").option("--example", "Include example page content.").action(async (themeKey, options) => {
+  const agentPage = agent.command("page").description("Page content configuration tooling.");
+  agentPage.command("schema").description("Print the page content configuration schema for a theme.").argument("<theme>", "Theme key.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").option("--example", "Include example page content.").action(async (themeKey, options) => {
     const manifest = await fetchAgentManifest(themeKey, options);
     printJson(
-      createAgentPageSchemaOutput(manifest, { includeExample: options.example === true })
+      createSudaPageAgentRuntime(manifest).getPageSchemaOutput({
+        includeExample: options.example === true
+      })
     );
   });
-  agentPage.command("validate").description("Validate an AI-generated Suda page content JSON document.").requiredOption("--theme <theme>", "Theme key.").requiredOption("--input <file>", "JSON file containing Suda page content.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").action(async (options) => {
+  agentPage.command("validate").description("Validate a Suda page content JSON document.").requiredOption("--theme <theme>", "Theme key.").requiredOption("--input <file>", "JSON file containing Suda page content.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").action(async (options) => {
     await validateAgentPage(options.theme, options.input, options);
   });
   agentPage.command("create").description(
@@ -2822,7 +2990,7 @@ function buildProgram() {
     await createAgentPage(options);
   });
   const agentSection = agent.command("section").description("Inspect a single section.");
-  agentSection.command("schema").description("Print one AI-first section output schema for a theme.").requiredOption("--theme <theme>", "Theme key.").requiredOption("--section <section>", "Section type.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").action(async (options) => {
+  agentSection.command("schema").description("Print one section configuration schema for a theme.").requiredOption("--theme <theme>", "Theme key.").requiredOption("--section <section>", "Section type.").option("--version <version>", "Theme version.").option("--project-id <projectId>", "Project scope.").option("--theme-root <path>", "Read a local theme.").action(async (options) => {
     const manifest = await fetchAgentManifest(options.theme, options);
     printJson(createSectionSchema(manifest, options.section));
   });