@ikas/component-cli 1.4.0-beta.2 → 1.4.0-beta.21

package/dist/commands/add-to-page.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function createAddToPageCommand(): Command;
+//# sourceMappingURL=add-to-page.d.ts.map

package/dist/commands/add-to-page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-to-page.d.ts","sourceRoot":"","sources":["../../src/commands/add-to-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6CpC,wBAAgB,sBAAsB,IAAI,OAAO,CAYhD"}

package/dist/commands/add-to-page.js

@@ -0,0 +1,41 @@
+import { Command } from "commander";
+import { printErrorAndExit, printResultAndExit, runEditorAction, } from "../utils/editor-action-client.js";
+async function runAddToPage(options) {
+    if (!options.componentId || typeof options.componentId !== "string") {
+        printErrorAndExit(new Error("--component-id is required"));
+    }
+    if (!options.pageId || typeof options.pageId !== "string") {
+        printErrorAndExit(new Error("--page-id is required (use `ikas-component list-pages` to discover ids)"));
+    }
+    let index;
+    if (options.index !== undefined) {
+        index = parseInt(options.index, 10);
+        if (Number.isNaN(index) || index < 0) {
+            printErrorAndExit(new Error("--index must be a non-negative integer"));
+        }
+    }
+    const port = options.port ? parseInt(options.port, 10) : undefined;
+    try {
+        const result = await runEditorAction("add-section-to-page", {
+            componentId: options.componentId,
+            pageId: options.pageId,
+            ...(typeof index === "number" ? { index } : {}),
+        }, port ? { port } : {});
+        printResultAndExit(result);
+    }
+    catch (e) {
+        printErrorAndExit(e);
+    }
+}
+export function createAddToPageCommand() {
+    const cmd = new Command("add-to-page");
+    cmd
+        .description("Place a section-type code component on a page. Requires the component to be imported first (see `ikas-component import`).")
+        .requiredOption("--component-id <id>", "Code component id (from `ikas-component list-imported`)")
+        .requiredOption("--page-id <id>", "Page id (from `ikas-component list-pages`)")
+        .option("--index <n>", "Zero-based insertion index in the page; appends when omitted")
+        .option("--port <port>", "Dev server WebSocket port", "5201")
+        .action(runAddToPage);
+    return cmd;
+}
+//# sourceMappingURL=add-to-page.js.map

