@ikas/component-cli 1.4.0-beta.5 → 1.4.0-beta.50

package/dist/commands/config.js

@@ -2,6 +2,16 @@ 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 { runEditorAction, printResultAndExit, printErrorAndExit } from "../utils/editor-action-client.js";
+async function listLocales(port) {
+    try {
+        const result = await runEditorAction("list-locales", {}, port ? { port } : {});
+        printResultAndExit(result);
+    }
+    catch (e) {
+        printErrorAndExit(e);
+    }
+}
 function loadConfig() {
     const configPath = path.resolve(process.cwd(), "ikas.config.json");
     if (!fs.existsSync(configPath)) {
@@ -17,9 +27,48 @@ 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);
@@ -105,6 +154,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.
@@ -132,6 +194,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,
@@ -172,6 +244,14 @@ 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);
+            }
+        }
         // Auto-generate displayName if omitted
         const displayName = typeof r.displayName === "string" && r.displayName
             ? r.displayName
@@ -293,6 +373,7 @@ async function addComponent(name, options) {
     const newComponent = {
         id: componentId,
         name: pascalName,
+        ...(options.displayName ? { displayName: options.displayName } : {}),
         entry: `./src/components/${pascalName}/index.tsx`,
         styles: `./src/components/${pascalName}/styles.css`,
         ...(componentType === "section" ? { type: "section" } : {}),
@@ -322,16 +403,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)) {
@@ -434,14 +508,22 @@ async function addProp(componentName, options) {
             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);
+        }
+    }
     const newProp = {
         name: options.name,
         displayName: options.displayName,
         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 } : {}),
@@ -475,20 +557,73 @@ 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;
+            }
         default:
             return value;
     }
 }
