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

package/dist/index.js

@@ -15,6 +15,59 @@ function loadJsonFile(relativePath) {
     }
     return JSON.parse(fs.readFileSync(filePath, "utf-8"));
 }
+// Resolve theme.json from either raw string or absolute file path.
+// Exactly one of the two must be provided.
+function resolveThemeJson(themeJson, themeJsonPath) {
+    const hasInline = typeof themeJson === "string" && themeJson.length > 0;
+    const hasPath = typeof themeJsonPath === "string" && themeJsonPath.length > 0;
+    if (hasInline === hasPath) {
+        throw new Error("Provide exactly one of `theme_json` (raw JSON string) or `theme_json_path` (absolute path to theme.json).");
+    }
+    let raw;
+    if (hasPath) {
+        if (!path.isAbsolute(themeJsonPath)) {
+            throw new Error(`theme_json_path must be absolute: ${themeJsonPath}`);
+        }
+        if (!fs.existsSync(themeJsonPath)) {
+            throw new Error(`theme_json_path not found: ${themeJsonPath}`);
+        }
+        try {
+            raw = fs.readFileSync(themeJsonPath, "utf-8");
+        }
+        catch (e) {
+            throw new Error(`Failed to read theme_json_path "${themeJsonPath}": ${e.message}`);
+        }
+    }
+    else {
+        raw = themeJson;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Invalid JSON in theme.json: ${e.message}`);
+    }
+}
+// Atomic file write: temp file in same dir, then rename. Same-fs rename is atomic on POSIX.
+function writeFileAtomic(targetPath, content) {
+    const dir = path.dirname(targetPath);
+    const base = path.basename(targetPath);
+    const tmp = path.join(dir, `.${base}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`);
+    try {
+        fs.writeFileSync(tmp, content, "utf-8");
+        fs.renameSync(tmp, targetPath);
+    }
+    catch (e) {
+        try {
+            if (fs.existsSync(tmp))
+                fs.unlinkSync(tmp);
+        }
+        catch {
+            // ignore cleanup failure
+        }
+        throw e;
+    }
+}
 // Try multiple paths for storefront data (generated output or local data dir)
 function loadStorefrontData() {
     const paths = [
@@ -506,18 +559,22 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
     }
     const sharedSubs = oldSourceDir ? scanSharedSubcomponents(oldSourceDir) : [];
     const parts = [];
-    parts.push(`# Theme Migration Plan`);
+    parts.push(`# Theme Migration Plan — \`${projectName}\``);
     parts.push("");
     parts.push(`**Generated:** ${new Date().toISOString().slice(0, 10)}`);
-    parts.push(`**Project ID:** \`${projectName}\``);
     parts.push(`**Source:** ${components.length} old components, ${customData.filter(cd => cd.isRoot).length} custom data types, ${(theme.pages || []).length} pages`);
     parts.push("");
-    parts.push(`This file is the **source of truth** for the migration. All sessions must read it before starting work.`);
-    parts.push("");
-    parts.push(`## Status Legend`);
-    parts.push(`- \`[ ]\` Not started`);
-    parts.push(`- \`[~]\` In progress`);
-    parts.push(`- \`[x]\` Complete`);
+    parts.push(`> ## READ THIS FIRST`);
+    parts.push(`>`);
+    parts.push(`> This file is your responsibility from here. The MCP wrote this initial scaffold **once**. You own all updates — no MCP tool will modify this file again.`);
+    parts.push(`>`);
+    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(`>`);
+    parts.push(`> Status legend: \`[ ]\` not started · \`[~]\` in progress · \`[x]\` complete.`);
     parts.push("");
     parts.push(`## Foundation`);
     parts.push("");
@@ -537,27 +594,9 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
         parts.push(`- [ ] ${settings.fontFamily.name} (weights: ${settings.fontFamily.variants?.join(", ") || "default"})`);
         parts.push("");
     }
-    // Custom Enums
-    const enumCustomData = customData.filter(cd => cd.type === "ENUM" && cd.isRoot);
-    if (enumCustomData.length > 0) {
-        parts.push(`### Custom Enums (run these BEFORE any \`config add-component\`)`);
-        parts.push("");
-        for (const cd of enumCustomData) {
-            const enumName = cd.typescriptName || (cd.name ? cd.name.replace(/[^a-zA-Z0-9]/g, "") : "Enum");
-            const options = (cd.enumOptions || []).reduce((acc, o) => {
-                if (o.displayName && o.value)
-                    acc[o.displayName] = o.value;
-                return acc;
-            }, {});
-            const optionsStr = JSON.stringify(options);
-            parts.push(`- [ ] **${enumName}**`);
-            parts.push(`  \`\`\`bash`);
-            parts.push(`  npx ikas-component config add-enum --name "${enumName}" --options '${optionsStr}'`);
-            parts.push(`  \`\`\``);
-            parts.push(`  Save the returned \`enumId\` and update this file with: \`enumId: <id>\``);
-        }
-        parts.push("");
-    }
+    // (Custom Enums foundation subsection intentionally removed — see ## Custom Data Types below.
+    // Old customData entries are NOT pre-migrated as enums; each is a per-section decision.
+    // See get_migration_guide("custom-data-conversion") for the enum-vs-component heuristic.)
     // Shared sub-components
     if (sharedSubs.length > 0) {
         parts.push(`### Shared Sub-Components (→ \`src/sub-components/\`)`);
@@ -581,6 +620,51 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
         parts.push(`_Old source directory not provided — shared sub-components cannot be detected automatically. If you have access to the old source, call \`plan_migration\` again with \`old_source_dir\` to populate this section._`);
         parts.push("");
     }
+    parts.push(`> **This scan is partial.** \`scanSharedSubcomponents\` only detects relative imports used by **3 or more** old components. Atomic components used by fewer sections (often Button/Input/Card/icon primitives) will be missed. Scan \`src/\` yourself and add any others under \`## Source Code Analysis\` below.`);
+    parts.push("");
+    // Custom Data Types — deferred decisions (reference list, not checkboxes)
+    const rootCustomData = customData.filter((cd) => cd.isRoot);
+    if (rootCustomData.length > 0) {
+        // Build a usage map: which sections reference each customData type
+        const usageByCustomDataId = new Map();
+        for (const comp of components) {
+            const sectionName = comp.displayName || comp.dir || comp.id || "?";
+            for (const p of comp.props || []) {
+                if (p.type === "CUSTOM" && p.customDataId) {
+                    const list = usageByCustomDataId.get(p.customDataId) || [];
+                    if (!list.includes(sectionName))
+                        list.push(sectionName);
+                    usageByCustomDataId.set(p.customDataId, list);
+                }
+            }
+        }
+        parts.push(`### Custom Data Types — decide during section migration`);
+        parts.push("");
+        parts.push(`Each entry below is an OLD \`theme.customData[]\` type. Do **not** pre-migrate these as enums. When you migrate the section that uses one, decide:`);
+        parts.push(`- **Flat scalar set** (e.g. \`"left" | "right" | "center"\`) → new-system **enum prop** via \`config add-enum\`.`);
+        parts.push(`- **Structured record** (e.g. \`{image, link, title}\`, repeated in a list) → new-system **component** via \`config add-component\` + COMPONENT_LIST wiring on the parent.`);
+        parts.push("");
+        parts.push(`Log every decision in \`## Custom Data Decisions\` below. See \`get_migration_guide("custom-data-conversion")\` for the full heuristic and worked examples (Position, Slide, MenuItem).`);
+        parts.push("");
+        for (const cd of rootCustomData) {
+            const cdName = cd.typescriptName || cd.name || cd.id || "Unknown";
+            const cdType = cd.type || "?";
+            let shape = "";
+            if (cd.type === "ENUM") {
+                const opts = (cd.enumOptions || []).map((o) => o.value || o.displayName).filter(Boolean);
+                shape = ` — shape: \`enum {${opts.slice(0, 6).join(", ")}${opts.length > 6 ? ", ..." : ""}}\``;
+            }
+            else if (cd.nestedData && cd.nestedData.length > 0) {
+                const first = cd.nestedData[0];
+                const fields = (first?.nestedData || cd.nestedData || []).map((f) => `${f.key || f.name || "?"}: ${f.type || "?"}`).slice(0, 8);
+                shape = ` — shape: \`{${fields.join(", ")}}\``;
+            }
+            const usedBy = cd.id ? usageByCustomDataId.get(cd.id) || [] : [];
+            const usedByStr = usedBy.length > 0 ? ` — used by: ${usedBy.slice(0, 6).join(", ")}${usedBy.length > 6 ? `, +${usedBy.length - 6} more` : ""}` : ` — _not directly referenced by any section's props (may be nested inside another customData)_`;
+            parts.push(`- \`${cdName}\` (${cdType})${shape}${usedByStr}`);
+        }
+        parts.push("");
+    }
     // Sections queue
     parts.push(`## Sections`);
     parts.push("");
@@ -638,10 +722,32 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
         }
         parts.push("");
     }
