@ikas/component-cli 0.133.0 → 1.1.0

package/templates/create/cursorrules

@@ -1,123 +0,0 @@
-# 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 `ikas.config.json`, `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.
-
-**The CLI does NOT edit your component source.** `remove-prop` and `remove-enum` update `ikas.config.json` and the generated `types.ts` / `global-types.ts` only — `index.tsx`, sub-components, and `styles.css` are untouched. After removing a prop or enum, grep the source for the old identifier and clean up dead references yourself before building.
-
-## 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 config add-enum --name "Size" --options '[{"name":"Small","value":"s"}]' — Create a custom ENUM type (returns enumTypeId)
-- npx ikas-component config update-enum --id <enumId> --name "..." [--options '[...]'] — Update enum name/options
-- npx ikas-component config remove-enum --id <enumId> — Remove enum (fails if any prop still references it)
-- npx ikas-component config list-enums — List all custom enums
-- 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-section") → get starter files + CLI command with --props
-2. For any custom ENUM props the section needs: `config add-enum` FIRST (capture the returned enumTypeId), then reference it in `add-prop --type ENUM --enumTypeId <id>`. Order matters — an ENUM prop without a pre-existing enumTypeId is rejected.
-3. Run the CLI command (creates component + props + types.ts in one step)
-4. Write index.tsx and styles.css using the template (do NOT edit types.ts or global-types.ts — both are regenerated on every prop/enum mutation)
-5. Look up APIs: get_model_guide("IkasProduct"), get_function_doc("addItemToCart")
-6. npx ikas-component check --json → fix type errors
-7. npx ikas-component build → verify clean build
-
-### Custom ENUM lifecycle
-- **Create:** `add-enum` → `add-prop --type ENUM --enumTypeId <id>` (enum must exist before the prop is created).
-- **Rename options:** `update-enum --id <id> --options '[...]'` — types.ts regenerates automatically.
-- **Remove:** remove (or repoint) every prop that references the enum FIRST, then `remove-enum`. `remove-enum` blocks with an error while any prop still references the id.
-- `global-types.ts` is regenerated unconditionally on `add-enum` / `update-enum` / `remove-enum` / `remove-prop` — never hand-edit it.
-- Template snippets from `get_section_template` use `{{ENUM_ID:<EnumName>}}` placeholders (e.g. `{{ENUM_ID:AspectRatio}}`). Create the matching `add-enum` first, then substitute the returned id.
-
-## 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";`
-- TSX: `import ProductCard from "../../sub-components/ProductCard";`
-- Sub-components should be wrapped with `observer()` from `@ikas/component-utils`
-- 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 sub-components.
-- 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 or another specific text group name.
-
-**Assistive strings (`aria-label`, `aria-describedby`, `alt`, sr-only text):** if the string is meaningful to end users (e.g. icon-only button label, product image alt), make it a TEXT prop. English literal defaults are acceptable for purely structural labels where a merchant would never want to change them (e.g. `role="dialog" aria-modal="true"`). When in doubt, make it a prop.
-
-## 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 props that are related to each other 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.

package/templates/create/gitignore

@@ -1,6 +0,0 @@
-node_modules/
-dist/
-.DS_Store
-*.log
-.ikas-dev-state.json
-asd

package/templates/create/ikas.config.json

@@ -1,95 +0,0 @@
-{
-  "name": "{{PROJECT_NAME}}",
-  "version": "1.0.0",
-  "projectId": "{{PROJECT_ID}}",
-  "globalStyles": "./src/global.css",
-  "components": [
-    {
-      "id": "{{EXAMPLE_COMPONENT_ID}}",
-      "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": "{{EXAMPLE_SECTION_ID}}",
-      "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"
-        }
-      ]
-    }
-  ]
-}

package/templates/create/mcp.json

@@ -1,10 +0,0 @@
-{
-  "mcpServers": {
-    "ikas-code-components": {
-      "command": "npx",
-      "args": [
-        "ikas-mcp"
-      ]
-    }
-  }
-}

package/templates/create/package.json

@@ -1,22 +0,0 @@
-{
-  "name": "{{PROJECT_NAME}}",
-  "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": "*",
-    "@preact/preset-vite": "^2.10.3",
-    "typescript": "^5.3.0",
-    "vite": "^5.0.0"
-  }
-}

package/templates/create/src/components/ExampleComponent/index.tsx

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

package/templates/create/src/components/ExampleComponent/styles.css

@@ -1,36 +0,0 @@
-.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);
-}

package/templates/create/src/components/ExampleComponent/types.ts

@@ -1,7 +0,0 @@
-// This file is auto-generated — do not edit manually.
-export interface Props {
-  title: string;
-  description?: string;
-  showButton?: boolean;
-  buttonText?: string;
-}

package/templates/create/src/components/ExampleSection/index.tsx

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

package/templates/create/src/components/ExampleSection/styles.css

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

package/templates/create/src/components/ExampleSection/types.ts

@@ -1,6 +0,0 @@
-// This file is auto-generated — do not edit manually.
-export interface Props {
-  heading: string;
-  subtitle?: string;
-  backgroundColor?: string;
-}

package/templates/create/src/components/index.ts

@@ -1,2 +0,0 @@
-export { ExampleComponent } from "./ExampleComponent/index";
-export { ExampleSection } from "./ExampleSection/index";

package/templates/create/src/global-types.ts

@@ -1,5 +0,0 @@
-// 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 {};

package/templates/create/src/global.css

@@ -1,29 +0,0 @@
-/*
- * Global styles for your ikas code components project.
- *
- * Scoping: at build time every rule here is wrapped in a per-project scope
- * (`:where([data-cc-scope~="<projectId>"])`) so styles from one project cannot
- * leak into another project's components or the host page.
- *
- * What works:
- *   - Class / tag / attribute selectors on elements you render (`.card`, `img`, `[data-x]`).
- *   - `:root { --var: value }` — variables are rewritten onto the component wrapper
- *     and inherit down its subtree. Use this for design tokens.
- *   - `@media`, `@supports`, `@container`, `@layer` — walked recursively.
- *   - `@keyframes`, `@font-face` — left untouched.
- *
- * What does NOT work (code components only style elements they own):
- *   - Top-level `body { ... }` / `html { ... }` rules — dropped.
- *   - Descendant selectors starting with `body` / `html` (e.g. `body .x`, `html.dark .y`) —
- *     emitted but never match, because the component wrapper is INSIDE body, not
- *     the other way around. Use a class on your own wrapper instead
- *     (e.g. add `dark` via JS and write `.dark .x`).
- *   - Document-wide resets, scrollbar tweaks, page backgrounds — belong to the theme.
- *
- * Loading order (all scoped to this project):
- *   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.
- */

package/templates/create/src/ikas-component-utils.d.ts

@@ -1,3 +0,0 @@
-declare module "@ikas/component-utils" {
-  export function observer<T extends (props: any) => any>(component: T): T;
-}

package/templates/create/tsconfig.json

@@ -1,30 +0,0 @@
-{
-  "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"
-  ]
-}

package/templates/create/vite.config.ts

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

package/templates/create-full/README.md

@@ -1,78 +0,0 @@
-# my-ikas-components
-
-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
-
-```
-my-ikas-components/
-├── 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
-├── 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
-- `SELECT` - Dropdown selection
-- `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
-
-## Building for Production
-
-Run `npm run build` to compile your components. The output will be ready to upload to the ikas editor.