@ikas/component-cli 1.4.0-beta.10 → 1.4.0-beta.100

package/dist/commands/config.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import * as fs from "fs";
 import * as path from "path";
-import { PROP_TYPES, toPascalCase, generateTypesFile, generateGlobalTypesFile, collectUsedEnumIds, generateComponentFile, generateStylesFile, generateProjectId, generateComponentId, generateUniqueId, updateBarrelExport, findPropGroup, collectPropGroupIds, movePropGroupInTree, validateFilteredComponentIds, } from "../utils/component-helpers.js";
+import { PROP_TYPES, toPascalCase, generateTypesFile, generateGlobalTypesFile, collectUsedEnumIds, generateComponentFile, generateStylesFile, generateProjectId, isValidProjectId, generateComponentId, generateUniqueId, updateBarrelExport, findPropGroup, collectPropGroupIds, movePropGroupInTree, validateFilteredComponentIds, } from "../utils/component-helpers.js";
 function loadConfig() {
     const configPath = path.resolve(process.cwd(), "ikas.config.json");
     if (!fs.existsSync(configPath)) {
@@ -31,7 +31,10 @@ function resolveComponent(config, ref) {
             success: false,
             error: "Component reference required: pass --id (preferred) or --name (exact PascalCase). " +
                 "Run `ikas-component config list-components` to see canonical ids.",
-            validComponents: config.components.map((c) => ({ id: c.id, name: c.name })),
+            validComponents: config.components.map((c) => ({
+                id: c.id,
+                name: c.name,
+            })),
         }));
         process.exit(1);
     }
@@ -52,7 +55,10 @@ function resolveComponent(config, ref) {
                 ? `Component not found: id="${id}".`
                 : `Component not found: name="${name}". Names are matched exactly (PascalCase, no normalization).`,
             lookup: id ? { id } : { name },
-            validComponents: config.components.map((c) => ({ id: c.id, name: c.name })),
+            validComponents: config.components.map((c) => ({
+                id: c.id,
+                name: c.name,
+            })),
             hint: "Use --id (preferred) or exact PascalCase --name. " +
                 "Run `ikas-component config list-components` to see canonical ids.",
         }));
@@ -144,6 +150,19 @@ function camelCaseToDisplayName(name) {
         .replace(/([a-z])([A-Z])/g, "$1 $2")
         .replace(/^./, (c) => c.toUpperCase());
 }