+    // Source Code Analysis — placeholder for the LLM to fill in
+    parts.push(`## Source Code Analysis`);
+    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("");
+    // 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("");
     // Known Environmental Issues (agents fill in during work)
     parts.push(`## Known Environmental Issues`);
     parts.push("");
-    parts.push(`_Agents working on this migration: record any non-component build/TS errors here so future sessions don't waste time diagnosing them._`);
+    parts.push(`_Record any non-component build/TS errors here so future sessions don't waste time diagnosing them._`);
     parts.push("");
     parts.push(`- [ ] _(none recorded yet)_`);
     parts.push("");
@@ -651,20 +757,22 @@ function generateMigrationPlan(theme, projectName, oldSourceDir) {
     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, "<old section name>", "${projectName}")\`.`);
+    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. Run the CLI commands in the plan (they create parent + children with auto-generated types.ts).`);
-    parts.push(`5. Write \`index.tsx\` and \`styles.css\` using the patterns in the plan. DO NOT manually edit types.ts.`);
-    parts.push(`6. Mark the section \`[x]\` when it builds cleanly. Append a short note to the **Session Log** 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(`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("");
-    // Session Log — agents append notes here
-    parts.push(`## Session Log`);
+    // Notes — append-only log for decisions not captured elsewhere
+    parts.push(`## Notes`);
     parts.push("");
-    parts.push(`_Each agent: 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._`);
+    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("");
-    parts.push(`_After completing Foundation, also record which sub-components were built and which were skipped, e.g.:_`);
-    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(`<!-- 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("");
     // Cross-references
     parts.push(`## Cross-References`);
@@ -1057,6 +1165,99 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
         parts.push(`| \`${oldName}\` | ${oldType} | → | \`${newName}\` | ${newType} | ${notes} |`);
     }
     parts.push("");
+    // Custom Data Decision Callouts — per prop referencing a customData type
+    const customDataPropsForCallouts = (target.props || []).filter((p) => p.type === "CUSTOM" && p.customDataId && customDataMap.has(p.customDataId));
+    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("");
+        for (const p of customDataPropsForCallouts) {
+            const cd = customDataMap.get(p.customDataId);
+            if (!cd)
+                continue;
+            const cdName = cd.typescriptName || cd.name || cd.id || "Unknown";
+            const cdType = cd.type || "?";
+            let shape = "";
+            let shapeKind = "unknown";
+            if (cd.type === "ENUM") {
+                const opts = (cd.enumOptions || []).map((o) => o.value || o.displayName).filter(Boolean);
+                shape = `enum {${opts.slice(0, 6).join(", ")}${opts.length > 6 ? ", ..." : ""}}`;
+                shapeKind = "enum";
+            }
+            else if (cd.type === "DYNAMIC_LIST" || cd.type === "STATIC_LIST") {
+                const first = cd.nestedData?.[0];
+                const fields = (first?.nestedData || []).map((f) => `${f.key || f.name || "?"}: ${f.type || "?"}`);
+                shape = `${cdType} of {${fields.slice(0, 6).join(", ")}}`;
+                shapeKind = "list";
+            }
+            else if (cd.type === "OBJECT") {
+                const fields = (cd.nestedData || []).map((f) => `${f.key || f.name || "?"}: ${f.type || "?"}`);
+                shape = `OBJECT {${fields.slice(0, 6).join(", ")}}`;
+                shapeKind = "record";
+            }
+            else {
+                shape = cdType;
+            }
+            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).`;
+            }
+            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.`;
+            }
+            else {
+                recommendation = `**MCP default: unable to classify automatically — you decide.**`;
+            }
+            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
     if (enumsNeeded.length > 0) {
         parts.push(`## 3. Create Enums FIRST (if not already done)`);
@@ -1242,10 +1443,11 @@ function generateSectionMigrationPlan(theme, sectionName, projectName, oldSource
     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`);
+    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. Append an entry to the **Session Log** 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(`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("");
     return parts.join("\n");
 }
@@ -1271,6 +1473,54 @@ function matchScore(text, query) {
     }
     return score;
 }
