@ikas/code-components-mcp 1.4.0-beta.5 → 1.4.0-beta.7

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-11T12:29:24.468Z",
+  "generatedAt": "2026-05-12T09:27:14.491Z",
   "functions": [
     {
       "name": "fbp_initAdvancedMatching",

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-05-11T12:29:24.493Z",
+  "generatedAt": "2026-05-12T09:27:14.516Z",
   "types": [
     {
       "name": "IkasProductAttributeDetail",

package/dist/index.js

@@ -571,8 +571,9 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
     parts.push(`> 1. **Tick checkboxes** as you finish work. Use \`[~]\` for in-progress and \`[x]\` for done. Edit the file directly with your file-editing tools.`);
     parts.push(`> 2. **theme.json is incomplete.** Atomic components (Button, Input, Card, icons, etc.) often live only in \`src/\` and are NOT referenced from theme.json. Before you start section migration, scan the old source directory and ADD entries to this file for anything the initial scan missed — list them under \`## Source Code Analysis\` and add shared ones to \`### Shared Sub-Components\`.`);
     parts.push(`> 3. **Custom data types are NOT pre-converted.** For each customData entry used by a section, decide enum-vs-component when you migrate that section. Log every decision in \`## Custom Data Decisions\` with reasoning. See \`get_migration_guide("custom-data-conversion")\` for the heuristic.`);
-    parts.push(`> 4. **Per-section work:** call \`get_section_migration_plan({theme_json_path, section_name, project_name: "${projectName}"})\` for each section. The MCP returns concrete CLI commands and flags any customData-referencing props with a "Decide: enum or component?" callout.`);
-    parts.push(`> 5. **If you discover new shared sub-components mid-migration**, add them under \`### Shared Sub-Components\` and any notes under \`## Notes\`.`);
+    parts.push(`> 4. **Preserve feature parity. Do NOT silently simplify or drop features.** If an old prop has richer fields than a new built-in prop type can carry (e.g. a navigation link with a per-link image), the answer is to build a child component — never to flatten and "add it later." Later doesn't come. If the user explicitly wants a feature removed, log that as an explicit decision in \`## Notes\`; otherwise migrate to functional parity.`);
+    parts.push(`> 5. **Per-section work:** call \`get_section_migration_plan({theme_json_path, section_name, project_name: "${projectName}"})\` for each section. The MCP returns concrete CLI commands and flags any customData-referencing props with a "Decide: enum or component?" callout.`);
+    parts.push(`> 6. **If you discover new shared sub-components mid-migration**, add them under \`### Shared Sub-Components\` and any notes under \`## Notes\`.`);
     parts.push(`>`);
     parts.push(`> Status legend: \`[ ]\` not started · \`[~]\` in progress · \`[x]\` complete.`);
     parts.push("");
@@ -727,22 +728,14 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
     parts.push("");
     parts.push(`> **Before starting section migration**, scan the old \`src/\` for components NOT listed above. theme.json does not see atomic primitives — buttons, inputs, cards, icon wrappers, layout helpers, etc. — that are imported by sections but never appear as theme components. Add them here, then decide which become shared sub-components vs which collapse into section bodies.`);
     parts.push("");
-    parts.push(`<!-- Example: list each atomic component you find here.`);
-    parts.push(`- \`Button\` — found in src/atoms/Button/. Used by ~all sections. → add as Shared Sub-Component.`);
-    parts.push(`- \`PriceLabel\` — found in src/atoms/. Used only by ProductCard. → inline into ProductCard during migration.`);
-    parts.push(`- \`Icon\` — found in src/atoms/Icon/. Used everywhere; replace with inline SVG per section.`);
-    parts.push(`-->`);
+    parts.push(`<!-- Example: \`- Button (src/atoms/Button/) — used by ~all sections → promote to Shared Sub-Component\` -->`);
     parts.push("");
     // Custom Data Decisions — append-only log the LLM fills as it makes per-section decisions
     parts.push(`## Custom Data Decisions`);
     parts.push("");
     parts.push(`> Log each customData enum-vs-component decision here as you encounter it during section migration. Format: \`- \\\`<CustomDataName>\\\` → enum/component \\\`<target name>\\\` (YYYY-MM-DD) — reasoning\`.`);
     parts.push("");
-    parts.push(`<!-- Example entries:`);
-    parts.push(`- \`SlideData\` → component \`hero-slide\` (2026-05-11) — structured record {image, link, title} repeated per slide; wired into HeroSlider via COMPONENT_LIST.`);
-    parts.push(`- \`Position\` → enum \`Position\` (2026-05-11) — flat scalar set left/right/center; enumId: enm_abc123.`);
-    parts.push(`- \`MenuItemData\` → component \`menu-item\` (2026-05-12) — mega-menu links with image + title fields; LIST_OF_LINK would have dropped the image.`);
-    parts.push(`-->`);
+    parts.push(`<!-- Example: \`- SlideData → component \\\`hero-slide\\\` (2026-05-11) — structured record {image,link,title}; LIST_OF_LINK would drop the image\` -->`);
     parts.push("");
     // Known Environmental Issues (agents fill in during work)
     parts.push(`## Known Environmental Issues`);
@@ -751,44 +744,22 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
     parts.push("");
     parts.push(`- [ ] _(none recorded yet)_`);
     parts.push("");
-    // Usage section
-    parts.push(`## Per-Section Usage`);
-    parts.push("");
-    parts.push(`Once the Foundation is complete, for each section above:`);
-    parts.push("");
-    parts.push(`1. Find the first unchecked \`[ ]\` section (start with Simple).`);
-    parts.push(`2. Call \`get_section_migration_plan({theme_json_path, section_name: "<old section name>", project_name: "${projectName}"})\`.`);
-    parts.push(`3. Read the old source files listed in the plan.`);
-    parts.push(`4. Make any customData enum-vs-component decisions surfaced in the plan and log them under \`## Custom Data Decisions\` above.`);
-    parts.push(`5. Run the CLI commands in the plan (they create parent + children with auto-generated types.ts).`);
-    parts.push(`6. Write \`index.tsx\` and \`styles.css\` using the patterns in the plan. DO NOT manually edit types.ts.`);
-    parts.push(`7. Mark the section \`[x]\` when it builds cleanly. Append a short note to the **Notes** section below (what libraries you replaced, any ad-hoc props you had to add, the actual folder name the CLI created if different from the name you passed).`);
-    parts.push("");
     // Notes — append-only log for decisions not captured elsewhere
     parts.push(`## Notes`);
     parts.push("");
-    parts.push(`_Append a bullet after completing work. Format: \`- [YYYY-MM-DD] <section-id>: <brief note>\`. This is how future sessions learn about decisions not encoded in the plan structure (library swaps, ad-hoc props, CLI folder-name oddities, etc.)._`);
+    parts.push(`_Append a bullet after completing work — library swaps, ad-hoc props, CLI folder-name oddities, user-approved feature drops, etc. Format: \`- [YYYY-MM-DD] <section-id>: <brief note>\`._`);
     parts.push("");
-    parts.push(`<!-- Examples:`);
-    parts.push(`- [2026-04-15] Foundation: built Input, SubmitButton, Modal, SectionHeader, StarRating. Skipped: GoogleCaptcha (needs investigation), BlogCard, Pagination (low priority).`);
-    parts.push(`- [2026-04-15] ${projectName}-footer: swapped react-hot-toast for inline status text; newsletter uses form-model pattern (getNewsletterSubscriptionForm). CLI created folder as "Footer/" as expected.`);
-    parts.push(`-->`);
+    parts.push(`<!-- Example: \`- [2026-04-15] ${projectName}-footer: swapped react-hot-toast for inline status text; CLI created Footer/ as expected\` -->`);
     parts.push("");
-    // Cross-references
+    // Cross-references — keep terse; LLM can call `get_migration_guide("list")` or `get_framework_guide("list")` for more
     parts.push(`## Cross-References`);
     parts.push("");
-    parts.push(`Essential MCP tools to call during migration:`);
+    parts.push(`- \`get_migration_guide("iterative-workflow")\` — the full per-phase protocol`);
+    parts.push(`- \`get_migration_guide("custom-data-conversion")\` — enum-vs-component decisions`);
+    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — runtime shapes & access patterns`);
+    parts.push(`- \`get_framework_guide("common-pitfalls")\` — gotchas & old→new property migrations`);
     parts.push("");
-    parts.push(`- \`get_migration_guide("iterative-workflow")\` — full protocol for resumable migrations`);
-    parts.push(`- \`get_migration_guide("component-renderer-limitations")\` — critical constraints when using COMPONENT_LIST`);
-    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — \`.data\` vs \`.links\`, \`.variant\` vs \`.product\`, etc.`);
-    parts.push(`- \`get_migration_guide("link-prop-decision-guide")\` — LINK vs LIST_OF_LINK vs COMPONENT_LIST`);
-    parts.push(`- \`get_migration_guide("library-replacements")\` — swiper, headlessui, tailwind, etc.`);
-    parts.push(`- \`get_migration_guide("react-to-preact")\` — observer rules, imports, IkasSlider removal`);
-    parts.push(`- \`get_framework_guide("component-renderer-patterns")\` — full IkasComponentRenderer usage`);
-    parts.push(`- \`get_framework_guide("common-pitfalls")\` — general gotchas`);
-    parts.push(`- \`get_framework_guide("navigation-patterns")\` — Router.navigate, Router.navigateToPage`);
-    parts.push(`- \`get_model_guide("<TypeName>")\` — IkasCart, IkasProduct, IkasCustomer shapes`);
+    parts.push(`Call \`get_migration_guide("list")\` or \`get_framework_guide("list")\` for the full topic catalog.`);
     parts.push("");
     return parts.join("\n");
 }
@@ -1170,14 +1141,7 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
     if (customDataPropsForCallouts.length > 0) {
         parts.push(`## Custom Data Decisions to Make`);
         parts.push("");
-        parts.push(`Each prop below references an old \`customData\` type. The conversion table above shows the MCP's **default** choice based on shape — but you should verify it matches the data's actual semantics. **Heuristic:**`);
-        parts.push("");
-        parts.push(`- **Flat scalar set** (e.g. \`"left" | "right" | "center"\`) → new-system **enum prop** via \`config add-enum\`.`);
-        parts.push(`- **Structured record** (\`{image, link, title}\`, repeated in a list) → new-system **component** via \`config add-component\` + COMPONENT_LIST wiring.`);
-        parts.push("");
-        parts.push(`See \`get_migration_guide("custom-data-conversion")\` for worked examples (Position → enum; Slide → component; MenuItem → component).`);
-        parts.push("");
-        parts.push(`> **For each decision below, log it in MIGRATION.md under \`## Custom Data Decisions\`** with the format: \`- \\\`<CustomDataName>\\\` → enum/component \\\`<target name>\\\` (${new Date().toISOString().slice(0, 10)}) — reasoning\`.`);
+        parts.push(`Each prop below references an old \`customData\` type. Verify the MCP's default against the actual data semantics, then run the CLI command. **Log every decision in MIGRATION.md → \`## Custom Data Decisions\`** with reasoning. See \`get_migration_guide("custom-data-conversion")\` for the heuristic and worked examples.`);
         parts.push("");
         for (const p of customDataPropsForCallouts) {
             const cd = customDataMap.get(p.customDataId);
@@ -1206,56 +1170,83 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             else {
                 shape = cdType;
             }
+            // Build the field source + names list once so we can use it for the lost-fields enumeration
+            // AND for the component-path CLI template.
+            const fieldSource = cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST"
+                ? cd.nestedData?.[0]?.nestedData || []
+                : cd.nestedData || [];
+            const fieldDescriptions = fieldSource
+                .filter((f) => f.key)
+                .map((f) => `\`${f.key}\` (${f.type || "?"})`);
             parts.push(`### Prop \`${p.name || "?"}\` → customData \`${cdName}\``);
             parts.push("");
             parts.push(`**Shape:** \`${shape}\``);
             parts.push("");
-            let recommendation;
             if (shapeKind === "enum") {
-                recommendation = `**MCP default: enum prop.** This looks like a flat scalar set. Use \`config add-enum\` unless the data is actually used as a richer object (e.g. each "option" carries an image — in which case it's a component).`;
+                parts.push(`**Default: enum prop.** Flat scalar set; use \`config add-enum\`.`);
+                parts.push("");
+                const enumName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "Enum");
+                const enumOptions = (cd.enumOptions || []).reduce((acc, o) => {
+                    if (o.displayName && o.value)
+                        acc[o.displayName] = o.value;
+                    return acc;
+                }, {});
+                parts.push("```bash");
+                parts.push(`npx ikas-component config add-enum --name "${enumName}" --options '${JSON.stringify(enumOptions)}'`);
+                parts.push("```");
+                parts.push("");
+                parts.push(`If you believe this should be a component instead (e.g. each option secretly carries richer data not visible in the customData shape), see \`get_migration_guide("custom-data-conversion")\`.`);
+                parts.push("");
             }
             else if (shapeKind === "list" || shapeKind === "record") {
-                recommendation = `**MCP default: component + COMPONENT_LIST.** This has multiple fields per item — a single enum value can't carry the structure. Use \`config add-component\` for a child component, then wire it via \`filteredComponentIds\` on the parent.`;
+                const fieldCount = fieldDescriptions.length;
+                const isMinimal = fieldCount > 0 && fieldCount <= 2;
+                if (isMinimal) {
+                    parts.push(`⚠️ **This child would have only ${fieldCount} field${fieldCount === 1 ? "" : "s"}** (${fieldDescriptions.join(", ")}). \`COMPONENT_LIST\` is usually overkill at this size. **Prefer one of:**`);
+                    parts.push(`- repeated scalar props on the parent (\`title1\`/\`link1\`, \`title2\`/\`link2\`, …) for a small fixed count`);
+                    parts.push(`- a domain LIST prop type (\`LIST_OF_LINK\`, \`IMAGE_LIST\`, \`PRODUCT_LIST\`, …) when each item IS one domain object`);
+                    parts.push(`- \`COMPONENT_LIST\` (CLI command below) only if reordering in the editor is a real UX win`);
+                    parts.push("");
+                    parts.push(`See \`get_migration_guide("component-composition-decision-guide")\` for the full tree. Log your choice in MIGRATION.md → \`## Custom Data Decisions\`.`);
+                    parts.push("");
+                }
+                else {
+                    parts.push(`**Default: component + COMPONENT_LIST.** Multiple fields per item — a single enum value cannot carry this structure.`);
+                    parts.push("");
+                    if (fieldCount > 0) {
+                        parts.push(`⚠️ **Fields you would lose if you flatten this:** ${fieldDescriptions.join(", ")}. Flattening to a simpler prop type drops these from the editor UI permanently. **Do not "simplify for later"** — if the feature genuinely isn't wanted, log that explicitly in MIGRATION.md → \`## Notes\` with reasoning. Otherwise build the component.`);
+                        parts.push("");
+                    }
+                    parts.push(`> See \`get_migration_guide("component-composition-decision-guide")\` for when \`COMPONENT_LIST\` is overkill.`);
+                    parts.push("");
+                }
+                const compName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : `${sectionPascal}Item`);
+                const compPropsForCli = [];
+                for (const f of fieldSource) {
+                    if (!f.key)
+                        continue;
+                    let fType = f.type;
+                    if (fType === "SLIDER")
+                        fType = "NUMBER";
+                    else if (fType === "PRODUCT_DETAIL")
+                        fType = "PRODUCT";
+                    compPropsForCli.push({ name: f.key, displayName: f.name || f.key, type: fType });
+                }
+                parts.push("```bash");
+                if (isMinimal) {
+                    parts.push(`# Fallback: COMPONENT_LIST (use only if the simpler alternatives above don't fit)`);
+                }
+                parts.push(`npx ikas-component config add-component --name "${compName}" --type component --props '${JSON.stringify(compPropsForCli)}'`);
+                parts.push(`# Then on the parent, set the prop's filteredComponentIds to the new component's id.`);
+                parts.push("```");
+                parts.push("");
+                parts.push(`If you believe this should be an enum despite the structure, see \`get_migration_guide("custom-data-conversion")\`.`);
+                parts.push("");
             }
             else {
-                recommendation = `**MCP default: unable to classify automatically — you decide.**`;
+                parts.push(`**Unable to classify automatically — you decide.** See \`get_migration_guide("custom-data-conversion")\` for the enum-vs-component heuristic.`);
+                parts.push("");
             }
-            parts.push(recommendation);
-            parts.push("");
-            parts.push(`**Both CLI templates** (pick the one that matches your decision):`);
-            parts.push("");
-            parts.push(`Enum path:`);
-            parts.push("```bash");
-            const enumName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "Enum");
-            const enumOptions = (cd.enumOptions || []).reduce((acc, o) => {
-                if (o.displayName && o.value)
-                    acc[o.displayName] = o.value;
-                return acc;
-            }, {});
-            parts.push(`npx ikas-component config add-enum --name "${enumName}" --options '${JSON.stringify(enumOptions)}'`);
-            parts.push("```");
-            parts.push("");
-            parts.push(`Component path:`);
-            parts.push("```bash");
-            const compName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : `${sectionPascal}Item`);
-            const compPropsForCli = [];
-            const fieldSource = cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST"
-                ? cd.nestedData?.[0]?.nestedData || []
-                : cd.nestedData || [];
-            for (const f of fieldSource) {
-                if (!f.key)
-                    continue;
-                let fType = f.type;
-                if (fType === "SLIDER")
-                    fType = "NUMBER";
-                else if (fType === "PRODUCT_DETAIL")
-                    fType = "PRODUCT";
-                compPropsForCli.push({ name: f.key, displayName: f.name || f.key, type: fType });
-            }
-            parts.push(`npx ikas-component config add-component --name "${compName}" --type component --props '${JSON.stringify(compPropsForCli)}'`);
-            parts.push(`# Then on the parent, set the prop's filteredComponentIds to the new component's id.`);
-            parts.push("```");
-            parts.push("");
         }
     }
     // Enums to create first
