@sudajs/cli 0.5.5 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sudajs/cli",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "type": "module",
   "bin": {
     "suda": "./bin/suda.js"
@@ -17,7 +17,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "templates"
   ],
   "publishConfig": {
     "access": "public"
@@ -31,15 +32,20 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^3.24.1",
-    "@sudajs/theme-engine": "1.6.1"
+    "@sudajs/theme-engine": "2.0.0"
   },
   "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.0",
     "@types/node": "^22.10.2",
     "@types/react": "^19.0.2",
     "@types/react-dom": "^19.0.2",
+    "@vitejs/plugin-react": "^5.1.2",
     "eslint": "^9.17.0",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.0",
     "tsx": "^4.22.3",
     "typescript": "^5.7.2",
+    "vite": "^7.3.3",
     "vitest": "^3.2.4",
     "@suda/build-config": "0.0.0",
     "@suda/eslint-config": "0.0.0",

package/templates/theme/AGENTS.md

@@ -0,0 +1,30 @@
+# Suda Theme Agent Guide
+
+This directory is a standalone Vite + React + Tailwind Suda theme generated by `suda theme init`.
+
+## Contract
+
+- Keep `renderMode: "ssr"` in `src/manifest.ts`.
+- Keep source entries at `src/index.tsx`, `src/runtime.client.ts`, and `src/styles.css`.
+- Do not edit generated files under `dist/`, root `manifest.json`, or root `styles.css`; run `pnpm build` to regenerate them.
+- React, React DOM, Puck, and `@sudajs/theme-engine` are host-provided peers. Do not bundle private copies into the theme runtime.
+
+## Styling
+
+- Tailwind v4 starts in `src/styles.css` with `@import "tailwindcss";` and `@source "./**/*.{ts,tsx}";`.
+- Customize `vite.config.ts`, `postcss.config.mjs`, and `src/styles.css` as needed.
+
+## Commands
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm dev       # Vite-powered local preview
+pnpm build     # Vite build + Suda artifact finalize + AI metadata check
+pnpm validate
+suda theme check
+```
+
+## AI metadata
+
+Every component and layout component should declare useful `ai.instructions`. Missing component-level instructions fail `suda theme check` and block publish.

package/templates/theme/CLAUDE.md

@@ -0,0 +1,3 @@
+# Claude Code
+
+Read `AGENTS.md` first. It is the canonical guide for this Suda theme project.

package/templates/theme/README.md

@@ -0,0 +1,28 @@
+# **SUDA_THEME_KEY**
+
+A standalone Vite + React + Tailwind Suda theme scaffolded with `suda theme init`.
+
+## Setup
+
+```bash
+pnpm install
+```
+
+## Develop
+
+```bash
+pnpm dev
+pnpm typecheck
+pnpm build
+pnpm validate
+```
+
+`pnpm dev` starts the Vite-powered preview. `pnpm build` produces the Suda artifact contract: `dist/index.js`, `dist/runtime.client.js`, root `manifest.json`, and root `styles.css`.
+
+## Publish
+
+```bash
+pnpm build
+suda theme screenshot   # optional
+suda theme publish
+```

package/templates/theme/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@suda-themes/__SUDA_THEME_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": "suda theme build --theme-root .",
+    "dev": "suda theme dev --theme-root .",
+    "finalize": "suda theme finalize --theme-root .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "validate": "suda theme validate --theme-root ."
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.0",
+    "@puckeditor/core": "^0.21.2",
+    "@sudajs/cli": "*",
+    "@sudajs/theme-engine": "*",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^5.1.2",
+    "postcss": "^8.5.15",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^5.6.0",
+    "vite": "^7.3.3"
+  },
+  "peerDependencies": {
+    "@puckeditor/core": "^0.21.2",
+    "@sudajs/theme-engine": "*",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  }
+}

package/templates/theme/pnpm-workspace.yaml

@@ -0,0 +1,8 @@
+# This is NOT a monorepo marker — 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:
+  '@tailwindcss/oxide': true
+  esbuild: true

package/templates/theme/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/templates/theme/src/config.ts

@@ -0,0 +1,22 @@
+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: "__SUDA_THEME_KEY__" } },
+  content: [
+    { type: "Header", props: { id: "Header-1", siteName: "__SUDA_THEME_KEY__" } },
+    { type: "PageOutlet", props: { id: "PageOutlet-1" } },
+    { type: "Footer", props: { id: "Footer-1", text: "© __SUDA_THEME_KEY__" } },
+  ],
+};

package/templates/theme/src/index.tsx

@@ -0,0 +1,23 @@
+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 };

package/templates/theme/src/layout.tsx

@@ -0,0 +1,76 @@
+import type { Config } from "@puckeditor/core";
+import type { SudaComponentConfig } from "@sudajs/theme-engine";
+import { getIcpRecord, getPageSlot, getWhiteLabel } from "@sudajs/theme-engine/runtime";
+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: "__SUDA_THEME_KEY__" },
+  render: ({ children, siteName }: { children?: ReactNode; siteName?: string }) => (
+    <div className="__SUDA_THEME_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: "__SUDA_THEME_KEY__" },
+  render: ({ siteName }) => <header className="__SUDA_THEME_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 — not for primary CTAs.",
+  },
+  fields: { text: { type: "text", label: "Text" } },
+  defaultProps: { text: "© __SUDA_THEME_KEY__" },
+  render: ({ text, puck }: { text?: string } & PuckExtras) => {
+    const whiteLabel = getWhiteLabel(puck?.metadata);
+    const icp = getIcpRecord(puck?.metadata);
+    return (
+      <footer className="__SUDA_THEME_KEY__-footer">
+        <span>{text}</span>
+        {whiteLabel?.visible ? (
+          <a href={whiteLabel.href} target="_blank" rel="noreferrer">
+            {whiteLabel.logo ? <img src={whiteLabel.logo} alt="" /> : null}
+            <span dangerouslySetInnerHTML={{ __html: whiteLabel.text }} />
+          </a>
+        ) : null}
+        {icp ? (
+          <a href={icp.href} target="_blank" rel="noreferrer">
+            {icp.text}
+          </a>
+        ) : null}
+      </footer>
+    );
+  },
+};
+
+export const LAYOUT_COMPONENTS = { Header, PageOutlet, Footer };

package/templates/theme/src/manifest.ts

@@ -0,0 +1,18 @@
+import type { ThemeSourceManifest } from "@sudajs/theme-engine";
+
+// Source-side manifest — 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: "__SUDA_THEME_KEY__",
+  name: "__SUDA_THEME_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",
+};

package/templates/theme/src/runtime.client.ts

@@ -0,0 +1,5 @@
+"use client";
+
+import theme from "./index.js";
+
+export default theme;

package/templates/theme/src/sections.tsx

@@ -0,0 +1,161 @@
+import type { SudaComponentConfig } from "@sudajs/theme-engine";
+
+type FeatureItem = { title?: string; description?: string };
+type HeroProps = {
+  eyebrow?: string;
+  title?: string;
+  description?: string;
+  primaryLabel?: string;
+  primaryHref?: string;
+};
+type FeatureGridProps = {
+  title?: string;
+  description?: string;
+  features?: FeatureItem[];
+};
+type TestimonialProps = {
+  quote?: string;
+  author?: string;
+  role?: string;
+};
+type CallToActionProps = {
+  title?: string;
+  description?: string;
+  buttonLabel?: string;
+  buttonHref?: string;
+};
+
+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 }: HeroProps) => (
+    <section className="__SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-hero">
+      <p className="__SUDA_THEME_KEY__-eyebrow">{eyebrow}</p>
+      <h1>{title}</h1>
+      <p>{description}</p>
+      <a className="__SUDA_THEME_KEY__-button" href={primaryHref}>{primaryLabel}</a>
+    </section>
+  ),
+};
+
+export const FeatureGrid: SudaComponentConfig = {
+  label: "Feature grid",
+  ai: {
+    instructions:
+      "Section that lists 3–6 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 = [] }: FeatureGridProps) => (
+    <section className="__SUDA_THEME_KEY__-section">
+      <h2>{title}</h2>
+      <p>{description}</p>
+      <div className="__SUDA_THEME_KEY__-grid">
+        {features.map((feature: FeatureItem, index: number) => (
+          <article className="__SUDA_THEME_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 }: TestimonialProps) => (
+    <section className="__SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-quote">
+      <blockquote>{quote}</blockquote>
+      <p>{author} · {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 — 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 }: CallToActionProps) => (
+    <section className="__SUDA_THEME_KEY__-section __SUDA_THEME_KEY__-cta" id="contact">
+      <h2>{title}</h2>
+      <p>{description}</p>
+      <a className="__SUDA_THEME_KEY__-button" href={buttonHref}>{buttonLabel}</a>
+    </section>
+  ),
+};
+
+export const SECTION_COMPONENTS = { Hero, FeatureGrid, Testimonial, CallToAction };

package/templates/theme/src/styles.css

@@ -0,0 +1,102 @@
+@import "tailwindcss";
+@source "./**/*.{ts,tsx}";
+
+.__SUDA_THEME_KEY__-root {
+  font-family: Inter, ui-sans-serif, system-ui, sans-serif;
+  color: #111827;
+  background: #ffffff;
+}
+.__SUDA_THEME_KEY__-header,
+.__SUDA_THEME_KEY__-footer {
+  padding: 20px clamp(20px, 5vw, 64px);
+  border-bottom: 1px solid #e5e7eb;
+}
+.__SUDA_THEME_KEY__-footer {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 12px 20px;
+  border-top: 1px solid #e5e7eb;
+  border-bottom: 0;
+  color: #6b7280;
+}
+.__SUDA_THEME_KEY__-footer a {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  color: inherit;
+  text-decoration: none;
+}
+.__SUDA_THEME_KEY__-footer img {
+  height: 16px;
+  width: auto;
+}
+.__SUDA_THEME_KEY__-section {
+  padding: 64px clamp(20px, 5vw, 64px);
+}
+.__SUDA_THEME_KEY__-hero {
+  background: #f8fafc;
+}
+.__SUDA_THEME_KEY__-eyebrow {
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  font-size: 12px;
+  color: #2563eb;
+  font-weight: 700;
+}
+.__SUDA_THEME_KEY__-section h1 {
+  max-width: 780px;
+  font-size: clamp(40px, 7vw, 72px);
+  line-height: 0.95;
+  margin: 0 0 20px;
+}
+.__SUDA_THEME_KEY__-section h2 {
+  max-width: 720px;
+  font-size: 36px;
+  line-height: 1.05;
+  margin: 0 0 16px;
+}
+.__SUDA_THEME_KEY__-section p {
+  max-width: 680px;
+  line-height: 1.7;
+  color: #4b5563;
+}
+.__SUDA_THEME_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;
+}
+.__SUDA_THEME_KEY__-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 16px;
+  margin-top: 28px;
+}
+.__SUDA_THEME_KEY__-card {
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  padding: 20px;
+}
+.__SUDA_THEME_KEY__-quote blockquote {
+  max-width: 780px;
+  font-size: 28px;
+  line-height: 1.25;
+  margin: 0 0 16px;
+}
+.__SUDA_THEME_KEY__-cta {
+  background: #111827;
+  color: #ffffff;
+}
+.__SUDA_THEME_KEY__-cta p {
+  color: #d1d5db;
+}
+.__SUDA_THEME_KEY__-cta .__SUDA_THEME_KEY__-button {
+  background: #ffffff;
+  color: #111827;
+}

package/templates/theme/src/templates.ts

@@ -0,0 +1,107 @@
+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 __SUDA_THEME_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",
+          },
+        },
+      ],
+    },
+  },
+];