+const ALLOWED_PROP_FIELDS = new Set([
+    "name",
+    "displayName",
+    "type",
+    "required",
+    "description",
+    "defaultValue",
+    "groupId",
+    "typeId",
+    "enumTypeId",
+    "filteredComponentIds",
+    "privateVarMap",
+]);
 /**
  * Parse and validate the --props JSON flag for add-component.
  * Returns validated ComponentProp[] or exits with error.
@@ -171,6 +190,16 @@ async function parsePropsFlag(propsJson, config, configPath) {
     const props = [];
     for (const raw of rawProps) {
         const r = raw;
+        const unknownFields = Object.keys(r).filter((k) => !ALLOWED_PROP_FIELDS.has(k));
+        if (unknownFields.length > 0) {
+            console.log(JSON.stringify({
+                success: false,
+                error: `Unknown field(s) in --props entry: ${unknownFields.join(", ")}. ` +
+                    `Allowed: ${[...ALLOWED_PROP_FIELDS].join(", ")}. ` +
+                    `Note: use "groupId" (not "group") and "defaultValue" (not "default") in --props JSON.`,
+            }));
+            process.exit(1);
+        }
         if (!r.name || typeof r.name !== "string") {
             console.log(JSON.stringify({
                 success: false,
@@ -211,6 +240,24 @@ async function parsePropsFlag(propsJson, config, configPath) {
             }));
             process.exit(1);
         }
+        // Validate LINK / LIST_OF_LINK defaultValue shape (reject JSON strings and legacy { href })
+        if ((propType === "LINK" || propType === "LIST_OF_LINK") &&
+            r.defaultValue !== undefined) {
+            const linkError = validateLinkDefaultValue(propType, r.defaultValue, r.name);
+            if (linkError) {
+                console.log(JSON.stringify({ success: false, error: linkError }));
+                process.exit(1);
+            }
+        }
+        // Validate SVG / SVG_LIST defaultValue (reject malformed/oversized/unsafe SVG)
+        if ((propType === "SVG" || propType === "SVG_LIST") &&
+            r.defaultValue !== undefined) {
+            const svgError = validateSvgDefaultValue(propType, r.defaultValue, r.name);
+            if (svgError) {
+                console.log(JSON.stringify({ success: false, error: svgError }));
+                process.exit(1);
+            }
+        }
         // Auto-generate displayName if omitted
         const displayName = typeof r.displayName === "string" && r.displayName
             ? r.displayName
@@ -235,7 +282,10 @@ async function parsePropsFlag(propsJson, config, configPath) {
                 process.exit(1);
             }
             // Validate enum type exists (checks config then live dev server)
-            if (config && configPath && typeof r.enumTypeId === "string" && !r.enumTypeId.startsWith("@ikas/")) {
+            if (config &&
+                configPath &&
+                typeof r.enumTypeId === "string" &&
+                !r.enumTypeId.startsWith("@ikas/")) {
                 const resolved = await resolveEnumType(r.enumTypeId, config, configPath);
                 if (!resolved) {
                     console.log(JSON.stringify({
@@ -254,9 +304,7 @@ async function parsePropsFlag(propsJson, config, configPath) {
             ...(typeof r.description === "string" && r.description
                 ? { description: r.description }
                 : {}),
-            ...(r.defaultValue !== undefined
-                ? { defaultValue: r.defaultValue }
-                : {}),
+            ...(r.defaultValue !== undefined ? { defaultValue: r.defaultValue } : {}),
             ...(typeof r.groupId === "string" && r.groupId
                 ? { groupId: r.groupId }
                 : {}),
@@ -266,11 +314,19 @@ async function parsePropsFlag(propsJson, config, configPath) {
             ...(propType === "ENUM" && typeof r.enumTypeId === "string"
                 ? { enumTypeId: r.enumTypeId }
                 : {}),
-            ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") && r.filteredComponentIds && Array.isArray(r.filteredComponentIds)
-                ? { filteredComponentIds: assertKnownComponentIds(r.filteredComponentIds, config) }
+            ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") &&
+                r.filteredComponentIds &&
+                Array.isArray(r.filteredComponentIds)
+                ? {
+                    filteredComponentIds: assertKnownComponentIds(r.filteredComponentIds, config),
+                }
                 : {}),
-            ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") && r.privateVarMap && typeof r.privateVarMap === "object"
-                ? { privateVarMap: r.privateVarMap }
+            ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") &&
+                r.privateVarMap &&
+                typeof r.privateVarMap === "object"
+                ? {
+                    privateVarMap: r.privateVarMap,
+                }
                 : {}),
         };
         props.push(prop);
@@ -302,6 +358,18 @@ async function addComponent(name, options) {
     if (!config.projectId) {
         config.projectId = generateProjectId();
     }
+    else if (!isValidProjectId(config.projectId)) {
+        // A malformed projectId (hand-edited config) breaks the editor's republish
+        // stability: published/local id prefixes stop matching and every publish
+        // INSERTs duplicate design elements. Fail fast instead of corrupting data.
+        console.log(JSON.stringify({
+            success: false,
+            error: `Invalid projectId "${config.projectId}" in ikas.config.json. ` +
+                "projectId must be at least 6 alphanumeric characters (no '-' or '_'). " +
+                "Restore the original generated value — do not hand-edit it.",
+        }));
+        process.exit(1);
+    }
     // Parse --props (and validate filteredComponentIds) BEFORE any filesystem side-effects
     // so a bad payload doesn't leave an empty component directory behind.
     const props = options.props
@@ -407,7 +475,9 @@ async function addProp(ref, options) {
     }
     // Validate that enumTypeId references an existing enum type
     // (checks config.customTypes first, then falls back to the live dev server)
-    if (propType === "ENUM" && options.enumTypeId && !options.enumTypeId.startsWith("@ikas/")) {
+    if (propType === "ENUM" &&
+        options.enumTypeId &&
+        !options.enumTypeId.startsWith("@ikas/")) {
         const resolved = await resolveEnumType(options.enumTypeId, config, configPath);
         if (!resolved) {
             console.log(JSON.stringify({
@@ -437,32 +507,66 @@ async function addProp(ref, options) {
     }
     // Parse filteredComponentIds JSON for COMPONENT/COMPONENT_LIST
     let parsedFilteredIds;
-    if (options.filteredComponentIds && (propType === "COMPONENT" || propType === "COMPONENT_LIST")) {
+    if (options.filteredComponentIds &&
+        (propType === "COMPONENT" || propType === "COMPONENT_LIST")) {
         try {
             parsedFilteredIds = JSON.parse(options.filteredComponentIds);
             if (!Array.isArray(parsedFilteredIds)) {
-                console.log(JSON.stringify({ success: false, error: "--filteredComponentIds must be a JSON array of strings." }));
+                console.log(JSON.stringify({
+                    success: false,
+                    error: "--filteredComponentIds must be a JSON array of strings.",
+                }));
                 process.exit(1);
             }
         }
         catch {
-            console.log(JSON.stringify({ success: false, error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}` }));
+            console.log(JSON.stringify({
+                success: false,
+                error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}`,
+            }));
             process.exit(1);
         }
         assertKnownComponentIds(parsedFilteredIds, config);
     }
     // Parse privateVarMap JSON for COMPONENT/COMPONENT_LIST
     let parsedPrivateVarMap;
-    if (options.privateVarMap && (propType === "COMPONENT" || propType === "COMPONENT_LIST")) {
+    if (options.privateVarMap &&
+        (propType === "COMPONENT" || propType === "COMPONENT_LIST")) {
         try {
             parsedPrivateVarMap = JSON.parse(options.privateVarMap);
-            if (typeof parsedPrivateVarMap !== "object" || Array.isArray(parsedPrivateVarMap)) {
-                console.log(JSON.stringify({ success: false, error: "--privateVarMap must be a JSON object mapping keys to {id, typeId}." }));
+            if (typeof parsedPrivateVarMap !== "object" ||
+                Array.isArray(parsedPrivateVarMap)) {
+                console.log(JSON.stringify({
+                    success: false,
+                    error: "--privateVarMap must be a JSON object mapping keys to {id, typeId}.",
+                }));
                 process.exit(1);
             }
         }
         catch {
-            console.log(JSON.stringify({ success: false, error: `Invalid --privateVarMap JSON: ${options.privateVarMap}` }));
+            console.log(JSON.stringify({
+                success: false,
+                error: `Invalid --privateVarMap JSON: ${options.privateVarMap}`,
+            }));
+            process.exit(1);
+        }
+    }
+    const parsedDefaultValue = options.defaultValue !== undefined
+        ? parseDefaultValue(options.defaultValue, propType)
+        : undefined;
+    if ((propType === "LINK" || propType === "LIST_OF_LINK") &&
+        parsedDefaultValue !== undefined) {
+        const linkError = validateLinkDefaultValue(propType, parsedDefaultValue, options.name);
+        if (linkError) {
+            console.log(JSON.stringify({ success: false, error: linkError }));
+            process.exit(1);
+        }
+    }
+    if ((propType === "SVG" || propType === "SVG_LIST") &&
+        parsedDefaultValue !== undefined) {
+        const svgError = validateSvgDefaultValue(propType, parsedDefaultValue, options.name);
+        if (svgError) {
+            console.log(JSON.stringify({ success: false, error: svgError }));
             process.exit(1);
         }
     }
@@ -472,8 +576,8 @@ async function addProp(ref, options) {
         type: propType,
         required: options.required ?? false,
         ...(options.description ? { description: options.description } : {}),
-        ...(options.defaultValue !== undefined
-            ? { defaultValue: parseDefaultValue(options.defaultValue, propType) }
+        ...(parsedDefaultValue !== undefined
+            ? { defaultValue: parsedDefaultValue }
             : {}),
         ...(options.group ? { groupId: options.group } : {}),
         ...(options.typeId ? { typeId: options.typeId } : {}),
@@ -496,8 +600,12 @@ async function addProp(ref, options) {
             required: newProp.required,
             ...(newProp.groupId ? { groupId: newProp.groupId } : {}),
             ...(newProp.enumTypeId ? { enumTypeId: newProp.enumTypeId } : {}),
-            ...(newProp.filteredComponentIds ? { filteredComponentIds: newProp.filteredComponentIds } : {}),
-            ...(newProp.privateVarMap ? { privateVarMap: newProp.privateVarMap } : {}),
+            ...(newProp.filteredComponentIds
+                ? { filteredComponentIds: newProp.filteredComponentIds }
+                : {}),
+            ...(newProp.privateVarMap
+                ? { privateVarMap: newProp.privateVarMap }
+                : {}),
         },
     }));
 }
@@ -507,10 +615,147 @@ function parseDefaultValue(value, propType) {
             return Number(value);
         case "BOOLEAN":
             return value === "true";
+        case "LINK":
+        case "LIST_OF_LINK":
+            // The --default-value flag arrives as a string; LINK values must be stored as a
+            // typed object. Parse it here; if it is not valid JSON, return the raw string so
+            // validateLinkDefaultValue can report a precise error.
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value;
+            }
+        case "SVG_LIST":
+            // Same reasoning as LINK_LIST: SVG_LIST must be stored as an array of SVG strings.
+            // Parse it here; if it is not valid JSON, return the raw string so
+            // validateSvgDefaultValue can report a precise "must be an array" error.
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value;
+            }
         default:
             return value;
     }
 }
+const VALID_LINK_TYPES = ["PAGE", "EXTERNAL", "FILE"];
+const LINK_SHAPE_HELP = 'A link must be an object: { "linkType": "EXTERNAL", "label": "Text", "externalLink": "https://...", "subLinks": [] } ' +
+    'for external links, or { "linkType": "PAGE", "label": "Text", "pageType": "INDEX", "subLinks": [] } for store pages. ' +
+    "Do NOT pass a JSON string or a { label, href } shape.";
+// Returns the index of the first array element that fails `fn`, as an error string, or null.
+const firstError = (arr, fn) => arr.reduce((acc, item, index) => acc ?? fn(item, index), null);
+const validateSingleLink = (link, propName, path) => {
+    const where = `defaultValue for prop "${propName}"${path}`;
+    if (typeof link === "string") {
+        return `${where} is a JSON string but must be an object. ${LINK_SHAPE_HELP}`;
+    }
+    if (!link || typeof link !== "object" || Array.isArray(link)) {
+        return `${where} must be a link object. ${LINK_SHAPE_HELP}`;
+    }
+    const l = link;
+    if ("href" in l && !("linkType" in l)) {
+        return `${where} uses a legacy { href } shape without "linkType". Use "linkType" + "externalLink"/"pageType" instead. ${LINK_SHAPE_HELP}`;
+    }
+    if (typeof l.linkType !== "string" ||
+        !VALID_LINK_TYPES.includes(l.linkType)) {
+        return `${where} must have a valid "linkType" (one of ${VALID_LINK_TYPES.join(", ")}). ${LINK_SHAPE_HELP}`;
+    }
+    if (l.subLinks !== undefined && !Array.isArray(l.subLinks)) {
+        return `${where}: "subLinks" must be an array (use [] when there are none).`;
+    }
+    if (Array.isArray(l.subLinks)) {
+        return firstError(l.subLinks, (sl, i) => validateSingleLink(sl, propName, `${path}.subLinks[${i}]`));
+    }
+    return null;
+};
+// Validates a LINK / LIST_OF_LINK defaultValue. Returns an error message, or null if valid.
+// These defaults are a frequent source of bad data: agents tend to pass a JSON string or a
+// legacy { label, href } shape. Rejecting them at authoring time keeps malformed link values
+// out of published themes.
+function validateLinkDefaultValue(propType, value, propName) {
+    if (value === undefined || value === null)
+        return null;
+    if (propType === "LINK") {
+        return validateSingleLink(value, propName, "");
+    }
+    // LIST_OF_LINK
+    if (typeof value === "string") {
+        return `defaultValue for prop "${propName}" is a JSON string but must be an object { "links": [...] }. ${LINK_SHAPE_HELP}`;
+    }
+    if (!value ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        !Array.isArray(value.links)) {
+        return `defaultValue for prop "${propName}" must be an object with a "links" array: { "links": [ <link>, ... ] }. ${LINK_SHAPE_HELP}`;
+    }
+    const links = value.links;
+    return firstError(links, (link, i) => validateSingleLink(link, propName, `.links[${i}]`));
+}
+const SVG_DEFAULT_HELP = "An SVG default must be a single well-formed <svg>…</svg> string ≤ 64 KB with no embedded base64 raster images. " +
+    "Tip: the editor uses each svg's `class` attribute as its display name — set class=\"my-icon\" to name it; " +
+    "SVG_LIST items with no class show as svg-1, svg-2, ….";
+// Keep the cap and base64 pattern in sync with @ikas/editor-models validate-svg.ts (the
+// authoritative validator). Duplicated here on purpose — see validateSvgShape below.
+const SVG_MAX_SIZE_KB = 64;
+const SVG_BASE64_RASTER_RE = /data:image\/[a-z0-9.+-]+;base64/i;
+const SVG_SHAPE_RE = /^\s*(?:<\?xml[^>]*\?>\s*)?(?:<!DOCTYPE[^>]*>\s*)?<svg[\s>][\s\S]*<\/svg>\s*$/i;
+// Count TOP-LEVEL <svg> roots without a DOM: scan svg open/close tags in order and track
+// nesting depth. A root is any <svg> opened at depth 0. This matches the editor's DOM-based
+// single-root check — it rejects siblings (`<svg/><svg/>`) while allowing a nested <svg>.
+// Self-closing <svg .../> counts as a root but opens no nesting level.
+function svgRootCount(input) {
+    const tags = input.match(/<svg\b[^>]*>|<\/svg\s*>/gi) || [];
+    return tags.reduce((acc, tag) => {
+        if (tag.startsWith("</"))
+            return { depth: Math.max(0, acc.depth - 1), roots: acc.roots };
+        const roots = acc.depth === 0 ? acc.roots + 1 : acc.roots;
+        const depth = /\/>\s*$/.test(tag) ? acc.depth : acc.depth + 1;
+        return { depth, roots };
+    }, { depth: 0, roots: 0 }).roots;
+}
+// Lightweight, dependency-free SVG structure check. This standalone CLI is publishable and
+// must not depend on the private @ikas/editor-models package (nor pull a DOM/DOMPurify into a
+// CLI), so it mirrors the RULES of the editor's validateSvg (size, base64, single <svg> root)
+// for fast authoring feedback. The authoritative sanitize runs in the editor/upload path.
+// Returns a rejection reason, or null if the shape is acceptable.
+function validateSvgShape(input) {
+    if (typeof input !== "string" || input.trim() === "")
+        return "empty or not a string";
+    if (Buffer.byteLength(input, "utf8") > SVG_MAX_SIZE_KB * 1024)
+        return `exceeds ${SVG_MAX_SIZE_KB} KB`;
+    if (SVG_BASE64_RASTER_RE.test(input))
+        return "embedded base64 raster image not allowed";
+    if (!SVG_SHAPE_RE.test(input))
+        return "not a single-root <svg> document";
+    if (svgRootCount(input) !== 1)
+        return "must be exactly one <svg> root";
+    return null;
+}
+// Validates an SVG / SVG_LIST defaultValue. Returns an error message, or null if valid.
+// Authoring an SVG default is a common mistake source for agents; rejecting here (with an
+// instructive message) keeps malformed/oversized SVGs out of published components.
+function validateSvgDefaultValue(propType, value, propName) {
+    if (value === undefined || value === null)
+        return null;
+    if (propType === "SVG") {
+        const reason = validateSvgShape(value);
+        return reason
+            ? `defaultValue for prop "${propName}" is not a valid SVG: ${reason}. ${SVG_DEFAULT_HELP}`
+            : null;
+    }
+    // SVG_LIST
+    if (!Array.isArray(value)) {
+        return `defaultValue for prop "${propName}" must be an array of SVG strings: [ "<svg>…</svg>", ... ]. ${SVG_DEFAULT_HELP}`;
+    }
+    return firstError(value, (svg, i) => {
+        const reason = validateSvgShape(svg);
+        return reason
+            ? `defaultValue[${i}] for prop "${propName}" is not a valid SVG: ${reason}. ${SVG_DEFAULT_HELP}`
+            : null;
+    });
+}
 function updateProp(ref, options) {
     const { config, configPath } = loadConfig();
     const component = resolveComponent(config, ref);
@@ -544,7 +789,15 @@ function updateProp(ref, options) {
         prop.description = options.description || undefined;
     }
     if (options.defaultValue !== undefined) {
-        prop.defaultValue = parseDefaultValue(options.defaultValue, prop.type);
+        const parsed = parseDefaultValue(options.defaultValue, prop.type);
+        if (prop.type === "LINK" || prop.type === "LIST_OF_LINK") {
+            const linkError = validateLinkDefaultValue(prop.type, parsed, prop.name);
+            if (linkError) {
+                console.log(JSON.stringify({ success: false, error: linkError }));
+                process.exit(1);
+            }
+        }
+        prop.defaultValue = parsed;
     }
     if (options.group !== undefined) {
         if (options.group === "" || options.group === "none") {
@@ -586,14 +839,18 @@ function updateProp(ref, options) {
         }
     }
     if (options.filteredComponentIds !== undefined) {
-        if (options.filteredComponentIds === "" || options.filteredComponentIds === "none") {
+        if (options.filteredComponentIds === "" ||
+            options.filteredComponentIds === "none") {
             delete prop.filteredComponentIds;
         }
         else {
             try {
                 const parsed = JSON.parse(options.filteredComponentIds);
                 if (!Array.isArray(parsed)) {
-                    console.log(JSON.stringify({ success: false, error: "--filteredComponentIds must be a JSON array of strings." }));
+                    console.log(JSON.stringify({
+                        success: false,
+                        error: "--filteredComponentIds must be a JSON array of strings.",
+                    }));
                     process.exit(1);
                 }
                 assertKnownComponentIds(parsed, config);
@@ -601,7 +858,10 @@ function updateProp(ref, options) {
             }
             catch (err) {
                 if (err instanceof SyntaxError) {
-                    console.log(JSON.stringify({ success: false, error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}` }));
+                    console.log(JSON.stringify({
+                        success: false,
+                        error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}`,
+                    }));
                     process.exit(1);
                 }
                 throw err;
@@ -616,13 +876,19 @@ function updateProp(ref, options) {
             try {
                 const parsed = JSON.parse(options.privateVarMap);
                 if (typeof parsed !== "object" || Array.isArray(parsed)) {
-                    console.log(JSON.stringify({ success: false, error: "--privateVarMap must be a JSON object mapping keys to {id, typeId}." }));
+                    console.log(JSON.stringify({
+                        success: false,
+                        error: "--privateVarMap must be a JSON object mapping keys to {id, typeId}.",
+                    }));
                     process.exit(1);
                 }
                 prop.privateVarMap = parsed;
             }
             catch {
-                console.log(JSON.stringify({ success: false, error: `Invalid --privateVarMap JSON: ${options.privateVarMap}` }));
+                console.log(JSON.stringify({
+                    success: false,
+                    error: `Invalid --privateVarMap JSON: ${options.privateVarMap}`,
+                }));
                 process.exit(1);
             }
         }
@@ -642,7 +908,9 @@ function updateProp(ref, options) {
             ...(prop.groupId ? { groupId: prop.groupId } : {}),
             ...(prop.typeId ? { typeId: prop.typeId } : {}),
             ...(prop.enumTypeId ? { enumTypeId: prop.enumTypeId } : {}),
-            ...(prop.filteredComponentIds ? { filteredComponentIds: prop.filteredComponentIds } : {}),
+            ...(prop.filteredComponentIds
+                ? { filteredComponentIds: prop.filteredComponentIds }
+                : {}),
             ...(prop.privateVarMap ? { privateVarMap: prop.privateVarMap } : {}),
         },
     }));
@@ -706,7 +974,10 @@ function removeComponent(ref) {
         removedComponentId: component.id,
         removedComponentName: component.name,
         removedDirectory: path.relative(process.cwd(), componentDir),
-        remainingComponents: config.components.map((c) => ({ id: c.id, name: c.name })),
+        remainingComponents: config.components.map((c) => ({
+            id: c.id,
+            name: c.name,
+        })),
     }));
 }
 function addPropGroup(ref, options) {
@@ -813,10 +1084,10 @@ function removePropGroup(ref, options) {
         process.exit(1);
     }
     if (found.parent) {
-        found.parent.children = found.parent.children.filter(c => c.id !== options.id);
+        found.parent.children = found.parent.children.filter((c) => c.id !== options.id);
     }
     else {
-        component.propGroups = component.propGroups.filter(g => g.id !== options.id);
+        component.propGroups = component.propGroups.filter((g) => g.id !== options.id);
     }
     // Clear groupId from props referencing the deleted group
     for (const prop of component.props) {
@@ -829,7 +1100,7 @@ function removePropGroup(ref, options) {
         success: true,
         componentName: component.name,
         removedPropGroup: options.id,
-        remainingPropGroups: component.propGroups.map(g => g.id),
+        remainingPropGroups: component.propGroups.map((g) => g.id),
     }));
 }
 function movePropGroup(ref, options) {
@@ -846,7 +1117,10 @@ function movePropGroup(ref, options) {
         component.propGroups = movePropGroupInTree(component.propGroups, options.id, options.parent || null, options.index);
     }
     catch (e) {
-        console.log(JSON.stringify({ success: false, error: e.message || "Failed to move prop group" }));
+        console.log(JSON.stringify({
+            success: false,
+            error: e.message || "Failed to move prop group",
+        }));
         process.exit(1);
     }
     saveConfig(configPath, config);
@@ -902,7 +1176,9 @@ function listComponents() {
             required: p.required,
             ...(p.groupId ? { groupId: p.groupId } : {}),
         })),
-        ...(c.propGroups && c.propGroups.length > 0 ? { propGroups: c.propGroups } : {}),
+        ...(c.propGroups && c.propGroups.length > 0
+            ? { propGroups: c.propGroups }
+            : {}),
     }));
     console.log(JSON.stringify({
         success: true,
@@ -916,7 +1192,9 @@ function listComponents() {
 async function addEnum(options) {
     const { config, configPath } = loadConfig();
     // Validate name
-    if (!options.name || typeof options.name !== "string" || !options.name.trim()) {
+    if (!options.name ||
+        typeof options.name !== "string" ||
+        !options.name.trim()) {
         console.log(JSON.stringify({ success: false, error: "Enum name is required." }));
         process.exit(1);
     }
@@ -1030,7 +1308,7 @@ function updateEnum(options) {
             Object.keys(enumOptions).length === 0) {
             console.log(JSON.stringify({
                 success: false,
-                error: 'Options must be a non-empty JSON object.',
+                error: "Options must be a non-empty JSON object.",
             }));
             process.exit(1);
         }
@@ -1103,8 +1381,7 @@ function listEnums() {
 }
 // --- Command registration ---
 export function createConfigCommand() {
-    const config = new Command("config")
-        .description("Non-interactive commands for managing ikas.config.json (designed for AI agents and scripting)");
+    const config = new Command("config").description("Non-interactive commands for managing ikas.config.json (designed for AI agents and scripting)");
     config
         .command("add-component")
         .description("Add a new component to the project")
@@ -1112,7 +1389,8 @@ export function createConfigCommand() {
         .option("--type <type>", "Component type: section or component", "component")
         .option("--isHeader", "Mark this section as the store header (only for type: section)")
         .option("--isFooter", "Mark this section as the store footer (only for type: section)")
-        .option("--props <json>", "JSON array of props, e.g. '[{\"name\":\"title\",\"type\":\"TEXT\",\"required\":true}]'. Each prop needs name+type; displayName is auto-generated from name if omitted.")
+        .option("--props <json>", "JSON array of props. Required per entry: name, type. Optional: displayName (auto from name), required, description, defaultValue, groupId, typeId (TYPE props), enumTypeId (ENUM props), filteredComponentIds, privateVarMap. " +
+        'Example: \'[{"name":"title","type":"TEXT","required":true,"defaultValue":"Hello","groupId":"basic"}]\'')
         .action((options) => {
         addComponent(options.name, options);
     });
@@ -1131,7 +1409,7 @@ export function createConfigCommand() {
         .option("--typeId <typeId>", "Type ID for TYPE props (required when type is TYPE)")
         .option("--enumTypeId <enumTypeId>", "Enum type ID for ENUM props (required when type is ENUM)")
         .option("--filteredComponentIds <json>", "JSON array of component IDs to restrict selection (for COMPONENT/COMPONENT_LIST)")
-        .option("--privateVarMap <json>", 'JSON object mapping variable keys to {id, typeId} (for COMPONENT/COMPONENT_LIST)')
+        .option("--privateVarMap <json>", "JSON object mapping variable keys to {id, typeId} (for COMPONENT/COMPONENT_LIST)")
         .action((options) => {
         addProp({ id: options.componentId, name: options.component }, options);
     });
@@ -1222,7 +1500,7 @@ export function createConfigCommand() {
         .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--id <id>", "Group ID to move")
         .option("--parent <parentId>", "Target parent group ID (omit to move to root)")
-        .option("--index <index>", "Zero-based insertion index within the target parent (appends when omitted)", v => parseInt(v, 10))
+        .option("--index <index>", "Zero-based insertion index within the target parent (appends when omitted)", (v) => parseInt(v, 10))
         .action((options) => {
         movePropGroup({ id: options.componentId, name: options.component }, options);
     });
@@ -1318,7 +1596,15 @@ async function fetchLiveEditorEnumById(enumId) {
                     clearTimeout(timeout);
                     const types = message.payload?.types || [];
                     const match = types.find((t) => t.category === "enum" && t.id === enumId);
-                    finish(match ? { id: match.id, name: match.name, ...(match.enumOptions ? { enumOptions: match.enumOptions } : {}) } : null);
+                    finish(match
+                        ? {
+                            id: match.id,
+                            name: match.name,
+                            ...(match.enumOptions
+                                ? { enumOptions: match.enumOptions }
+                                : {}),
+                        }
+                        : null);
                 }
             }
             catch {