-function updateProp(componentName, options) {
+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}]`));
+}
+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({
@@ -519,7 +654,15 @@ function updateProp(componentName, 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") {
@@ -622,16 +765,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({
@@ -652,21 +788,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)) {
@@ -676,21 +821,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
@@ -741,16 +880,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,
@@ -780,16 +912,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,
@@ -825,16 +950,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,
@@ -857,16 +975,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;
@@ -883,20 +994,217 @@ function updateComponent(options) {
             delete component.isFooter;
         }
     }
+    // displayName is the code-owned default-locale display label (may contain spaces).
+    // An empty string clears it (falls back to `name`).
+    if (options.displayName !== undefined) {
+        if (options.displayName) {
+            component.displayName = options.displayName;
+        }
+        else {
+            delete component.displayName;
+        }
+    }
     saveConfig(configPath, config);
     console.log(JSON.stringify({
         success: true,
         componentName: component.name,
         type: component.type ?? "component",
+        ...(component.displayName ? { displayName: component.displayName } : {}),
         ...(component.isHeader ? { isHeader: true } : {}),
         ...(component.isFooter ? { isFooter: true } : {}),
     }));
 }
+// Upsert a per-locale translation row in `list` by locale, applying only the
+// provided fields. Studio keeps one translation per locale, so this matches by
+// locale rather than appending. A row left with no content (all label fields
+// empty) is not persisted — a new one is skipped, an existing one is pruned —
+// so we never write a meaningless `{id, locale}` row. Returns the row, or null
+// when nothing meaningful remains.
+function upsertTranslation(list, locale, fields) {
+    const existing = list.find((t) => t.locale === locale);
+    const target = existing ?? { id: generateUniqueId(), locale };
+    if (fields.displayName !== undefined)
+        target.displayName = fields.displayName || undefined;
+    if (fields.description !== undefined)
+        target.description = fields.description || undefined;
+    if (fields.name !== undefined)
+        target.name = fields.name || undefined;
+    if (!target.displayName && !target.description && !target.name) {
+        if (existing)
+            list.splice(list.indexOf(existing), 1);
+        return null;
+    }
+    if (!existing)
+        list.push(target);
+    return target;
+}
+function setPropTranslation(ref, options) {
+    const { config, configPath } = loadConfig();
+    const component = resolveComponent(config, ref);
+    const prop = component.props.find((p) => p.name === options.prop);
+    if (!prop) {
+        console.log(JSON.stringify({
+            success: false,
+            error: `Prop "${options.prop}" not found on component "${component.name}". Available: ${component.props.map((p) => p.name).join(", ")}`,
+        }));
+        process.exit(1);
+    }
+    if (options.displayName === undefined && options.description === undefined) {
+        console.log(JSON.stringify({
+            success: false,
+            error: "Nothing to set: provide --displayName and/or --description.",
+        }));
+        process.exit(1);
+    }
+    if (!prop.translations)
+        prop.translations = [];
+    const row = upsertTranslation(prop.translations, options.locale, {
+        displayName: options.displayName,
+        description: options.description,
+    });
+    if (prop.translations.length === 0)
+        prop.translations = undefined;
+    saveConfig(configPath, config);
+    console.log(JSON.stringify({
+        success: true,
+        componentName: component.name,
+        prop: prop.name,
+        translation: row,
+    }));
+}
+function setGroupTranslation(ref, options) {
+    const { config, configPath } = loadConfig();
+    const component = resolveComponent(config, ref);
+    if (!component.propGroups || component.propGroups.length === 0) {
+        console.log(JSON.stringify({ success: false, error: `No prop groups on component "${component.name}".` }));
+        process.exit(1);
+    }
+    const found = findPropGroup(component.propGroups, options.group);
+    if (!found) {
+        console.log(JSON.stringify({
+            success: false,
+            error: `Prop group "${options.group}" not found on component "${component.name}". Available: ${Array.from(collectPropGroupIds(component.propGroups)).join(", ")}`,
+        }));
+        process.exit(1);
+    }
+    if (options.name === undefined && options.description === undefined) {
+        console.log(JSON.stringify({
+            success: false,
+            error: "Nothing to set: provide --name and/or --description.",
+        }));
+        process.exit(1);
+    }
+    if (!found.group.translations)
+        found.group.translations = [];
+    const row = upsertTranslation(found.group.translations, options.locale, {
+        name: options.name,
+        description: options.description,
+    });
+    if (found.group.translations.length === 0)
+        found.group.translations = undefined;
+    saveConfig(configPath, config);
+    console.log(JSON.stringify({
+        success: true,
+        componentName: component.name,
+        group: found.group.id,
+        translation: row,
+    }));
+}
+function removePropTranslation(ref, options) {
+    const { config, configPath } = loadConfig();
+    const component = resolveComponent(config, ref);
+    const prop = component.props.find((p) => p.name === options.prop);
+    if (!prop) {
+        console.log(JSON.stringify({
+            success: false,
+            error: `Prop "${options.prop}" not found on component "${component.name}". Available: ${component.props.map((p) => p.name).join(", ")}`,
+        }));
+        process.exit(1);
+    }
+    const before = prop.translations?.length ?? 0;
+    if (prop.translations) {
+        prop.translations = prop.translations.filter((t) => t.locale !== options.locale);
+        if (prop.translations.length === 0)
+            prop.translations = undefined;
+    }
+    saveConfig(configPath, config);
+    console.log(JSON.stringify({
+        success: true,
+        componentName: component.name,
+        prop: prop.name,
+        removed: before - (prop.translations?.length ?? 0),
+    }));
+}
+function removeGroupTranslation(ref, options) {
+    const { config, configPath } = loadConfig();
+    const component = resolveComponent(config, ref);
+    if (!component.propGroups || component.propGroups.length === 0) {
+        console.log(JSON.stringify({ success: false, error: `No prop groups on component "${component.name}".` }));
+        process.exit(1);
+    }
+    const found = findPropGroup(component.propGroups, options.group);
+    if (!found) {
+        console.log(JSON.stringify({
+            success: false,
+            error: `Prop group "${options.group}" not found on component "${component.name}". Available: ${Array.from(collectPropGroupIds(component.propGroups)).join(", ")}`,
+        }));
+        process.exit(1);
+    }
+    const before = found.group.translations?.length ?? 0;
+    if (found.group.translations) {
+        found.group.translations = found.group.translations.filter((t) => t.locale !== options.locale);
+        if (found.group.translations.length === 0)
+            found.group.translations = undefined;
+    }
+    saveConfig(configPath, config);
+    console.log(JSON.stringify({
+        success: true,
+        componentName: component.name,
+        group: found.group.id,
+        removed: before - (found.group.translations?.length ?? 0),
+    }));
+}
+function setComponentTranslation(ref, options) {
+    const { config, configPath } = loadConfig();
+    const component = resolveComponent(config, ref);
+    if (options.displayName === undefined) {
+        console.log(JSON.stringify({ success: false, error: "Nothing to set: provide --displayName." }));
+        process.exit(1);
+    }
+    if (!component.translations)
+        component.translations = [];
+    const row = upsertTranslation(component.translations, options.locale, { displayName: options.displayName });
+    if (component.translations.length === 0)
+        component.translations = undefined;
+    saveConfig(configPath, config);
+    console.log(JSON.stringify({
+        success: true,
+        componentName: component.name,
+        translation: row,
+    }));
+}
+function removeComponentTranslation(ref, options) {
+    const { config, configPath } = loadConfig();
+    const component = resolveComponent(config, ref);
+    const before = component.translations?.length ?? 0;
+    if (component.translations) {
+        component.translations = component.translations.filter((t) => t.locale !== options.locale);
+        if (component.translations.length === 0)
+            component.translations = undefined;
+    }
+    saveConfig(configPath, config);
+    console.log(JSON.stringify({
+        success: true,
+        componentName: component.name,
+        removed: before - (component.translations?.length ?? 0),
+    }));
+}
 function listComponents() {
     const { config } = loadConfig();
     const components = config.components.map((c) => ({
         id: c.id,
         name: c.name,
+        ...(c.displayName ? { displayName: c.displayName } : {}),
         type: c.type ?? "component",
         ...(c.isHeader ? { isHeader: true } : {}),
         ...(c.isFooter ? { isFooter: true } : {}),
@@ -1116,17 +1424,20 @@ export function createConfigCommand() {
         .command("add-component")
         .description("Add a new component to the project")
         .requiredOption("--name <name>", "Component name (PascalCase or kebab-case)")
+        .option("--displayName <displayName>", "Human-facing display label shown in the editor (may contain spaces; defaults to name)")
         .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(", ")}`)