@@ -1423,31 +1414,19 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
             parts.push("");
         }
     }
-    // Relevant guides
-    parts.push(`## ${nextStep + 1}. Relevant Guides (call these for details)`);
+    // Relevant guides — keep terse; LLM can call get_migration_guide("list") for the full catalog
+    parts.push(`## ${nextStep + 1}. Relevant Guides`);
     parts.push("");
     parts.push(`- \`get_migration_guide("react-to-preact")\` — code conversion patterns`);
-    parts.push(`- \`get_migration_guide("library-replacements")\` — library → vanilla Preact patterns`);
-    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — exact runtime shapes (.data vs .links)`);
-    if (children.length > 0) {
-        parts.push(`- \`get_migration_guide("component-renderer-limitations")\` — critical COMPONENT_LIST constraints`);
-        parts.push(`- \`get_framework_guide("component-renderer-patterns")\` — full IkasComponentRenderer usage`);
-        parts.push(`- \`get_migration_example("custom-dynamic-list-to-component-list")\` — concrete example`);
-    }
-    if (target.isHeader || target.isFooter) {
-        parts.push(`- \`get_framework_guide("header-footer-patterns")\` — header/footer specifics`);
+    parts.push(`- \`get_migration_guide("prop-runtime-shapes")\` — exact runtime shapes (\`.data\` vs \`.links\`, etc.)`);
+    if (children.length > 0 || target.isHeader || target.isFooter) {
+        parts.push(`- \`get_framework_guide("header-footer-patterns")\` — COMPONENT_LIST + IkasComponentRenderer wiring`);
     }
-    parts.push(`- \`get_framework_guide("common-pitfalls")\` — observer rules, common mistakes`);
     parts.push("");
     // Completion
     parts.push(`## ${nextStep + 2}. Mark Complete`);
     parts.push("");
-    parts.push(`Once the section builds cleanly with \`npx ikas-component build\`:`);
-    parts.push(`1. Edit \`MIGRATION.md\` at the project root with your file-editing tool (no MCP tool needed)`);
-    parts.push(`2. Change the checkbox for \`${sectionId}\` from \`[ ]\` to \`[x]\``);
-    parts.push(`3. Also mark each child component as \`[x]\``);
-    parts.push(`4. If you made customData enum-vs-component decisions, log them under \`## Custom Data Decisions\` (one bullet per decision with reasoning)`);
-    parts.push(`5. Append an entry to the **Notes** section of \`MIGRATION.md\` noting: libraries replaced, any props added beyond the generated plan, the actual folder name the CLI created (in case it differs from the name you passed — e.g., \`FAQ\` → \`Faq/\`), and any other decisions a future agent should know.`);
+    parts.push(`Once the section builds cleanly with \`npx ikas-component build\`: edit MIGRATION.md → tick \`[x]\` for \`${sectionId}\` and each child component, log any customData decisions under \`## Custom Data Decisions\`, and append a brief entry to \`## Notes\` with anything future sessions should know.`);
     parts.push("");
     return parts.join("\n");
 }