package/dist/commands/add-to-page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"add-to-page.js","sourceRoot":"","sources":["../../src/commands/add-to-page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,GAChB,MAAM,kCAAkC,CAAC;AAS1C,KAAK,UAAU,YAAY,CAAC,OAAyB;IACnD,IAAI,CAAC,OAAO,CAAC,WAAW,IAAI,OAAO,OAAO,CAAC,WAAW,KAAK,QAAQ,EAAE,CAAC;QACpE,iBAAiB,CAAC,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC,CAAC;IAC7D,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1D,iBAAiB,CAAC,IAAI,KAAK,CAAC,yEAAyE,CAAC,CAAC,CAAC;IAC1G,CAAC;IACD,IAAI,KAAyB,CAAC;IAC9B,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QACpC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACrC,iBAAiB,CAAC,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,eAAe,CAClC,qBAAqB,EACrB;YACE,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,GAAG,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,EACD,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CACrB,CAAC;QACF,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,iBAAiB,CAAC,CAAC,CAAC,CAAC;IACvB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,aAAa,CAAC,CAAC;IACvC,GAAG;SACA,WAAW,CACV,2HAA2H,CAC5H;SACA,cAAc,CAAC,qBAAqB,EAAE,yDAAyD,CAAC;SAChG,cAAc,CAAC,gBAAgB,EAAE,4CAA4C,CAAC;SAC9E,MAAM,CAAC,aAAa,EAAE,8DAA8D,CAAC;SACrF,MAAM,CAAC,eAAe,EAAE,2BAA2B,EAAE,MAAM,CAAC;SAC5D,MAAM,CAAC,YAAY,CAAC,CAAC;IACxB,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/commands/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA28CpC,wBAAgB,mBAAmB,IAAI,OAAO,CAuL7C"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/commands/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAw/CpC,wBAAgB,mBAAmB,IAAI,OAAO,CA2M7C"}

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, } from "../utils/component-helpers.js";
+import { PROP_TYPES, toPascalCase, generateTypesFile, generateGlobalTypesFile, collectUsedEnumIds, generateComponentFile, generateStylesFile, generateProjectId, 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)) {
@@ -17,13 +17,79 @@ function loadConfig() {
 function saveConfig(configPath, config) {
     fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
 }
-function findComponent(config, name) {
-    const pascalName = toPascalCase(name);
-    return config.components.find((c) => c.name === pascalName);
+/**
+ * Resolve a component by canonical id (preferred) or exact PascalCase name.
+ * No silent normalization: pass --id from `config list-components`, or pass --name
+ * exactly as stored in ikas.config.json. Exits with a structured JSON error
+ * (listing valid {id, name} pairs) if zero/both/missing.
+ */
+function resolveComponent(config, ref) {
+    const id = ref.id?.trim() || undefined;
+    const name = ref.name?.trim() || undefined;
+    if (!id && !name) {
+        console.log(JSON.stringify({
+            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 })),
+        }));
+        process.exit(1);
+    }
+    if (id && name) {
+        console.log(JSON.stringify({
+            success: false,
+            error: "Specify only one of --id or --name, not both.",
+        }));
+        process.exit(1);
+    }
+    const found = id
+        ? config.components.find((c) => c.id === id)
+        : config.components.find((c) => c.name === name);
+    if (!found) {
+        console.log(JSON.stringify({
+            success: false,
+            error: id
+                ? `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 })),
+            hint: "Use --id (preferred) or exact PascalCase --name. " +
+                "Run `ikas-component config list-components` to see canonical ids.",
+        }));
+        process.exit(1);
+    }
+    return found;
 }
 function getComponentNames(config) {
     return config.components.map((c) => c.name);
 }
+/**
+ * Emit a structured JSON error for unknown filteredComponentIds entries and exit non-zero.
+ * Lists valid `{ id, name }` pairs so the LLM/caller can recover.
+ */
+function emitFilteredComponentIdsError(unknown, components) {
+    console.log(JSON.stringify({
+        success: false,
+        error: `Unknown filteredComponentIds: ${unknown.join(", ")}. ` +
+            `Component ids are opaque and cannot be derived from names — they must come from the ` +
+            `componentId returned by 'config add-component' or from 'config list'.`,
+        validComponents: components.map((c) => ({ id: c.id, name: c.name })),
+    }));
+    process.exit(1);
+}
+/**
+ * Validate `input` ids against `config.components` and return the same array on success.
+ * Exits with a JSON error if any id is unknown. Use at every write site that accepts
+ * filteredComponentIds from user/LLM input.
+ */
+function assertKnownComponentIds(input, config) {
+    const components = config?.components ?? [];
+    const { unknown } = validateFilteredComponentIds(input, components);
+    if (unknown.length > 0) {
+        emitFilteredComponentIdsError(unknown, components);
+    }
+    return input;
+}
 function regenerateTypes(component, componentType, config) {
     const componentDir = path.resolve(process.cwd(), path.dirname(component.entry));
     const typesPath = path.join(componentDir, "types.ts");
@@ -78,6 +144,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.
@@ -105,6 +184,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,
@@ -201,7 +290,7 @@ async function parsePropsFlag(propsJson, config, configPath) {
                 ? { enumTypeId: r.enumTypeId }
                 : {}),
             ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") && r.filteredComponentIds && Array.isArray(r.filteredComponentIds)
-                ? { filteredComponentIds: r.filteredComponentIds }
+                ? { filteredComponentIds: assertKnownComponentIds(r.filteredComponentIds, config) }
                 : {}),
             ...((propType === "COMPONENT" || propType === "COMPONENT_LIST") && r.privateVarMap && typeof r.privateVarMap === "object"
                 ? { privateVarMap: r.privateVarMap }
@@ -236,14 +325,15 @@ async function addComponent(name, options) {
     if (!config.projectId) {
         config.projectId = generateProjectId();
     }
+    // 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
+        ? await parsePropsFlag(options.props, config, configPath)
+        : [];
     const componentId = generateComponentId(config.projectId);
     const componentDir = path.resolve(process.cwd(), `src/components/${pascalName}`);
     // Create directory
     fs.mkdirSync(componentDir, { recursive: true });
-    // Parse --props if provided, otherwise empty
-    const props = options.props
-        ? await parsePropsFlag(options.props, config, configPath)
-        : [];
     // Auto-create prop groups from groupId references in props
     const referencedGroupIds = new Set();
     for (const prop of props) {
@@ -294,16 +384,9 @@ async function addComponent(name, options) {
         ],
     }));
 }
-async function addProp(componentName, options) {
+async function addProp(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     // Validate prop type
     const propType = options.type.toUpperCase();
     if (!PROP_TYPES.includes(propType)) {
@@ -389,6 +472,7 @@ async function addProp(componentName, options) {
             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;
@@ -450,16 +534,9 @@ function parseDefaultValue(value, propType) {
             return value;
     }
 }
-function updateProp(componentName, options) {
+function updateProp(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     const propIndex = component.props.findIndex((p) => p.name === options.prop);
     if (propIndex === -1) {
         console.log(JSON.stringify({
@@ -542,11 +619,15 @@ function updateProp(componentName, options) {
                     console.log(JSON.stringify({ success: false, error: "--filteredComponentIds must be a JSON array of strings." }));
                     process.exit(1);
                 }
+                assertKnownComponentIds(parsed, config);
                 prop.filteredComponentIds = parsed;
             }
-            catch {
-                console.log(JSON.stringify({ success: false, error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}` }));
-                process.exit(1);
+            catch (err) {
+                if (err instanceof SyntaxError) {
+                    console.log(JSON.stringify({ success: false, error: `Invalid --filteredComponentIds JSON: ${options.filteredComponentIds}` }));
+                    process.exit(1);
+                }
+                throw err;
             }
         }
     }