@@ -1139,12 +1450,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")
@@ -1157,76 +1469,157 @@ 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 (displayName, 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("--displayName <displayName>", "Human-facing display label shown in the editor (may contain spaces; empty string clears it)")
         .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("set-prop-translation")
+        .description("Add or update a per-locale translation for a prop's label/description. " +
+        "Seeded into the editor on first import of a new component or a newly added prop; " +
+        "studio-owned translations for already-imported props are not overwritten.")
+        .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 translate")
+        .requiredOption("--locale <locale>", "Target locale (e.g. de, fr, en)")
+        .option("--displayName <text>", "Translated display name")
+        .option("--description <text>", "Translated description")
+        .action((options) => {
+        setPropTranslation({ id: options.componentId, name: options.component }, options);
+    });
+    config
+        .command("set-group-translation")
+        .description("Add or update a per-locale translation for a prop group's name/description. " +
+        "Seeded into the editor only for groups studio has not seen yet (studio wins otherwise).")
+        .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("--group <groupId>", "Prop group id (local, as in ikas.config.json)")
+        .requiredOption("--locale <locale>", "Target locale (e.g. de, fr, en)")
+        .option("--name <text>", "Translated group name")
+        .option("--description <text>", "Translated description")
+        .action((options) => {
+        setGroupTranslation({ id: options.componentId, name: options.component }, options);
+    });
+    config
+        .command("remove-prop-translation")
+        .description("Remove a prop's translation for a given locale")
+        .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")
+        .requiredOption("--locale <locale>", "Locale to remove")
+        .action((options) => {
+        removePropTranslation({ id: options.componentId, name: options.component }, options);
+    });
+    config
+        .command("remove-group-translation")
+        .description("Remove a prop group's translation for a given locale")
+        .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("--group <groupId>", "Prop group id (local, as in ikas.config.json)")
+        .requiredOption("--locale <locale>", "Locale to remove")
+        .action((options) => {
+        removeGroupTranslation({ id: options.componentId, name: options.component }, options);
+    });
+    config
+        .command("set-component-translation")
+        .description("Add or update a per-locale translation for a section/component's own display label. " +
+        "Seeded into the editor only for components studio has not seen yet (studio wins otherwise).")
+        .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("--locale <locale>", "Target locale (e.g. de, fr, en)")
+        .option("--displayName <text>", "Translated component display label")
+        .action((options) => {
+        setComponentTranslation({ id: options.componentId, name: options.component }, options);
+    });
+    config
+        .command("remove-component-translation")
+        .description("Remove a section/component name translation for a given locale")
+        .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("--locale <locale>", "Locale to remove")
+        .action((options) => {
+        removeComponentTranslation({ 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();
     });
@@ -1237,6 +1630,13 @@ export function createConfigCommand() {
         .action(async (options) => {
         await listTypes(options.componentType);
     });
+    config
+        .command("list-locales")
+        .description("List the editor's configured locales — the ONLY valid --locale values for set-prop-translation / set-group-translation. Run this before adding translations; never invent a locale. (Requires a running dev server with the editor connected.)")
+        .option("--port <port>", "Dev server WebSocket port", "5201")
+        .action(async (options) => {
+        await listLocales(options.port ? parseInt(options.port, 10) : undefined);
+    });
     config
         .command("add-enum")
         .description("Create a custom enum type (offline, no editor needed)")