@sudajs/cli 0.0.2 → 0.1.0

package/dist/index.js

@@ -3,11 +3,15 @@ import { createHash } from 'crypto';
 import fs, { mkdir, writeFile, readFile, stat, readdir } from 'fs/promises';
 import path2 from 'path';
 import { pathToFileURL } from 'url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createAgentPageSchemaOutput, createThemeAgentManifest, validateAgentPageContentWithManifest, agentValidationResultSchema, createPageDataFromAgentContent, findAgentSection, createAgentComponentSchemaOutput, agentPageSchemaOutputSchema, agentComponentOutputSchema } from '@sudajs/theme-engine';
 import { extractLayoutChrome, ThemeRender } from '@sudajs/theme-engine/server';
 import { Command } from 'commander';
 import { build, context } from 'esbuild';
 import { createElement } from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
+import { z } from 'zod';
 import os from 'os';
 
 function getConfigPath() {
@@ -38,7 +42,7 @@ async function clearAuthConfig() {
     }
   }
 }
-async function login(host = "workspace.sudacloud.com") {
+async function login(host = "app.sudayun.cn") {
   const protocol = host.includes("localhost") || host.includes("127.0.0.1") ? "http" : "https";
   const baseUrl = `${protocol}://${host}`;
   console.log(`Requesting device authorization from ${baseUrl}...`);
@@ -120,6 +124,22 @@ async function logout() {
 }
 
 // src/index.ts
+var createPageDraftOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("created").describe("The page draft was created."),
+    pageId: z.string().describe("New page id.")
+  }),
+  z.object({
+    status: z.literal("invalid").describe("The page content failed validation."),
+    valid: z.literal(false),
+    issues: z.array(
+      z.object({
+        path: z.string(),
+        message: z.string()
+      })
+    )
+  })
+]);
 function createHostReactShimPlugin() {
   return {
     name: "suda-host-react-shim",
@@ -266,6 +286,43 @@ async function readJson(filePath) {
   const raw = await readFile(filePath, "utf8");
   return JSON.parse(raw);
 }
+async function readJsonIfExists(filePath) {
+  if (!await pathExists(filePath)) {
+    return null;
+  }
+  return readJson(filePath);
+}
+function protocolForHost(host) {
+  return host.includes("localhost") || host.includes("127.0.0.1") ? "http" : "https";
+}
+async function requireCliBaseUrl() {
+  const config = await readAuthConfig();
+  if (!config) {
+    throw new Error("Not logged in. Run `suda auth login` to authenticate first.");
+  }
+  return {
+    baseUrl: `${protocolForHost(config.host)}://${config.host}`,
+    token: config.sessionToken
+  };
+}
+async function fetchJson(url, options = {}) {
+  const headers = new Headers(options.headers);
+  if (options.token) {
+    headers.set("Authorization", `Bearer ${options.token}`);
+  }
+  const response = await fetch(url, { ...options, headers });
+  if (!response.ok) {
+    const errorData = await response.json().catch(() => ({}));
+    throw new Error(errorData.message || errorData.error || response.statusText);
+  }
+  return await response.json();
+}
+function agentCacheDir() {
+  return path2.join(process.env.XDG_CACHE_HOME ?? path2.join(process.env.HOME ?? ".", ".cache"), "suda", "agent");
+}
+function cachedThemeManifestPath(themeKey, version) {
+  return path2.join(agentCacheDir(), "themes", safeObjectKeyPart(themeKey), safeObjectKeyPart(version), "agent-manifest.json");
+}
 async function loadThemeModule(serverEntryPath) {
   const imported = await import(`${pathToFileURL(serverEntryPath).href}?t=${Date.now()}`);
   if (!imported.default) {
@@ -617,8 +674,292 @@ async function screenshotTheme(root, options) {
   const theme = resolved.skipBuild ? await validateTheme(root) : await buildTheme(root, false);
   await captureScreenshot(theme, resolved);
 }
+async function loadLocalAgentManifest(root) {
+  const built = await readJsonIfExists(path2.join(root, "dist", "agent-manifest.json"));
+  if (built) {
+    return built;
+  }
+  throw new Error(
+    `No agent manifest found at ${path2.join(root, "dist", "agent-manifest.json")}. Run "suda theme build" first.`
+  );
+}
+async function listAgentThemes(options) {
+  if (options.themeRoot) {
+    const manifest = await loadLocalAgentManifest(resolveThemeRoot(options));
+    return [
+      {
+        key: manifest.manifest.key,
+        name: manifest.manifest.name,
+        version: manifest.manifest.version,
+        description: manifest.manifest.description ?? null,
+        categories: manifest.manifest.categories,
+        preview: manifest.manifest.preview
+      }
+    ];
+  }
+  const auth = await requireCliBaseUrl();
+  const url = new URL("/api/cli/agent/themes", auth.baseUrl);
+  if (options.projectId) {
+    url.searchParams.set("projectId", options.projectId);
+  }
+  const catalog = await fetchJson(url.href, { token: auth.token });
+  await mkdir(agentCacheDir(), { recursive: true });
+  await writeFile(path2.join(agentCacheDir(), "catalog.json"), `${JSON.stringify(catalog, null, 2)}
+`);
+  return catalog.themes;
+}
+async function fetchAgentManifest(themeKey, options) {
+  if (options.themeRoot) {
+    return loadLocalAgentManifest(resolveThemeRoot(options));
+  }
+  const auth = await requireCliBaseUrl();
+  const version = options.version ?? "latest";
+  const cachePath = cachedThemeManifestPath(themeKey, version);
+  const cached = version === "latest" ? null : await readJsonIfExists(cachePath);
+  if (cached) {
+    return cached;
+  }
+  const url = new URL(`/api/cli/agent/themes/${encodeURIComponent(themeKey)}/${encodeURIComponent(version)}/schema`, auth.baseUrl);
+  if (options.projectId) {
+    url.searchParams.set("projectId", options.projectId);
+  }
+  const result = await fetchJson(url.href, { token: auth.token });
+  const realVersion = result.agentManifest.manifest.version;
+  const realCachePath = cachedThemeManifestPath(themeKey, realVersion);
+  await mkdir(path2.dirname(realCachePath), { recursive: true });
+  await writeFile(realCachePath, `${JSON.stringify(result.agentManifest, null, 2)}
+`);
+  return result.agentManifest;
+}
+function printJson(value) {
+  console.log(JSON.stringify(value, null, 2));
+}
+function createSectionSchema(manifest, sectionType) {
+  const section = findAgentSection(manifest, sectionType);
+  if (!section) {
+    throw new Error(`Unknown section type "${sectionType}".`);
+  }
+  return createAgentComponentSchemaOutput(section, "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);
+  printJson(agentValidationResultSchema.parse(result));
+  if (!result.valid) {
+    process.exitCode = 1;
+  }
+}
+async function createAgentPage(options) {
+  if (!options.projectId) {
+    throw new Error("--project-id is required.");
+  }
+  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));
+    process.exitCode = 1;
+    return;
+  }
+  const pageData = createPageDataFromAgentContent(pageContent);
+  const auth = await requireCliBaseUrl();
+  const response = await fetchJson(
+    `${auth.baseUrl}/api/cli/agent/projects/${encodeURIComponent(options.projectId)}/pages`,
+    {
+      method: "POST",
+      token: auth.token,
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        title: options.title,
+        slug: options.slug,
+        themeKey: manifest.manifest.key,
+        themeVersion: manifest.manifest.version,
+        data: pageData
+      })
+    }
+  );
+  printJson({ success: true, ...response });
+}
+function mcpStructured(summary, value) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: summary
+      }
+    ],
+    structuredContent: value
+  };
+}
+async function startMcpServer() {
+  const server = new McpServer({
+    name: "suda",
+    version: "0.1.0"
+  });
+  server.registerTool(
+    "list_themes",
+    {
+      description: "List themes visible to the current Suda CLI user.",
+      inputSchema: {
+        projectId: z.string().optional(),
+        themeRoot: z.string().optional()
+      },
+      outputSchema: {
+        themes: z.array(
+          z.object({
+            key: z.string(),
+            name: z.string(),
+            version: z.string(),
+            description: z.string().nullable().optional(),
+            categories: z.array(z.string()).optional(),
+            preview: z.string().optional(),
+            active: z.boolean().optional()
+          })
+        )
+      }
+    },
+    async ({ projectId, themeRoot }) => {
+      const structuredContent = { themes: await listAgentThemes({ projectId, themeRoot }) };
+      return mcpStructured("Available Suda themes.", structuredContent);
+    }
+  );
+  server.registerTool(
+    "describe_theme",
+    {
+      description: "Return the raw Suda agent manifest for a theme.",
+      inputSchema: {
+        theme: z.string(),
+        version: z.string().optional(),
+        projectId: z.string().optional(),
+        themeRoot: z.string().optional()
+      },
+      outputSchema: {
+        agentManifest: z.unknown()
+      }
+    },
+    async ({ theme, version, projectId, themeRoot }) => {
+      const structuredContent = {
+        agentManifest: await fetchAgentManifest(theme, { version, projectId, themeRoot })
+      };
+      return mcpStructured("Raw Suda theme agent manifest.", structuredContent);
+    }
+  );
+  server.registerTool(
+    "get_page_schema",
+    {
+      description: "Return the AI-first output schema for generating Suda page content, including all section schemas.",
+      inputSchema: {
+        theme: z.string(),
+        version: z.string().optional(),
+        projectId: z.string().optional(),
+        themeRoot: z.string().optional(),
+        includeExample: z.boolean().optional()
+      },
+      outputSchema: agentPageSchemaOutputSchema.shape
+    },
+    async ({ theme, version, projectId, themeRoot, includeExample }) => {
+      const manifest = await fetchAgentManifest(theme, { version, projectId, themeRoot });
+      const structuredContent = createAgentPageSchemaOutput(manifest, {
+        includeExample: includeExample === true
+      });
+      return mcpStructured("AI-first Suda page content output schema.", structuredContent);
+    }
+  );
+  server.registerTool(
+    "get_section_schema",
+    {
+      description: "Return the AI-first output schema for one section component in a theme.",
+      inputSchema: {
+        theme: z.string(),
+        section: z.string(),
+        version: z.string().optional(),
+        projectId: z.string().optional(),
+        themeRoot: z.string().optional()
+      },
+      outputSchema: agentComponentOutputSchema.shape
+    },
+    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);
+    }
+  );
+  server.registerTool(
+    "validate_page_config",
+    {
+      description: "Validate AI-generated Suda page content against a theme.",
+      inputSchema: {
+        theme: z.string(),
+        data: z.unknown(),
+        version: z.string().optional(),
+        projectId: z.string().optional(),
+        themeRoot: z.string().optional()
+      },
+      outputSchema: agentValidationResultSchema.shape
+    },
+    async ({ theme, data, version, projectId, themeRoot }) => {
+      const manifest = await fetchAgentManifest(theme, { version, projectId, themeRoot });
+      const structuredContent = agentValidationResultSchema.parse(
+        validateAgentPageContentWithManifest(data, manifest)
+      );
+      return mcpStructured("Suda page content validation result.", structuredContent);
+    }
+  );
+  server.registerTool(
+    "create_page_draft",
+    {
+      description: "Create a workspace page draft from AI-generated Suda page content.",
+      inputSchema: {
+        projectId: z.string(),
+        title: z.string(),
+        slug: z.string(),
+        theme: z.string(),
+        data: z.unknown(),
+        version: z.string().optional()
+      },
+      outputSchema: createPageDraftOutputSchema
+    },
+    async ({ projectId, title, slug, theme, data, version }) => {
+      const manifest = await fetchAgentManifest(theme, { version, projectId });
+      const validation = validateAgentPageContentWithManifest(data, manifest);
+      if (!validation.valid) {
+        return mcpStructured(
+          "Suda page content validation failed. Fix issues before creating a draft.",
+          createPageDraftOutputSchema.parse({
+            status: "invalid",
+            valid: false,
+            issues: validation.issues
+          })
+        );
+      }
+      const auth = await requireCliBaseUrl();
+      const response = await fetchJson(
+        `${auth.baseUrl}/api/cli/agent/projects/${encodeURIComponent(projectId)}/pages`,
+        {
+          method: "POST",
+          token: auth.token,
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            title,
+            slug,
+            themeKey: manifest.manifest.key,
+            themeVersion: manifest.manifest.version,
+            data: createPageDataFromAgentContent(data)
+          })
+        }
+      );
+      return mcpStructured(
+        "Created Suda page draft.",
+        createPageDraftOutputSchema.parse({ status: "created", ...response })
+      );
+    }
+  );
+  await server.connect(new StdioServerTransport());
+}
 async function writeThemeArtifacts(theme) {
   const dist = path2.join(theme.root, "dist");
+  const agentManifest = createThemeAgentManifest(theme.module);
   await writeFile(
     path2.join(dist, "manifest.json"),
     `${JSON.stringify(theme.module.manifest, null, 2)}
@@ -632,6 +973,11 @@ async function writeThemeArtifacts(theme) {
   await writeFile(
     path2.join(dist, "default-layout.json"),
     `${JSON.stringify(theme.module.defaultLayout, null, 2)}
+`
+  );
+  await writeFile(
+    path2.join(dist, "agent-manifest.json"),
+    `${JSON.stringify(agentManifest, null, 2)}
 `
   );
 }
@@ -709,8 +1055,7 @@ async function publishTheme(root, skipBuild) {
   if (!config) {
     throw new Error("Not logged in. Run `suda auth login` to authenticate first.");
   }
-  const protocol = config.host.includes("localhost") || config.host.includes("127.0.0.1") ? "http" : "https";
-  const baseUrl = `${protocol}://${config.host}`;
+  const baseUrl = `${protocolForHost(config.host)}://${config.host}`;
   const { key, version } = theme.module.manifest;
   const intentRes = await fetch(`${baseUrl}/api/cli/themes/publish-intent`, {
     method: "POST",
@@ -755,6 +1100,7 @@ async function publishTheme(root, skipBuild) {
   }
   const previewArtifactRelative = "dist/preview/desktop.png";
   const previewArtifactExists = await pathExists(path2.join(theme.root, previewArtifactRelative));
+  const agentManifest = createThemeAgentManifest(theme.module);
   const completeRes = await fetch(`${baseUrl}/api/cli/themes/publish-complete`, {
     method: "POST",
     headers: {
@@ -766,6 +1112,7 @@ async function publishTheme(root, skipBuild) {
       version,
       checksum: digest,
       manifest: theme.module.manifest,
+      agentManifest,
       bundleArtifactRelative,
       previewArtifactRelative: previewArtifactExists ? previewArtifactRelative : void 0
     })
@@ -834,22 +1181,109 @@ export const Hero: ComponentConfig = {
     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 }) => (
-    <section className="${key}-hero">
-      <p>{eyebrow}</p>
+  render: ({ eyebrow, title, description, primaryLabel, primaryHref }) => (
+    <section className="${key}-section ${key}-hero">
+      <p className="${key}-eyebrow">{eyebrow}</p>
       <h1>{title}</h1>
-      <div>{description}</div>
+      <p>{description}</p>
+      <a className="${key}-button" href={primaryHref}>{primaryLabel}</a>
+    </section>
+  ),
+};
+
+export const FeatureGrid: ComponentConfig = {
+  label: "Feature grid",
+  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 SECTION_COMPONENTS = { Hero };
+export const Testimonial: ComponentConfig = {
+  label: "Testimonial",
+  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: ComponentConfig = {
+  label: "Call to action",
+  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(
@@ -939,6 +1373,90 @@ export const starterPages: ThemeStarterPage[] = [
             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",
           },
         },
       ],
@@ -971,8 +1489,67 @@ export { manifest, pageConfig, layoutConfig, defaultLayout, starterPages };
     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"), "\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\`.
+
+## 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\`.
+
+## 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.
+
+## Useful commands
+
+\`\`\`bash
+suda theme build
+suda theme validate
+suda theme preview
+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}
@@ -982,10 +1559,19 @@ A Suda theme scaffolded with \`suda theme init\`.
 ## Develop
 
 \`\`\`bash
+suda theme build
 suda theme dev      # rebuild the browser runtime on change
 suda theme preview  # build and preview the home starter page
 \`\`\`
 
+## 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
@@ -997,7 +1583,7 @@ suda theme publish
   );
   console.log(`created theme scaffold at ${target}`);
 }
-async function main() {
+function buildProgram() {
   const program = new Command();
   program.name("suda").description("Suda CLI for managing themes, sites, posts and AI tooling.").version("0.0.0");
   const theme = program.command("theme").description("Manage Suda theme artifacts.");
@@ -1032,8 +1618,38 @@ async function main() {
   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.").action(async (options) => {
     await publishTheme(resolveThemeRoot(options), options.skipBuild === true);
   });
+  const agent = program.command("agent").description("Agent-friendly theme and page tooling.");
+  const agentThemes = agent.command("themes").description("Manage agent-visible themes.");
+  agentThemes.command("list").description("List themes visible to the current CLI user.").option("--project-id <projectId>", "Scope results to a project.").option("--theme-root <path>", "Describe a local theme instead of the remote catalog.").action(async (options) => {
+    const themes = await listAgentThemes(options);
+    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) => {
+    const manifest = await fetchAgentManifest(themeKey, options);
+    printJson(createAgentPageSchemaOutput(manifest, { 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 manifest = await fetchAgentManifest(themeKey, options);
+    printJson(createAgentPageSchemaOutput(manifest, { 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) => {
+    await validateAgentPage(options.theme, options.input, options);
+  });
+  agentPage.command("create").description("Create a workspace page draft from AI-generated Suda page content JSON.").requiredOption("--project-id <projectId>", "Project id.").requiredOption("--title <title>", "Page title.").requiredOption("--slug <slug>", "Page slug.").requiredOption("--theme <theme>", "Theme key.").requiredOption("--input <file>", "JSON file containing Suda page content.").option("--version <version>", "Theme version.").action(async (options) => {
+    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) => {
+    const manifest = await fetchAgentManifest(options.theme, options);
+    printJson(createSectionSchema(manifest, options.section));
+  });
+  program.command("mcp").description("Run the Suda local MCP server over stdio.").action(async () => {
+    await startMcpServer();
+  });
   const authCmd = program.command("auth").description("Manage Suda authentication.");
-  authCmd.command("login").description("Authenticate Suda CLI with a SudaCloud workspace.").option("--host <host>", "The SudaCloud workspace host to authenticate against.", "workspace.sudacloud.com").action(async (options) => {
+  authCmd.command("login").description("Authenticate Suda CLI with a SudaCloud workspace.").option("--host <host>", "The SudaCloud workspace host to authenticate against.", "app.sudayun.cn").action(async (options) => {
     await login(options.host);
   });
   authCmd.command("status").description("Check current authentication status.").action(async () => {
@@ -1043,12 +1659,14 @@ async function main() {
     await logout();
   });
   program.showHelpAfterError();
+  return program;
+}
+async function main() {
+  const program = buildProgram();
   const argv = process.argv.filter((arg, index) => index < 2 || arg !== "--");
   await program.parseAsync(argv);
 }
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : error);
-  process.exitCode = 1;
-});
+
+export { buildProgram, main };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map