@@ -589,16 +670,9 @@ function updateProp(componentName, options) {
         },
     }));
 }
-function removeProp(componentName, options) {
+function removeProp(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     const propIndex = component.props.findIndex((p) => p.name === options.prop);
     if (propIndex === -1) {
         console.log(JSON.stringify({
@@ -619,21 +693,30 @@ function removeProp(componentName, options) {
         remainingProps: component.props.map((p) => p.name),
     }));
 }
-function removeComponent(options) {
-    const { config, configPath } = loadConfig();
-    const pascalName = toPascalCase(options.name);
-    const componentIndex = config.components.findIndex((c) => c.name === pascalName);
-    if (componentIndex === -1) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${options.name}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
+/**
+ * Strip a deleted component's ID from every other component's COMPONENT/COMPONENT_LIST
+ * `filteredComponentIds` allowlist. Empty arrays are deleted to keep the field optional
+ * (mirrors the editor-side convention).
+ */
+function pruneFilteredComponentIdRefs(config, removedId) {
+    for (const component of config.components) {
+        for (const prop of component.props || []) {
+            if (!prop.filteredComponentIds)
+                continue;
+            prop.filteredComponentIds = prop.filteredComponentIds.filter((id) => id !== removedId);
+            if (prop.filteredComponentIds.length === 0)
+                delete prop.filteredComponentIds;
+        }
     }
-    const component = config.components[componentIndex];
+}
+function removeComponent(ref) {
+    const { config, configPath } = loadConfig();
+    const component = resolveComponent(config, ref);
+    const componentIndex = config.components.indexOf(component);
     const componentDir = path.resolve(process.cwd(), path.dirname(component.entry));
-    // Remove component from config
+    // Remove component from config and strip orphaned references from remaining components
     config.components.splice(componentIndex, 1);
+    pruneFilteredComponentIdRefs(config, component.id);
     saveConfig(configPath, config);
     // Remove component directory
     if (fs.existsSync(componentDir)) {
@@ -643,21 +726,15 @@ function removeComponent(options) {
     updateBarrelExport(process.cwd(), getComponentNames(config));
     console.log(JSON.stringify({
         success: true,
-        removedComponent: pascalName,
+        removedComponentId: component.id,
+        removedComponentName: component.name,
         removedDirectory: path.relative(process.cwd(), componentDir),
-        remainingComponents: getComponentNames(config),
+        remainingComponents: config.components.map((c) => ({ id: c.id, name: c.name })),
     }));
 }
-function addPropGroup(componentName, options) {
+function addPropGroup(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (!component.propGroups)
         component.propGroups = [];
     // Check uniqueness
@@ -708,16 +785,9 @@ function addPropGroup(componentName, options) {
         },
     }));
 }
-function updatePropGroup(componentName, options) {
+function updatePropGroup(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (!component.propGroups || component.propGroups.length === 0) {
         console.log(JSON.stringify({
             success: false,
@@ -747,16 +817,9 @@ function updatePropGroup(componentName, options) {
         },
     }));
 }
-function removePropGroup(componentName, options) {
+function removePropGroup(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (!component.propGroups || component.propGroups.length === 0) {
         console.log(JSON.stringify({
             success: false,
@@ -792,16 +855,9 @@ function removePropGroup(componentName, options) {
         remainingPropGroups: component.propGroups.map(g => g.id),
     }));
 }
-function movePropGroup(componentName, options) {
+function movePropGroup(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, componentName);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${componentName}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (!component.propGroups || component.propGroups.length === 0) {
         console.log(JSON.stringify({
             success: false,
@@ -824,16 +880,9 @@ function movePropGroup(componentName, options) {
         parentGroupId: options.parent || null,
     }));
 }
-function updateComponent(options) {
+function updateComponent(ref, options) {
     const { config, configPath } = loadConfig();
-    const component = findComponent(config, options.name);
-    if (!component) {
-        console.log(JSON.stringify({
-            success: false,
-            error: `Component "${options.name}" not found. Available: ${getComponentNames(config).join(", ")}`,
-        }));
-        process.exit(1);
-    }
+    const component = resolveComponent(config, ref);
     if (options.isHeader !== undefined) {
         if (options.isHeader) {
             component.isHeader = true;
@@ -1086,14 +1135,16 @@ 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);
     });
     config
         .command("add-prop")
         .description("Add a prop to a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--name <name>", "Prop name (camelCase)")
         .requiredOption("--displayName <displayName>", "Display name in editor")
         .requiredOption("--type <type>", `Prop type: ${PROP_TYPES.join(", ")}`)
@@ -1106,12 +1157,13 @@ export function createConfigCommand() {
         .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)')
         .action((options) => {
-        addProp(options.component, options);
+        addProp({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("update-prop")
         .description("Update a prop on a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--prop <propName>", "Prop name to update")
         .option("--displayName <displayName>", "New display name")
         .option("--type <type>", "New prop type")
@@ -1124,76 +1176,89 @@ export function createConfigCommand() {
         .option("--filteredComponentIds <json>", "JSON array of component IDs (use 'none' to clear)")
         .option("--privateVarMap <json>", "JSON object mapping variable keys to {id, typeId} (use 'none' to clear)")
         .action((options) => {
-        updateProp(options.component, options);
+        updateProp({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("remove-prop")
         .description("Remove a prop from a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--prop <propName>", "Prop name to remove")
         .action((options) => {
-        removeProp(options.component, options);
+        removeProp({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("update-component")
-        .description("Update a component's metadata (isHeader, isFooter)")
-        .requiredOption("--name <name>", "Component name")
+        .description("Update a component's metadata (isHeader, isFooter). Identify by --id (preferred) or exact --name.")
+        .option("--id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--name <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .option("--isHeader", "Mark as store header")
         .option("--no-isHeader", "Unmark as store header")
         .option("--isFooter", "Mark as store footer")
         .option("--no-isFooter", "Unmark as store footer")
         .action((options) => {
-        updateComponent(options);
+        updateComponent({ id: options.id, name: options.name }, options);
     });
     config
         .command("remove-component")
-        .description("Remove a component from the project (deletes files)")
-        .requiredOption("--name <name>", "Component name to remove")
+        .description("Remove a component from the project (deletes files). Identify by --id (preferred) or exact --name.")
+        .option("--id <id>", "Component id (preferred; from `config list-components`)")
+        .option("--name <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .action((options) => {
-        removeComponent(options);
+        removeComponent({ id: options.id, name: options.name });
     });
     config
         .command("add-prop-group")
         .description("Add a prop group to a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <componentId>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--id <id>", "Group ID (unique within component, kebab-case)")
         .requiredOption("--name <name>", "Display name in editor")
         .option("--description <description>", "Group description")
         .option("--parent <parentId>", "Parent group ID (for nesting, max 1 level)")
         .action((options) => {
-        addPropGroup(options.component, options);
+        addPropGroup({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("update-prop-group")
         .description("Update a prop group on a component")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <componentId>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--id <id>", "Group ID to update")
         .option("--name <name>", "New display name")
         .option("--description <description>", "New description")
         .action((options) => {
-        updatePropGroup(options.component, options);
+        updatePropGroup({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("remove-prop-group")
         .description("Remove a prop group from a component (props become ungrouped)")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <componentId>", "Component id (preferred; from `config list-components`)")
+        .option("--component <name>", "Component name — exact match (PascalCase, as stored in ikas.config.json)")
         .requiredOption("--id <id>", "Group ID to remove")
         .action((options) => {
-        removePropGroup(options.component, options);
+        removePropGroup({ id: options.componentId, name: options.component }, options);
     });
     config
         .command("move-prop-group")
         .description("Move a prop group to a different parent or position (for drag-and-drop reordering)")
-        .requiredOption("--component <name>", "Component name")
+        .option("--component-id <componentId>", "Component id (preferred; from `config list-components`)")
+        .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))
         .action((options) => {
-        movePropGroup(options.component, options);
+        movePropGroup({ id: options.componentId, name: options.component }, options);
+    });
+    config
+        .command("list-components")
+        .description("List all components and their props (with canonical ids for use with --id flags)")
+        .action(() => {
+        listComponents();
     });
     config
         .command("list")
-        .description("List all components and their props")
+        .description("Alias for `list-components` (kept for backwards compatibility)")
         .action(() => {
         listComponents();
     });