@ikas/component-cli 0.83.0 → 0.86.0

package/dist/commands/create.js

@@ -5,6 +5,7 @@ import inquirer from "inquirer";
 import ora from "ora";
 import * as path from "path";
 import { generateComponentId, generateProjectId } from "../utils/component-helpers.js";
+import { readTemplate } from "../utils/template.js";
 const PROP_TYPES = [
     "TEXT",
     "NUMBER",
@@ -41,801 +42,41 @@ async function createProject(projectName) {
         fs.mkdirSync(projectPath, { recursive: true });
         fs.mkdirSync(path.join(projectPath, "src/components/ExampleComponent"), { recursive: true });
         fs.mkdirSync(path.join(projectPath, "src/components/ExampleSection"), { recursive: true });
-        // Create package.json
-        const packageJson = {
-            name: projectName,
-            version: "1.0.0",
-            type: "module",
-            scripts: {
-                dev: "ikas-component dev",
-                build: "ikas-component build",
-                add: "ikas-component add",
-                publish: "ikas-component publish"
-            },
-            dependencies: {
-                preact: "^10.19.3"
-            },
-            devDependencies: {
-                "@ikas/component-cli": "*",
-                "@ikas/bp-storefront": "*",
-                "@ikas/code-components-mcp": "*",
-                typescript: "^5.3.0",
-                vite: "^5.0.0"
-            }
-        };
-        fs.writeFileSync(path.join(projectPath, "package.json"), JSON.stringify(packageJson, null, 2));
-        // Create tsconfig.json
-        const tsConfig = {
-            compilerOptions: {
-                target: "ES2022",
-                lib: ["DOM", "DOM.Iterable", "ES2022"],
-                module: "ESNext",
-                moduleResolution: "bundler",
-                jsx: "react-jsx",
-                jsxImportSource: "preact",
-                strict: true,
-                esModuleInterop: true,
-                skipLibCheck: true,
-                forceConsistentCasingInFileNames: true,
-                resolveJsonModule: true,
-                declaration: true,
-                declarationMap: true,
-                outDir: "./dist",
-                rootDir: "./src"
-            },
-            include: ["src/**/*"],
-            exclude: ["node_modules", "dist"]
-        };
-        fs.writeFileSync(path.join(projectPath, "tsconfig.json"), JSON.stringify(tsConfig, null, 2));
-        // Create vite.config.ts
-        const viteConfig = `import { defineConfig } from "vite";
-import preact from "@preact/preset-vite";
-
-export default defineConfig({
-  plugins: [preact()],
-  build: {
-    lib: {
-      entry: "./src/components/index.ts",
-      formats: ["es"]
-    },
-    rollupOptions: {
-      external: ["preact", "preact/hooks", "@ikas/component-utils"]
-    }
-  }
-});
-`;
-        fs.writeFileSync(path.join(projectPath, "vite.config.ts"), viteConfig);
-        // Create ikas.config.json
+        // Generate IDs for the example config
         const projectId = generateProjectId();
-        const ikasConfig = {
-            name: projectName,
-            version: "1.0.0",
-            projectId,
-            globalStyles: "./src/global.css",
-            components: [
-                {
-                    id: generateComponentId(projectId, "example-component"),
-                    name: "Example Component",
-                    entry: "./src/components/ExampleComponent/index.tsx",
-                    styles: "./src/components/ExampleComponent/styles.css",
-                    props: [
-                        {
-                            name: "title",
-                            displayName: "Title",
-                            type: "TEXT",
-                            required: true,
-                            defaultValue: "Hello World",
-                            description: "The main title text"
-                        },
-                        {
-                            name: "description",
-                            displayName: "Description",
-                            type: "TEXT",
-                            required: false,
-                            defaultValue: "This is an example ikas code component built with Preact.",
-                            description: "The description text below the title"
-                        },
-                        {
-                            name: "showButton",
-                            displayName: "Show Button",
-                            type: "BOOLEAN",
-                            required: false,
-                            defaultValue: true,
-                            description: "Whether to show the action button"
-                        },
-                        {
-                            name: "buttonText",
-                            displayName: "Button Text",
-                            type: "TEXT",
-                            required: false,
-                            defaultValue: "Click Me",
-                            description: "The text displayed on the button"
-                        }
-                    ]
-                },
-                {
-                    id: generateComponentId(projectId, "example-section"),
-                    name: "Example Section",
-                    entry: "./src/components/ExampleSection/index.tsx",
-                    styles: "./src/components/ExampleSection/styles.css",
-                    type: "section",
-                    props: [
-                        {
-                            name: "heading",
-                            displayName: "Heading",
-                            type: "TEXT",
-                            required: true,
-                            defaultValue: "Welcome to Our Store",
-                            description: "The section heading text",
-                            groupId: "content"
-                        },
-                        {
-                            name: "subtitle",
-                            displayName: "Subtitle",
-                            type: "TEXT",
-                            required: false,
-                            defaultValue: "Discover our latest products and collections.",
-                            description: "The subtitle text below the heading",
-                            groupId: "content"
-                        },
-                        {
-                            name: "backgroundColor",
-                            displayName: "Background Color",
-                            type: "COLOR",
-                            required: false,
-                            description: "The section background color",
-                            groupId: "appearance"
-                        }
-                    ],
-                    propGroups: [
-                        { id: "content", name: "Content", description: "Text and copy settings" },
-                        { id: "appearance", name: "Appearance", description: "Colors and visual style" }
-                    ]
-                }
-            ]
+        const exampleComponentId = generateComponentId(projectId, "example-component");
+        const exampleSectionId = generateComponentId(projectId, "example-section");
+        const vars = {
+            PROJECT_NAME: projectName,
+            PROJECT_ID: projectId,
+            EXAMPLE_COMPONENT_ID: exampleComponentId,
+            EXAMPLE_SECTION_ID: exampleSectionId,
         };
-        fs.writeFileSync(path.join(projectPath, "ikas.config.json"), JSON.stringify(ikasConfig, null, 2));
-        // Create ExampleComponent
-        const exampleComponentTsx = `import { Props } from "./types";
-
-export function ExampleComponent({
-  title,
-  description = "This is an example ikas code component built with Preact.",
-  showButton,
-  buttonText = "Click Me",
-}: Props) {
-  return (
-    <div className="example-component">
-      <h1 className="example-title">{title}</h1>
-      <p className="example-description">{description}</p>
-      {showButton && (
-        <button className="example-button">
-          {buttonText}
-        </button>
-      )}
-    </div>
-  );
-}
-
-export default ExampleComponent;
-`;
-        fs.writeFileSync(path.join(projectPath, "src/components/ExampleComponent/index.tsx"), exampleComponentTsx);
-        // Create component types
-        const componentTypes = `// Auto-generated types based on ikas.config.json props
-export interface Props {
-  title: string;
-  description?: string;
-  showButton?: boolean;
-  buttonText?: string;
-}
-`;
-        fs.writeFileSync(path.join(projectPath, "src/components/ExampleComponent/types.ts"), componentTypes);
-        // Create component styles
-        const componentStyles = `.example-component {
-  padding: 24px;
-  border-radius: 8px;
-  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
-  color: white;
-  font-family: system-ui, -apple-system, sans-serif;
-}
-
-.example-title {
-  margin: 0 0 12px 0;
-  font-size: 28px;
-  font-weight: 700;
-}
-
-.example-description {
-  margin: 0 0 20px 0;
-  font-size: 16px;
-  opacity: 0.9;
-}
-
-.example-button {
-  padding: 12px 24px;
-  border: none;
-  border-radius: 6px;
-  background: white;
-  color: #667eea;
-  font-size: 16px;
-  font-weight: 600;
-  cursor: pointer;
-  transition: transform 0.2s, box-shadow 0.2s;
-}
-
-.example-button:hover {
-  transform: translateY(-2px);
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.2);
-}
-`;
-        fs.writeFileSync(path.join(projectPath, "src/components/ExampleComponent/styles.css"), componentStyles);
-        // Create ExampleSection
-        const exampleSectionTsx = `import { Props } from "./types";
-
-export function ExampleSection({ heading, subtitle, backgroundColor }: Props) {
-  return (
-    <section className="example-section" style={backgroundColor ? { backgroundColor } : undefined}>
-      <div className="example-section-inner">
-        <h2 className="example-section-heading">{heading}</h2>
-        {subtitle && <p className="example-section-subtitle">{subtitle}</p>}
-      </div>
-    </section>
-  );
-}
-
-export default ExampleSection;
-`;
-        fs.writeFileSync(path.join(projectPath, "src/components/ExampleSection/index.tsx"), exampleSectionTsx);
-        // Create section types
-        const sectionTypes = `// Auto-generated types based on ikas.config.json props
-export interface Props {
-  heading: string;
-  subtitle?: string;
-  backgroundColor?: string;
-}
-`;
-        fs.writeFileSync(path.join(projectPath, "src/components/ExampleSection/types.ts"), sectionTypes);
-        // Create section styles
-        const sectionStyles = `.example-section {
-  width: 100%;
-  padding: 64px 24px;
-  background: #f8f9fa;
-}
-
-.example-section-inner {
-  max-width: 1200px;
-  margin: 0 auto;
-  text-align: center;
-}
-
-.example-section-heading {
-  margin: 0 0 16px 0;
-  font-size: 36px;
-  font-weight: 700;
-  color: #1a1a2e;
-  font-family: system-ui, -apple-system, sans-serif;
-}
-
-.example-section-subtitle {
-  margin: 0;
-  font-size: 18px;
-  color: #6b7280;
-  font-family: system-ui, -apple-system, sans-serif;
-  max-width: 600px;
-  margin-left: auto;
-  margin-right: auto;
-}
-`;
-        fs.writeFileSync(path.join(projectPath, "src/components/ExampleSection/styles.css"), sectionStyles);
-        // Create global CSS file
-        const globalCss = `/*
- * Global styles for your ikas code components project.
- * These styles are NOT scoped — they apply across all components.
- * Use this for CSS resets, base typography, utility classes, or CSS variables.
- *
- * Loading order:
- *   1. Global CSS (this file) — lowest specificity
- *   2. Shared chunk CSS — multi-scope (.cc_a .sel, .cc_b .sel)
- *   3. Component CSS — single scope (.cc_id .sel) — highest specificity
- *
- * Component-scoped styles naturally override these globals.
- */
-`;
-        fs.writeFileSync(path.join(projectPath, "src/global.css"), globalCss);
-        // Create empty global types file
-        const globalTypes = `// Auto-generated global type definitions for ikas code components.
-// Custom enum types from the editor will appear here.
-// This file is regenerated automatically — do not edit manually.
-
-export {};
-`;
-        fs.writeFileSync(path.join(projectPath, "src/global-types.ts"), globalTypes);
-        // Create components index
-        const componentsIndex = `export { ExampleComponent } from "./ExampleComponent/index";
-export { ExampleSection } from "./ExampleSection/index";
-`;
-        fs.writeFileSync(path.join(projectPath, "src/components/index.ts"), componentsIndex);
-        // Create README
-        const readme = `# ${projectName}
-
-An ikas code components project.
-
-## Getting Started
-
-1. Install dependencies:
-   \`\`\`bash
-   npm install
-   \`\`\`
-
-2. Start the development server:
-   \`\`\`bash
-   npm run dev
-   \`\`\`
-
-3. Open the ikas editor and connect to the dev server from the Dev Components panel.
-
-## Commands
-
-- \`npm run dev\` - Start development server with live editor updates
-- \`npm run build\` - Build components for production
-- \`npm run add\` - Add a new component to the project
-
-## Project Structure
-
-\`\`\`
-${projectName}/
-├── src/
-│   ├── components/
-│   │   ├── ExampleComponent/  # A child component (type: "component")
-│   │   │   ├── index.tsx
-│   │   │   ├── styles.css
-│   │   │   └── types.ts
-│   │   ├── ExampleSection/    # A page-level section (type: "section")
-│   │   │   ├── index.tsx
-│   │   │   ├── styles.css
-│   │   │   └── types.ts
-│   │   └── index.ts
-│   ├── global.css             # Unscoped global styles
-│   └── global-types.ts        # Auto-generated shared enum types
-├── ikas.config.json
-├── package.json
-├── tsconfig.json
-└── vite.config.ts
-\`\`\`
-
-## Sections vs Components
-
-There are two types of code components:
-
-- **Sections** are page-level, full-width containers (e.g. Header, Hero Banner, Footer).
-  Set \`"type": "section"\` on the component entry in \`ikas.config.json\`.
-- **Components** are child elements placed inside sections (e.g. buttons, cards, badges).
-  No \`type\` field needed — it defaults to \`"component"\`.
-
-## Adding Props
-
-Edit \`ikas.config.json\` to add props to your components. Available prop types:
-
-- \`TEXT\` - String input
-- \`NUMBER\` - Number input
-- \`BOOLEAN\` - Checkbox toggle
-- \`IMAGE\` - Image picker
-- \`LINK\` - Link/URL input
-- \`LIST_OF_LINK\` - List of navigation links
-- \`COLOR\` - Color picker
-- \`PRODUCT\` - Single product selector
-- \`PRODUCT_LIST\` - Multiple products selector
-- \`CATEGORY\` - Single category selector
-- \`CATEGORY_LIST\` - Multiple categories selector
-- \`BRAND\` - Single brand selector
-- \`BRAND_LIST\` - Multiple brands selector
-- \`BLOG\` - Single blog post selector
-- \`BLOG_LIST\` - Multiple blog posts selector
-- \`BLOG_CATEGORY\` - Single blog category selector
-- \`BLOG_CATEGORY_LIST\` - Multiple blog categories selector
-
-## Building for Production
-
-Run \`npm run build\` to compile your components. The output will be ready to upload to the ikas editor.
-`;
-        fs.writeFileSync(path.join(projectPath, "README.md"), readme);
-        // Create .gitignore
-        const gitignore = `node_modules/
-dist/
-.DS_Store
-*.log
-`;
-        fs.writeFileSync(path.join(projectPath, ".gitignore"), gitignore);
-        // Create type declarations for virtual modules
-        const componentUtilsTypes = `declare module "@ikas/component-utils" {
-  export function observer<T extends (props: any) => any>(component: T): T;
-}
-`;
-        fs.writeFileSync(path.join(projectPath, "src/ikas-component-utils.d.ts"), componentUtilsTypes);
-        // Create CLAUDE.md for Claude Code AI assistant
-        const claudeMd = `# ikas Code Components Project
-
-You are building **Preact + TypeScript components for an e-commerce storefront**.
-This project uses the ikas Code Components framework with an MCP server for API documentation.
-
-**ALWAYS query MCP tools before writing code that uses storefront APIs.**
-Never guess function signatures or type shapes — the MCP server is the source of truth.
-
-## CRITICAL: Auto-Generated Files
-
-**NEVER manually create or edit \`types.ts\` or \`global-types.ts\`** — they are auto-generated by CLI commands.
-Use \`npx ikas-component config add-component --props '[...]'\` or \`npx ikas-component config add-prop\` to manage props.
-These commands update \`ikas.config.json\`, \`types.ts\`, and \`global-types.ts\` automatically.
-
-## MCP Tools (12 tools)
-
-### Starting a New Section
-| Tool | Purpose |
-|------|---------|
-| \`get_section_template(sectionType)\` | **Start here** — production-ready starter template (index.tsx + types.ts + styles.css + config) for common sections: header, footer, product-detail, product-list, cart, login, register, hero-banner, blog-post, faq, etc. |
-| \`get_framework_guide(topic)\` | Framework docs — "ai-workflow", "common-pitfalls", "prop-types", "css-scoping", "form-handling", "imports", "sections-vs-components" |
-| \`get_code_example(task)\` | Code examples — "add to cart", "variant selection", "image-handling", "product-detail-section", "cart-section" |
-
-### Looking Up APIs
-| Tool | Purpose |
-|------|---------|
-| \`search_docs(query)\` | Search across all storefront API docs and framework guides |
-| \`get_function_doc(name)\` | Full docs for a specific function (e.g. "addItemToCart", "Router.navigate") |
-| \`list_functions(category?)\` | List functions by category: ProductDetail, Cart, ProductList, Navigation, Customer, Order, Image, Blog, Brand, Category, Pricing, Form, Validation, Pagination, Filtering |
-| \`get_prop_types()\` | All available ikas.config.json prop types with TS types and examples |
-
-### Exploring Types
-| Tool | Purpose |
-|------|---------|
-| \`get_model_guide(model)\` | **One-stop-shop** — type definition + all utility functions + examples + related types for a model (e.g. "IkasProduct", "IkasOrder") |
-| \`get_type_definition(name)\` | Full definition of a type or enum (e.g. "IkasProduct", "IkasOrderStatus") |
-| \`get_functions_for_type(typeName)\` | All utility functions for a type (e.g. "IkasImage") |
-| \`search_types(query)\` | Search types/enums by keyword (e.g. "price", "address", "status") |
-| \`list_types(domain?, kind?)\` | List all types, optionally filtered by domain ("product", "cart", "order") or kind ("type", "enum") |
-
-## CLI Commands
-
-**Never edit ikas.config.json or types.ts manually** — use the CLI commands:
-
-| Command | Purpose |
-|---------|---------|
-| \`npx ikas-component config add-component --name "Name" --type section --props '[...]'\` | **Primary** — create component with all props in one command |
-| \`npx ikas-component config add-component --name "Name" --type section\` | Create component with no props (add later) |
-| \`npx ikas-component config add-prop --component "Name" --name title --displayName "Title" --type TEXT --required [--group content]\` | Add a single prop incrementally |
-| \`npx ikas-component config update-prop --component "Name" --prop title --type RICH_TEXT [--group colors]\` | Update a prop's type or group |
-| \`npx ikas-component config remove-prop --component "Name" --prop title\` | Remove a prop |
-| \`npx ikas-component config remove-component --name "Name"\` | Remove a component |
-| \`npx ikas-component config add-prop-group --component "Name" --id colors --name "Colors" [--description "..."] [--parent style]\` | Create a prop group |
-| \`npx ikas-component config update-prop-group --component "Name" --id colors [--name "..."] [--description "..."]\` | Update a prop group |
-| \`npx ikas-component config remove-prop-group --component "Name" --id colors\` | Remove a prop group |
-| \`npx ikas-component config list\` | List all components and their props |
-| \`npx ikas-component check --json\` | Type-check all components, output errors as JSON |
-| \`npx ikas-component build\` | Compile server.js + client.js + styles.css per component |
-| \`npx ikas-component dev\` | Start dev server (Vite 5200 + WebSocket 5201) |
-
-## Workflow: Building a New Section
-
-1. \`get_section_template("product-detail")\` → get starter files + CLI command with --props
-2. Run the CLI command (creates component + props + types.ts in one step)
-3. Write \`index.tsx\` and \`styles.css\` using the template (do NOT edit types.ts — it's already generated)
-4. Look up APIs → \`get_model_guide("IkasProduct")\`, \`get_function_doc("addItemToCart")\`
-5. \`npx ikas-component check --json\` → fix type errors
-6. \`npx ikas-component build\` → verify clean build
-
-## Sub-Component Structure
-
-**ALWAYS create sub-components in \`src/sub-components/\` with their own folder containing \`index.tsx\` and \`styles.css\`. NEVER create flat .tsx files inside a component folder.**
-
-\`\`\`
-src/
-├── components/
-│   ├── ProductList/
-│   │   ├── index.tsx         # imports from ../../sub-components/...
-│   │   ├── types.ts          # auto-generated (CLI-managed)
-│   │   └── styles.css        # @import "../../sub-components/.../styles.css"
-│   └── index.ts
-├── sub-components/
-│   ├── ProductCard/
-│   │   ├── index.tsx          # sub-component with inline Props
-│   │   └── styles.css
-│   └── FilterSidebar/
-│       ├── index.tsx
-│       └── styles.css
-├── global.css                 # unscoped global styles
-└── global-types.ts            # auto-generated shared enum types
-\`\`\`
-
-**Key rules:**
-- \`src/components/\` = registered in ikas.config.json. \`src/sub-components/\` = internal helpers (NOT in ikas.config.json)
-- Sub-components do NOT have \`types.ts\` — define \`Props\` inline in \`index.tsx\`
-- Custom enum types are exported from \`src/global-types.ts\` (auto-generated). Sub-components can import them: \`import type { MyEnum } from "../../global-types";\`
-- CSS: use \`@import "../../sub-components/ProductCard/styles.css";\` in parent styles.css
-- TSX: use \`import ProductCard from "../../sub-components/ProductCard";\`
-- Sub-components that read MobX stores need \`observer()\`, others don't
-- Sub-components can be shared across multiple parent sections
-
-\`\`\`tsx
-// src/sub-components/ProductCard/index.tsx — inline Props, no types.ts
-import { IkasProduct, getSelectedProductVariant } from "@ikas/bp-storefront";
-
-interface Props { product: IkasProduct; }
-
-export default function ProductCard({ product }: Props) { ... }
-\`\`\`
-
-## Key Patterns
-
-### Component Exports & Reactivity
-\`\`\`tsx
-// Root components are automatically reactive — the ikas runtime wraps them in autorun().
-// Do NOT import or use observer() on root exports.
-import { Props } from "./types";
-
-export function MySection({ product }: Props) { ... }
-export default MySection;
-\`\`\`
-
-\`\`\`tsx
-// Only use observer() on extracted SUB-COMPONENTS that independently read MobX stores:
-import { observer } from "@ikas/component-utils";
-
-const CartBadge = observer(function CartBadge() {
-  const count = cartStore.order?.orderLineItems?.length ?? 0;
-  return <span>{count}</span>;
-});
-\`\`\`
-
-### Null Safety
-\`\`\`tsx
-// Storefront models can be null — always check before accessing
-if (!product) return null;
-const price = product.selectedVariant?.price?.formattedPrice ?? "";
-\`\`\`
-
-### Mutations
-\`\`\`tsx
-// Functions like addItemToCart() mutate the model in-place (MobX observable)
-// No need to capture return value — root components re-render automatically via autorun()
-await addItemToCart({ product });
-\`\`\`
-
-### COMPONENT & COMPONENT_LIST Props
-These props let you create **slot-based** architectures where store owners can drag child components into your section/component from the editor.
-
-- \`COMPONENT\` — a single child component slot (TS type: \`any\`)
-- \`COMPONENT_LIST\` — a list of child components (TS type: \`any\`)
-
-**Rendering:** Use the \`<IkasComponentRenderer>\` wrapper to render child components:
-\`\`\`tsx
-import { IkasComponentRenderer } from "@ikas/bp-storefront";
-import { Props } from "./types";
-
-export function MySection({ title, cardList, ...props }: Props) {
-  return (
-    <section>
-      <h2>{title}</h2>
-      <div className="cards">
-        {/* COMPONENT_LIST — render a list of child components */}
-        <IkasComponentRenderer
-          components={cardList as any[]}
-          parentProps={props}
-        />
-      </div>
-    </section>
-  );
-}
-export default MySection;
-\`\`\`
-
-**Key rules:**
-- Always pass \`parentProps={props}\` so child components can access parent data via dynamic values
-- Cast the prop value: \`components={myList as any[]}\` for COMPONENT_LIST, \`components={[myComp] as any[]}\` for COMPONENT
-- \`<IkasComponentRenderer>\` handles rendering, styling, and reactivity of child components automatically
-
-**Config example:**
-\`\`\`json
-{
-  "name": "cardList",
-  "displayName": "Card List",
-  "type": "COMPONENT_LIST"
-}
-\`\`\`
-
-### CSS Scoping
-All CSS is auto-scoped with \`.cc_{componentId}\` prefix. Write plain class names — they are scoped at build time.
-
-### Preact Event Handling
-Use \`onInput\` instead of \`onChange\` for text inputs (Preact behavior).
-
-### Import Source
-\`\`\`tsx
-import { addItemToCart, IkasProduct, IkasImage } from "@ikas/bp-storefront";
-\`\`\`
-
-## No Static Text Rule
-
-**CRITICAL: Never hardcode user-visible text in JSX.** All text strings (headings, button labels,
-empty states, loading messages, form labels) MUST be TEXT props with defaultValues.
-
-Wrong: \`<h1>Sign In</h1>\`
-Correct: \`<h1>{title}</h1>\` with \`title\` as TEXT prop (defaultValue: "Sign In")
-
-For button loading states, use two separate props:
-- \`submitButtonText\` (default: "Sign In")
-- \`submittingButtonText\` (default: "Signing in...")
-
-Group text props under a "Texts" propGroup when the component has 5+ props.
-
-## Sections vs Components
-
-- **Sections** = page-level, full-width containers (Header, Hero, Product Grid, Footer).
-  Set \`"type": "section"\` via CLI. Use \`<section>\` root element. Props interface: \`Props\`.
-  **Sections MUST always include a \`backgroundColor\` COLOR prop** (default: \`#ffffff\`).
-  Apply via inline style: \`style={backgroundColor ? { backgroundColor } : undefined}\`
-  Consider also adding \`textColor\` COLOR props for text elements directly on the section background.
-- **Components** = child elements placed inside sections (buttons, cards, badges).
-  Defaults to \`"component"\`. Use \`<div>\` root element. Props interface: \`Props\`.
-
-## Prop Groups
-
-Organize props into collapsible groups in the editor sidebar. Use prop groups when a component has 5+ props to improve UX.
-
-### Config Format
-- Define groups in \`propGroups\` array on the component in \`ikas.config.json\`
-- Assign props to groups via \`groupId\` on each prop
-- Groups can nest 1 level deep via \`children\`
-- Props without \`groupId\` appear ungrouped at root level
-- Group IDs must be unique within a component
-
-### CLI Commands
-- \`config add-prop-group --component "Name" --id content --name "Content"\` — create group
-- \`config add-prop-group --component "Name" --id colors --name "Colors" --parent style\` — create nested group
-- \`config add-prop --component "Name" --name title --displayName "Title" --type TEXT --group content\` — add prop to group
-- \`config update-prop --component "Name" --prop title --group colors\` — move prop to different group
-- \`config remove-prop-group --component "Name" --id content\` — remove group (props become ungrouped)
-
-### When to Use
-- 5+ props → group related props
-- Sections with content + style props → separate "Content" and "Appearance" groups
-- Complex sections → use nested groups (e.g., "Style" → "Colors", "Typography")
-
-## Workflow Addition
-
-When building a section with 5+ props, organize into prop groups after defining props:
-\`\`\`bash
-npx ikas-component config add-prop-group --component "Name" --id content --name "Content"
-npx ikas-component config update-prop --component "Name" --prop title --group content
-\`\`\`
-
-## Build Verification
-
-IMPORTANT: After completing any task, always run \`npx ikas-component build\` (or \`npm run build\`) to check for
-TypeScript and build errors. Fix any errors before considering the task done.
-`;
-        fs.writeFileSync(path.join(projectPath, "CLAUDE.md"), claudeMd);
-        // Create .cursorrules for Cursor AI assistant
-        const cursorrules = `# ikas Code Components
-
-You are building **Preact + TypeScript components for an e-commerce storefront**.
-**ALWAYS query MCP tools before writing code that uses storefront APIs.**
-
-## CRITICAL: Auto-Generated Files
-
-**NEVER manually create or edit \`types.ts\` or \`global-types.ts\`** — they are auto-generated by CLI commands.
-Use \`npx ikas-component config add-component --props '[...]'\` or \`npx ikas-component config add-prop\` to manage props.
-These commands update \`ikas.config.json\`, \`types.ts\`, and \`global-types.ts\` automatically.
-
-## MCP Tools (12 tools)
-
-### Starting a New Section
-- get_section_template(sectionType) — **Start here** — production-ready starter template for common sections (header, footer, product-detail, product-list, cart, login, hero-banner, blog-post, faq, etc.)
-- get_framework_guide(topic) — Framework docs ("ai-workflow", "common-pitfalls", "prop-types", "css-scoping", "form-handling", "imports")
-- get_code_example(task) — Code examples ("add to cart", "variant selection", "image-handling")
-
-### Looking Up APIs
-- search_docs(query) — Search all storefront API docs and framework guides
-- get_function_doc(name) — Full docs for a function (e.g. "addItemToCart", "Router.navigate")
-- list_functions(category?) — List functions by category (ProductDetail, Cart, ProductList, Navigation, Customer, Order, Image, Blog, Brand, Pricing, Form, Validation, Pagination, Filtering)
-- get_prop_types() — All available ikas.config.json prop types
-
-### Exploring Types
-- get_model_guide(model) — **One-stop-shop** — type def + utility functions + examples for a model (e.g. "IkasProduct", "IkasOrder")
-- get_type_definition(name) — Full definition of a type or enum
-- get_functions_for_type(typeName) — All utility functions for a type
-- search_types(query) — Search types/enums by keyword ("price", "address", "status")
-- list_types(domain?, kind?) — List all types, filter by domain or kind ("type"/"enum")
-
-## CLI Commands (never edit ikas.config.json or types.ts manually)
-- npx ikas-component config add-component --name "Name" --type section --props '[...]' — **Primary** — create with all props in one command
-- npx ikas-component config add-component --name "Name" --type section — Create component with no props
-- npx ikas-component config add-prop --component "Name" --name title --displayName "Title" --type TEXT --required [--group content] — Add a prop incrementally
-- npx ikas-component config update-prop --component "Name" --prop title --type RICH_TEXT [--group colors] — Update a prop or group
-- npx ikas-component config remove-prop --component "Name" --prop title — Remove a prop
-- npx ikas-component config remove-component --name "Name" — Remove a component
-- npx ikas-component config add-prop-group --component "Name" --id colors --name "Colors" [--parent style] — Create a prop group
-- npx ikas-component config update-prop-group --component "Name" --id colors [--name "..."] — Update a prop group
-- npx ikas-component config remove-prop-group --component "Name" --id colors — Remove a prop group
-- npx ikas-component config list — List all components and their props
-- npx ikas-component check --json — Type-check all components
-- npx ikas-component build — Compile server.js + client.js + styles.css per component
-- npx ikas-component dev — Start dev server (Vite 5200 + WebSocket 5201)
-
-## Workflow: Building a New Section
-1. get_section_template("product-detail") → get starter files + CLI command with --props
-2. Run the CLI command (creates component + props + types.ts in one step)
-3. Write index.tsx and styles.css using the template (do NOT edit types.ts — it's already generated)
-4. Look up APIs: get_model_guide("IkasProduct"), get_function_doc("addItemToCart")
-5. npx ikas-component check --json → fix type errors
-6. npx ikas-component build → verify clean build
-
-## Sub-Component Structure
-**ALWAYS create sub-components in \`src/sub-components/\` with their own folder containing \`index.tsx\` and \`styles.css\`.**
-- \`src/components/\` = registered in ikas.config.json. \`src/sub-components/\` = internal helpers (NOT in ikas.config.json)
-- Sub-components do NOT have \`types.ts\` — define \`Props\` inline in \`index.tsx\`
-- Custom enum types are exported from \`src/global-types.ts\` (auto-generated). Sub-components can import them: \`import type { MyEnum } from "../../global-types";\`
-- CSS: \`@import "../../sub-components/ProductCard/styles.css";\` in parent styles.css
-- TSX: \`import ProductCard from "../../sub-components/ProductCard";\`
-- Sub-components that read MobX stores need \`observer()\`, others don't
-- Sub-components can be shared across multiple parent sections
-- NEVER create flat .tsx files inside a component folder
-
-## Key Patterns
-- Root components are automatically reactive (ikas runtime uses autorun). Do NOT use observer() on root exports.
-  Pattern: \`export function MySection({ title }: Props) { ... }\` + \`export default MySection;\`
-  Only use observer() on extracted sub-components that independently read MobX stores.
-- Null safety: storefront models can be null — always check before accessing
-- Mutations: addItemToCart() etc. mutate MobX observables in-place — no return capture needed
-- COMPONENT & COMPONENT_LIST props: slot-based child components rendered via \`<IkasComponentRenderer>\`
-  \`import { IkasComponentRenderer } from "@ikas/bp-storefront"\`
-  \`<IkasComponentRenderer components={myList as any[]} parentProps={props} />\`
-  Always pass \`parentProps={props}\` so children can access parent data. Cast with \`as any[]\`.
-- CSS: write plain class names — auto-scoped with .cc_{componentId} at build time
-- Events: use onInput (not onChange) for text inputs (Preact behavior)
-- Imports: \`import { addItemToCart, IkasProduct } from "@ikas/bp-storefront"\`
-
-## No Static Text Rule
-**CRITICAL: Never hardcode user-visible text in JSX.** All text strings (headings, button labels,
-empty states, loading messages, form labels) MUST be TEXT props with defaultValues.
-Wrong: \`<h1>Sign In</h1>\`
-Correct: \`<h1>{title}</h1>\` with \`title\` as TEXT prop (defaultValue: "Sign In")
-For button loading states, use two separate props (e.g., \`submitButtonText\` + \`submittingButtonText\`).
-Group text props under a "Texts" propGroup when the component has 5+ props.
-
-## Sections vs Components
-- Sections = page-level containers (Header, Hero, Product Grid, Footer)
-  Set "type": "section" via CLI. Use <section> root element. Props interface: Props.
-  **Sections MUST always include a \`backgroundColor\` COLOR prop** (default: \`#ffffff\`).
-  Apply via inline style: \`style={backgroundColor ? { backgroundColor } : undefined}\`
-  Consider also adding \`textColor\` COLOR props for text elements directly on the section background.
-- Components = child elements inside sections (buttons, cards, badges)
-  Defaults to "component". Use <div> root element. Props interface: Props.
-
-## Prop Groups
-Organize 5+ props into collapsible groups in editor sidebar.
-- Define groups in \`propGroups\` on component in ikas.config.json
-- Assign props via \`groupId\` on each prop
-- Nest 1 level deep with \`children\`
-- Group IDs must be unique within a component
-- CLI: add-prop-group, update-prop-group, remove-prop-group
-- Add prop to group: add-prop --group <groupId> or update-prop --group <groupId>
-
-## Build Verification
-IMPORTANT: After completing any task, always run \`npx ikas-component build\` (or \`npm run build\`)
-to check for TypeScript and build errors. Fix any errors before considering the task done.
-`;
-        fs.writeFileSync(path.join(projectPath, ".cursorrules"), cursorrules);
-        // Create .mcp.json for MCP server configuration
-        // Uses npx which resolves the bin through node_modules hierarchy,
-        // working both in standalone projects and monorepo workspaces.
-        const mcpConfig = {
-            mcpServers: {
-                "ikas-code-components": {
-                    command: "npx",
-                    args: ["ikas-mcp"]
-                }
-            }
-        };
-        fs.writeFileSync(path.join(projectPath, ".mcp.json"), JSON.stringify(mcpConfig, null, 2));
+        // Write all template files
+        const files = [
+            { template: "create/package.json", dest: "package.json", vars },
+            { template: "create/tsconfig.json", dest: "tsconfig.json" },
+            { template: "create/vite.config.ts", dest: "vite.config.ts" },
+            { template: "create/ikas.config.json", dest: "ikas.config.json", vars },
+            { template: "create/gitignore", dest: ".gitignore" },
+            { template: "create/mcp.json", dest: ".mcp.json" },
+            { template: "create/README.md", dest: "README.md", vars },
+            { template: "create/claude-md", dest: "CLAUDE.md" },
+            { template: "create/cursorrules", dest: ".cursorrules" },
+            { template: "create/src/global.css", dest: "src/global.css" },
+            { template: "create/src/global-types.ts", dest: "src/global-types.ts" },
+            { template: "create/src/ikas-component-utils.d.ts", dest: "src/ikas-component-utils.d.ts" },
+            { template: "create/src/components/index.ts", dest: "src/components/index.ts" },
+            { template: "create/src/components/ExampleComponent/index.tsx", dest: "src/components/ExampleComponent/index.tsx" },
+            { template: "create/src/components/ExampleComponent/types.ts", dest: "src/components/ExampleComponent/types.ts" },
+            { template: "create/src/components/ExampleComponent/styles.css", dest: "src/components/ExampleComponent/styles.css" },
+            { template: "create/src/components/ExampleSection/index.tsx", dest: "src/components/ExampleSection/index.tsx" },
+            { template: "create/src/components/ExampleSection/types.ts", dest: "src/components/ExampleSection/types.ts" },
+            { template: "create/src/components/ExampleSection/styles.css", dest: "src/components/ExampleSection/styles.css" },
+        ];
+        for (const file of files) {
+            fs.writeFileSync(path.join(projectPath, file.dest), readTemplate(file.template, file.vars));
+        }
         // Create or merge .cursor/mcp.json for Cursor editor
         // Uses node + ${workspaceFolder} instead of npx because Cursor
         // doesn't reliably inherit the shell PATH.