+// Levenshtein edit distance — small DP, fine for the 28 short kebab-case section template names.
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    const m = a.length;
+    const n = b.length;
+    const prev = new Array(n + 1);
+    const curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, // insertion
+            prev[j] + 1, // deletion
+            prev[j - 1] + cost // substitution
+            );
+        }
+        for (let j = 0; j <= n; j++)
+            prev[j] = curr[j];
+    }
+    return prev[n];
+}
+// Suggest up to `max` closest candidates for an unknown input.
+// Primary: matchScore (substring/word). Fallback: Levenshtein when nothing scores well.
+function suggestClosestNames(input, candidates, opts) {
+    const min = opts?.min ?? 8;
+    const max = opts?.max ?? 3;
+    const scored = candidates
+        .map((c) => ({ name: c, score: matchScore(c, input) }))
+        .filter((s) => s.score >= min)
+        .sort((a, b) => b.score - a.score);
+    if (scored.length > 0)
+        return scored.slice(0, max).map((s) => s.name);
+    // Levenshtein fallback — tolerate up to ceil(len/3) edits.
+    const maxDistance = Math.max(1, Math.ceil(input.length / 3));
+    const lower = input.toLowerCase();
+    const edits = candidates
+        .map((c) => ({ name: c, d: levenshtein(lower, c.toLowerCase()) }))
+        .filter((s) => s.d <= maxDistance)
+        .sort((a, b) => a.d - b.d);
+    return edits.slice(0, max).map((s) => s.name);
+}
 function searchFunctions(query) {
     const scored = storefrontData.functions
         .map((fn) => {
@@ -2099,7 +2349,7 @@ server.tool("get_prop_types", "Get all available ikas.config.json prop types wit
 const sectionTemplateKeys = sectionTemplateNames.length > 0
     ? sectionTemplateNames
     : null;
-server.tool("get_section_template", "Get the root files of a starter section template (index.tsx, types.ts, styles.css, ikas-config-snippet.json). Returns ONLY the section's root files plus the NAMES of any children, components, sub-components, utilities, and hooks — their files are NOT included by default. To view one item's full implementation, call `get_section_child(section, name, kind)` where kind is 'children' (default), 'components', or 'sub-components'. To bundle subtrees inline, pass `include`. Call `list_section_types()` for available section types. Use the API patterns shown — create your own JSX structure, CSS class names, and visual design.", {
+server.tool("get_section_template", "Get the root files of a starter section template (index.tsx, types.ts, styles.css, ikas-config-snippet.json). Returns ONLY the section's root files plus the NAMES of any children, components, sub-components, utilities, and hooks — their files are NOT included by default. To view one item's full implementation, call `get_section_child(section, name, kind)` where kind is 'children' (default), 'components', or 'sub-components'. To bundle subtrees inline, pass `include`. Call `list_section_types()` for available section types. Use the API patterns shown — create your own JSX structure, CSS class names, and visual design. **Container sections** (Header, Footer, ProductDetail, etc.) host child components via a `COMPONENT_LIST` slot — the response emits a complete multi-step Setup Recipe (create children → capture ids → wire `filteredComponentIds` via `config update-prop`). Follow all steps; the parent alone produces an empty section.", {
     sectionType: z
         .string()
         .describe("The section type (call `list_section_types()` for valid values)"),
@@ -2141,11 +2391,19 @@ server.tool("get_section_template", "Get the root files of a starter section tem
     }
     const normalizedType = normalizeName(sectionType);
     if (!sectionTemplateNames.includes(normalizedType)) {
+        const suggestions = suggestClosestNames(normalizedType, sectionTemplateNames);
+        let suggestionText = "";
+        if (suggestions.length === 1) {
+            suggestionText = ` Did you mean "${suggestions[0]}"?`;
+        }
+        else if (suggestions.length > 1) {
+            suggestionText = ` Did you mean one of: ${suggestions.map((s) => `"${s}"`).join(", ")}?`;
+        }
         return {
             content: [
                 {
                     type: "text",
-                    text: `Unknown section type "${sectionType}". Call \`list_section_types()\` to see all ${sectionTemplateNames.length} valid types.`,
+                    text: `Unknown section type "${sectionType}".${suggestionText} Call \`list_section_types()\` to see all ${sectionTemplateNames.length} valid types.`,
                 },
             ],
         };
@@ -2174,6 +2432,18 @@ server.tool("get_section_template", "Get the root files of a starter section tem
         `## ${bundle.title} — API Integration Pattern Reference`,
         "",
     ];
+    // Detect container-section pattern (COMPONENT_LIST with `<id-of-X>` placeholders).
+    // Surface this BEFORE every other warning so the LLM cannot miss the wiring requirement.
+    // The full recipe (commands, captured-id placeholders, update-prop call) is appended near
+    // the end of the response in the existing recipe-builder block.
+    {
+        const snippetStrForBanner = bundle.rootFiles["ikas-config-snippet.json"];
+        if (snippetStrForBanner && /<id-of-[A-Za-z0-9_]+>/.test(snippetStrForBanner)) {
+            const childMatches = Array.from(snippetStrForBanner.matchAll(/<id-of-([A-Za-z0-9_]+)>/g));
+            const uniqueChildren = Array.from(new Set(childMatches.map((m) => m[1])));
+            parts.push(`> 🔧 **CONTAINER SECTION — required wiring.** This template hosts ${uniqueChildren.length} child component${uniqueChildren.length === 1 ? "" : "s"} (${uniqueChildren.map((n) => `\`${n}\``).join(", ")}) via a \`COMPONENT_LIST\` slot. Creating the parent alone produces an empty, unusable section. **You MUST follow the full Setup Recipe below**: create each child → capture its \`componentId\` → wire them into the parent's \`filteredComponentIds\` with \`config update-prop\`. Component ids are opaque random strings (e.g. \`7ojrigep-Eml9n5sN3i\`) — they cannot be derived from names, and the CLI rejects unknown ids.`, "");
+        }
+    }
     if (anyOutstandingSubtree) {
         parts.push("> **PARTIAL TEMPLATE — NOT A COMPLETE IMPLEMENTATION.** The files below are the section's root files only. The section also ships with child components, local components, and/or shared sub-components whose files are **not included** in this response. To view one's full implementation, call `get_section_child(section, name, kind)` for each item you need (kind = `children`, `components`, or `sub-components`). The root `index.tsx` alone is not a complete reference — its imports resolve to files that live in those subtrees.", "");
     }
@@ -2242,7 +2512,10 @@ server.tool("get_section_template", "Get the root files of a starter section tem
     renderInlineSubtree("children", bundle.childContents);
     renderInlineSubtree("components", bundle.componentContents);
     renderInlineSubtree("sub-components", bundle.subComponentContents);
-    // Generate a ready-to-run CLI command from the config snippet
+    // Generate a ready-to-run CLI recipe from the config snippet. If the parent's
+    // filteredComponentIds reference `<id-of-X>` placeholders, expand into a
+    // multi-step recipe (create children → create parent → wire filteredComponentIds)
+    // so the LLM cannot skip the wiring step.
     const configSnippetStr = bundle.rootFiles["ikas-config-snippet.json"];
     if (configSnippetStr) {
         try {
@@ -2250,26 +2523,102 @@ server.tool("get_section_template", "Get the root files of a starter section tem
             const compName = configSnippet.name || normalizedType;
             const compType = configSnippet.type || "section";
             const propsArr = configSnippet.props || [];
-            let cliCommand = `npx ikas-component config add-component --name "${compName}" --type ${compType}`;
-            if (configSnippet.isHeader)
-                cliCommand += " --isHeader";
-            if (configSnippet.isFooter)
-                cliCommand += " --isFooter";
-            if (propsArr.length > 0) {
-                const propsJson = JSON.stringify(propsArr.map((p) => {
-                    const prop = {
-                        name: p.name,
-                        type: p.type,
-                    };
-                    if (p.displayName)
-                        prop.displayName = p.displayName;
-                    if (p.required)
-                        prop.required = true;
-                    return prop;
-                }));
-                cliCommand += ` --props '${propsJson}'`;
+            // Strip filteredComponentIds for the parent's add-component call (wired
+            // separately below). Preserve name/type/displayName/required so the LLM gets the prop shape.
+            const parentPropsForAdd = propsArr.map((p) => {
+                const out = { name: p.name, type: p.type };
+                if (p.displayName)
+                    out.displayName = p.displayName;
+                if (p.required)
+                    out.required = true;
+                return out;
+            });
+            const placeholderRe = /^<id-of-(.+)>$/;
+            const slotPlans = [];
+            const allChildNames = new Set();
+            for (const p of propsArr) {
+                if ((p.type === "COMPONENT_LIST" || p.type === "COMPONENT") &&
+                    Array.isArray(p.filteredComponentIds)) {
+                    const childNames = [];
+                    for (const entry of p.filteredComponentIds) {
+                        const m = typeof entry === "string" && entry.match(placeholderRe);
+                        if (m) {
+                            childNames.push(m[1]);
+                            allChildNames.add(m[1]);
+                        }
+                    }
+                    if (childNames.length > 0) {
+                        slotPlans.push({ propName: p.name, childNames });
+                    }
+                }
+            }
+            const childPlans = [];
+            for (const childName of allChildNames) {
+                const childSnippetPath = path.join(SECTION_TEMPLATES_DIR, normalizedType, "children", childName, "ikas-config-snippet.json");
+                let propsJson = "[]";
+                let hasTemplate = false;
+                if (fs.existsSync(childSnippetPath)) {
+                    hasTemplate = true;
+                    try {
+                        const childSnippet = JSON.parse(fs.readFileSync(childSnippetPath, "utf-8"));
+                        const childProps = (childSnippet.props || []).map((p) => {
+                            const out = { name: p.name, type: p.type };
+                            if (p.displayName)
+                                out.displayName = p.displayName;
+                            if (p.required)
+                                out.required = true;
+                            return out;
+                        });
+                        propsJson = JSON.stringify(childProps);
+                    }
+                    catch {
+                        // fall through with []
+                    }
+                }
+                childPlans.push({ name: childName, propsJson, hasTemplate });
+            }
+            const baseFlags = (configSnippet.isHeader ? " --isHeader" : "") +
+                (configSnippet.isFooter ? " --isFooter" : "");
+            const parentPropsJsonStr = parentPropsForAdd.length > 0
+                ? ` --props '${JSON.stringify(parentPropsForAdd)}'`
+                : "";
+            if (slotPlans.length > 0) {
+                parts.push("---", "");
+                parts.push(`### Setup Recipe (run in order — ${childPlans.length} child component${childPlans.length === 1 ? "" : "s"} + 1 parent + wiring)`);
+                parts.push("");
+                parts.push(`> ⚠️ **This section is a CONTAINER.** It hosts child components via ${slotPlans.length === 1 ? "a COMPONENT_LIST slot" : "COMPONENT_LIST slots"} (\`${slotPlans.map((s) => s.propName).join("`, `")}\`). Creating the parent alone is **not enough** — you MUST also create the child components and wire their opaque ids into the parent's \`filteredComponentIds\`. Skipping the wiring leaves the slot empty and the section unusable.`, "");
+                parts.push("**Step 1 — Create each child component, and capture its `componentId` from the JSON response:**");
+                parts.push("", "```bash");
+                for (const ch of childPlans) {
+                    parts.push(`npx ikas-component config add-component --name "${ch.name}" --type component --props '${ch.propsJson}'`);
+                    parts.push(`# → { "success": true, "componentId": "<capture as ${ch.name.toUpperCase()}_ID>", ... }`);
+                    if (!ch.hasTemplate) {
+                        parts.push(`# (no children/${ch.name}/ template in this section bundle — \`--props '[]'\` is a stub; add real props for ${ch.name} as needed)`);
+                    }
+                }
+                parts.push("```", "");
+                parts.push("**Step 2 — Create the parent section (without `filteredComponentIds` yet — those are wired in Step 3):**");
+                parts.push("", "```bash");
+                parts.push(`npx ikas-component config add-component --name "${compName}" --type ${compType}${baseFlags}${parentPropsJsonStr}`);
+                parts.push("```", "");
+                parts.push("**Step 3 — Wire each slot to its allowed children using the ids captured in Step 1:**");
+                parts.push("", "```bash");
+                for (const slot of slotPlans) {
+                    const idsArr = slot.childNames.map((n) => `<${n.toUpperCase()}_ID>`);
+                    parts.push(`npx ikas-component config update-prop --component "${compName}" --prop ${slot.propName} \\`);
+                    parts.push(`  --filteredComponentIds '${JSON.stringify(idsArr)}'`);
+                }
+                parts.push("```", "");
+                parts.push("Replace each `<X_ID>` placeholder above with the real `componentId` from the corresponding Step 1 response (or look ids up with `config list`). The CLI rejects unknown ids with a structured error — there is no silent failure mode.");
+                parts.push("");
+                parts.push("**Do NOT manually create or edit `types.ts`** — the CLI commands above regenerate it automatically.");
+                parts.push("");
+            }
+            else {
+                // No child slots — single-step parent command (preserves previous behaviour)
+                const cliCommand = `npx ikas-component config add-component --name "${compName}" --type ${compType}${baseFlags}${parentPropsJsonStr}`;
+                parts.push("---", "", "### CLI Command (run this first)", "", "```bash", cliCommand, "```", "", "**Do NOT manually create or edit `types.ts`** — the CLI command above generates it automatically.", "");
             }
-            parts.push("---", "", "### CLI Command (run this first)", "", "```bash", cliCommand, "```", "", "**Do NOT manually create or edit `types.ts`** — the CLI command above generates it automatically.", "", "**`filteredComponentIds` placeholders:** Any entry like `\"<id-of-Navbar>\"` in `filteredComponentIds` is a placeholder, not a literal value. Component ids are opaque random strings and cannot be derived from names. Create each referenced child component first with `config add-component` (which returns the new `componentId` in its JSON response), or read existing ids with `config list`, then substitute the real id into the parent's `filteredComponentIds` via `config add-prop`/`config update-prop`.", "");
         }
         catch {
             // ignore parse errors
@@ -2511,7 +2860,7 @@ const migrationTopicAliases = {
 const migrationTopicKeys = migrationData
     ? Object.keys(migrationData.topics)
     : [];
-server.tool("get_migration_guide", `Get a migration guide for converting old ikas themes to the new code-component system.${migrationTopicKeys.length > 0 ? ` Available topics: ${migrationTopicKeys.join(", ")}. Also supports aliases like "custom", "slider", "react", "libraries", "imports", "settings".` : ""} Call with topic "list" to see all available topics.`, { topic: z.string().describe("Migration topic key, alias, or 'list' to see all topics") }, async ({ topic }) => {
+server.tool("get_migration_guide", `Get a migration guide for converting old ikas themes to the new code-component system. **Start with \`get_migration_guide("iterative-workflow")\` if you're new to this MCP** — it explains the MCP-vs-LLM responsibility split and the four phases.${migrationTopicKeys.length > 0 ? ` Available topics: ${migrationTopicKeys.join(", ")}. Also supports aliases like "custom", "slider", "react", "libraries", "imports", "settings".` : ""} Call with topic "list" to see all available topics.`, { topic: z.string().describe("Migration topic key, alias, or 'list' to see all topics") }, async ({ topic }) => {
     if (!migrationData) {
         return { content: [{ type: "text", text: "Migration data not available. Ensure data/migration.json exists." }] };
     }
@@ -2595,39 +2944,95 @@ server.tool("get_migration_example", `Get a concrete before/after migration exam
     return { content: [{ type: "text", text: parts.join("\n") }] };
 });
 // Tool: plan_migration
-server.tool("plan_migration", "Generate a complete, resumable migration plan (MIGRATION.md) for converting an old ikas theme to the new code-component system. The LLM should save the returned markdown to <new-project-root>/MIGRATION.md as the source of truth for the entire migration. This is the FIRST tool to call for any multi-section (>5 sections) theme migration. Output includes: extracted CSS variables, font setup, custom enums with CLI commands, shared sub-components (when old_source_dir provided), and an ordered section queue grouped by complexity with canonical component IDs.", {
-    theme_json: z.string().describe("Raw JSON content of the old theme.json"),
-    project_name: z.string().optional().describe("Target new project name, used to prefix component IDs (default: 'my-theme')"),
-    old_source_dir: z.string().optional().describe("Absolute path to the old project's src/ directory. When provided, the tool scans .tsx files to detect shared sub-components used across 3+ components."),
-}, async ({ theme_json, project_name, old_source_dir }) => {
+server.tool("plan_migration", "Generate the **initial** migration plan and (when `project_root` is provided) write it to <project_root>/MIGRATION.md. **This is the only time the MCP writes that file.** From here, you own it: tick checkboxes as you finish work, log custom-data decisions, scan the old source for atomic components (Button, Input, Card, etc.) that theme.json doesn't see, and append them to MIGRATION.md yourself. theme.json is incomplete by design — the MCP can only describe what's listed there. Pass `theme_json_path` for large themes (raw `theme_json` string is supported for backward compat but fails on real-world sizes).", {
+    theme_json: z.string().optional().describe("Raw JSON content of the old theme.json. EITHER this OR theme_json_path is required (not both). For real themes use theme_json_path — raw strings exceed tool/context limits at production sizes."),
+    theme_json_path: z.string().optional().describe("Absolute path to the old theme.json file on disk. Preferred for any real-world theme."),
+    project_name: z.string().optional().describe("Target new project name, used to prefix migration-tracking IDs (default: 'my-theme')"),
+    old_source_dir: z.string().optional().describe("Absolute path to the old project's src/ directory. When provided, the tool scans .tsx files to detect shared sub-components used across 3+ components. This scan is partial — atomic components used by only 1-2 sections will be missed and must be added by the LLM."),
+    project_root: z.string().optional().describe("Absolute path to the new project root. When provided, the MCP writes MIGRATION.md to <project_root>/MIGRATION.md and returns a short summary instead of the full markdown body."),
+    overwrite: z.boolean().optional().describe("If MIGRATION.md already exists at <project_root>/MIGRATION.md and is non-empty, refuse the write unless this is true. Default: false."),
+}, async ({ theme_json, theme_json_path, project_name, old_source_dir, project_root, overwrite }) => {
     try {
-        const parsed = JSON.parse(theme_json);
+        const parsed = resolveThemeJson(theme_json, theme_json_path);
         const projectName = project_name || "my-theme";
         const plan = generateMigrationPlan(parsed, projectName, old_source_dir);
-        return { content: [{ type: "text", text: plan }] };
+        if (!project_root) {
+            return { content: [{ type: "text", text: plan }] };
+        }
+        // Write MIGRATION.md to project_root
+        if (!path.isAbsolute(project_root)) {
+            throw new Error(`project_root must be absolute: ${project_root}`);
+        }
+        if (!fs.existsSync(project_root)) {
+            throw new Error(`project_root not found: ${project_root}`);
+        }
+        if (!fs.statSync(project_root).isDirectory()) {
+            throw new Error(`project_root is not a directory: ${project_root}`);
+        }
+        const targetPath = path.join(project_root, "MIGRATION.md");
+        if (fs.existsSync(targetPath)) {
+            const existing = fs.readFileSync(targetPath, "utf-8").trim();
+            if (existing.length > 0 && !overwrite) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Refusing to overwrite existing non-empty MIGRATION.md at ${targetPath}. ` +
+                                `Pass overwrite: true to replace it, or delete the file first. ` +
+                                `If you intended to RESUME an in-progress migration, do not call plan_migration again — read the existing MIGRATION.md and continue from the first unchecked item.`,
+                        },
+                    ],
+                };
+            }
+        }
+        writeFileAtomic(targetPath, plan);
+        const components = parsed.components || [];
+        const customData = parsed.customData || [];
+        const cssVarCount = parsed.settings?.colors?.length || 0;
+        const fontCount = parsed.settings?.fontFamily?.name ? 1 : 0;
+        const customDataCount = customData.filter((cd) => cd.isRoot).length;
+        const sectionCount = components.length;
+        const summary = [
+            `Wrote initial migration plan to ${targetPath}`,
+            "",
+            `**Summary:**`,
+            `- Sections to migrate: ${sectionCount}`,
+            `- CSS variables: ${cssVarCount}`,
+            `- Fonts: ${fontCount}`,
+            `- Custom data types (deferred decisions, not pre-migrated): ${customDataCount}`,
+            "",
+            `**Next steps for the LLM:**`,
+            `1. Read \`${targetPath}\` start-to-finish. The "READ THIS FIRST" preamble explains your responsibilities.`,
+            `2. Scan the old source directory (\`${old_source_dir || "<old-src>"}\`) for atomic components (Button, Input, Card, icons, etc.) NOT referenced from theme.json. Add them to \`## Source Code Analysis\` in MIGRATION.md.`,
+            `3. Start the Foundation work (CSS variables, fonts, shared sub-components).`,
+            `4. For each section, call \`get_section_migration_plan({theme_json_path, section_name, project_name})\`. The MCP will tell you which props need enum-vs-component decisions.`,
+            `5. Log every custom-data decision in \`## Custom Data Decisions\`. Tick checkboxes as you finish.`,
+        ].join("\n");
+        return { content: [{ type: "text", text: summary }] };
     }
     catch (err) {
         return {
-            content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}. Make sure theme_json is valid JSON.` }],
+            content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
         };
     }
 });
 // Tool: get_section_migration_plan
-server.tool("get_section_migration_plan", "Get a concrete, actionable migration plan for a single section/component from the old theme. Returns: old source file paths to read, a prop-by-prop conversion table, CLI commands to create children and parent components (with auto-generated types.ts), library replacement hints, and cross-references to relevant framework/migration guides. Use this tool once per section in Phase C of the iterative workflow. Call after `plan_migration` has generated MIGRATION.md.", {
-    theme_json: z.string().describe("Raw JSON content of the old theme.json"),
+server.tool("get_section_migration_plan", "Returns concrete CLI commands and prop conversions for one section. For each prop that references a customData type, you'll see a 'Decide: enum or component?' callout — log your decision in MIGRATION.md under `## Custom Data Decisions`. Pass `theme_json_path` for large themes.", {
+    theme_json: z.string().optional().describe("Raw JSON content of the old theme.json. EITHER this OR theme_json_path is required (not both)."),
+    theme_json_path: z.string().optional().describe("Absolute path to the old theme.json file on disk. Preferred for any real-world theme."),
     section_name: z.string().describe("Old component name (e.g. 'Navbar', 'ProductGrid') or dir name, OR the new section ID (e.g. 'my-theme-navbar')"),
     project_name: z.string().optional().describe("Target new project name (must match what was used in plan_migration). Default: 'my-theme'"),
     old_source_dir: z.string().optional().describe("Absolute path to old src/ directory (used to output exact source file paths to read)"),
-}, async ({ theme_json, section_name, project_name, old_source_dir }) => {
+}, async ({ theme_json, theme_json_path, section_name, project_name, old_source_dir }) => {
     try {
-        const parsed = JSON.parse(theme_json);
+        const parsed = resolveThemeJson(theme_json, theme_json_path);
         const projectName = project_name || "my-theme";
         const plan = generateSectionMigrationPlan(parsed, section_name, projectName, old_source_dir);
         return { content: [{ type: "text", text: plan }] };
     }
     catch (err) {
         return {
-            content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}. Make sure theme_json is valid JSON.` }],
+            content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
         };
     }
 });