@midscene/shared 1.7.5-beta-20260420032657.0 → 1.7.5-beta-20260420052829.0

package/dist/es/cli/cli-runner.mjs

@@ -2,6 +2,8 @@ import { existsSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import dotenv from "dotenv";
+import { z } from "zod";
+import { getKeyAliases, isRecord } from "../key-alias-utils.mjs";
 import { getDebug } from "../logger.mjs";
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
@@ -26,19 +28,48 @@ function parseValue(raw) {
     if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
     return raw;
 }
-function parseCliArgs(args) {
-    const result = {};
+function walkCliArgs(args, setArgValue) {
     for(let i = 0; i < args.length; i++){
         const arg = args[i];
         if (!arg.startsWith('--')) continue;
         const body = arg.slice(2);
         const eqIdx = body.indexOf('=');
-        if (eqIdx >= 0) result[body.slice(0, eqIdx)] = parseValue(body.slice(eqIdx + 1));
+        if (eqIdx >= 0) setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
         else if (args[i + 1] && !args[i + 1].startsWith('--')) {
             i++;
-            result[body] = parseValue(args[i]);
-        } else result[body] = true;
+            setArgValue(body, parseValue(args[i]));
+        } else setArgValue(body, true);
     }
+}
+function parseRawCliArgs(args) {
+    const result = {};
+    walkCliArgs(args, (key, value)=>{
+        result[key] = value;
+    });
+    return result;
+}
+function parseCliArgs(args) {
+    const result = {};
+    walkCliArgs(args, (key, value)=>{
+        if (!key.includes('.')) {
+            result[key] = value;
+            return;
+        }
+        const segments = key.split('.');
+        let current = result;
+        for (const segment of segments.slice(0, -1)){
+            const aliases = getKeyAliases(segment);
+            const existing = aliases.map((alias)=>current[alias]);
+            const nestedRecord = existing.find(isRecord);
+            const conflictingScalar = existing.find((entry)=>void 0 !== entry && !isRecord(entry));
+            if (void 0 !== conflictingScalar) throw new CLIError(`Conflicting CLI args: "${segment}" is used both as a value and as a namespace`);
+            const target = nestedRecord ?? {};
+            for (const alias of aliases)current[alias] = target;
+            current = target;
+        }
+        const leafSegment = segments[segments.length - 1];
+        for (const alias of getKeyAliases(leafSegment))current[alias] = value;
+    });
     return result;
 }
 function outputContentItem(item, isError) {
@@ -66,16 +97,86 @@ function removePrefix(name, prefix) {
     if (prefix && name.startsWith(prefix)) return name.slice(prefix.length);
     return name;
 }
+function formatCliOptionName(name) {
+    return `--${name}`;
+}
+function getCliOptionDisplay(key, cliOption) {
+    const label = formatCliOptionName(cliOption?.preferredName ?? key);
+    const aliases = [
+        ...new Set(cliOption?.aliases ?? [])
+    ].map((alias)=>formatCliOptionName(alias)).filter((alias)=>alias !== label);
+    return {
+        label,
+        aliases
+    };
+}
+function getAcceptedCliOptionNames(key, cliOption) {
+    return [
+        ...new Set(cliOption ? [
+            cliOption.preferredName ?? key,
+            ...cliOption.aliases ?? []
+        ] : [
+            key,
+            ...getKeyAliases(key)
+        ])
+    ];
+}
+function toOptionalCliSchemaField(field) {
+    if ('object' == typeof field && null !== field && 'function' == typeof field.optional) return field.optional();
+    const description = 'object' == typeof field && null !== field && "description" in field && 'string' == typeof field.description ? field.description : void 0;
+    return description ? z.any().describe(description) : z.any();
+}
+function buildCliArgSchema(def) {
+    return Object.fromEntries(Object.entries(def.schema).flatMap(([key, zodType])=>getAcceptedCliOptionNames(key, def.cli?.options?.[key]).map((cliKey)=>[
+                cliKey,
+                toOptionalCliSchemaField(zodType)
+            ])));
+}
+function buildDisallowedCliSpellings(def) {
+    const disallowedSpellings = new Map();
+    for (const [key] of Object.entries(def.schema)){
+        const cliOption = def.cli?.options?.[key];
+        const preferredLabel = formatCliOptionName(cliOption?.preferredName ?? key);
+        const acceptedNames = new Set(getAcceptedCliOptionNames(key, cliOption));
+        const knownSpellings = new Set([
+            key,
+            ...getKeyAliases(key),
+            ...cliOption?.preferredName ? getKeyAliases(cliOption.preferredName) : [],
+            ...cliOption?.aliases ?? []
+        ]);
+        for (const spelling of knownSpellings)if (!acceptedNames.has(spelling)) disallowedSpellings.set(spelling, preferredLabel);
+    }
+    return disallowedSpellings;
+}
+function formatCliValidationError(scriptName, commandName, def, rawArgs) {
+    if (0 === Object.keys(def.schema).length) return;
+    const cliSchema = z.object(buildCliArgSchema(def)).strict();
+    const parsed = cliSchema.safeParse(rawArgs);
+    if (parsed.success) return;
+    const disallowedSpellings = buildDisallowedCliSpellings(def);
+    const unknownKeys = parsed.error.issues.flatMap((issue)=>'unrecognized_keys' === issue.code ? issue.keys : []);
+    if (unknownKeys.length > 0) return unknownKeys.map((key)=>{
+        const preferredLabel = disallowedSpellings.get(key);
+        if (preferredLabel) return `Unsupported option "--${key}" for ${scriptName} ${commandName}. Use "${preferredLabel}" instead.`;
+        return `Unknown option "--${key}" for ${scriptName} ${commandName}.`;
+    }).join('\n');
+    const [issue] = parsed.error.issues;
+    const optionName = 'string' == typeof issue?.path[0] ? `--${issue.path[0]}` : 'CLI arguments';
+    return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
+}
 function printCommandHelp(scriptName, cmd) {
     const { def } = cmd;
     console.log(`\nUsage: ${scriptName} ${cmd.name} [options]\n`);
     console.log(def.description);
     const schemaEntries = Object.entries(def.schema);
     if (schemaEntries.length > 0) {
+        const optionWidth = Math.max(22, ...schemaEntries.map(([key])=>getCliOptionDisplay(key, def.cli?.options?.[key]).label.length));
         console.log('\nOptions:');
         for (const [key, zodType] of schemaEntries){
+            const { label, aliases } = getCliOptionDisplay(key, def.cli?.options?.[key]);
             const desc = zodType.description ?? '';
-            console.log(`  --${key.padEnd(20)} ${desc}`);
+            const aliasText = aliases.length > 0 ? ` (aliases: ${aliases.join(', ')})` : '';
+            console.log(`  ${label.padEnd(optionWidth)} ${desc}${aliasText}`);
         }
     }
 }
@@ -136,13 +237,16 @@ async function runToolsCLI(tools, scriptName, options) {
         printHelp(scriptName, commands, cliVersion);
         throw new CLIError(`Unknown command: ${commandName}`);
     }
-    const parsedArgs = parseCliArgs(restArgs);
-    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
-    if (true === parsedArgs.help) {
+    const rawCliArgs = parseRawCliArgs(restArgs);
+    if (true === rawCliArgs.help) {
         debug('showing command help for: %s', match.name);
         printCommandHelp(scriptName, match);
         return;
     }
+    const cliValidationError = formatCliValidationError(scriptName, match.name, match.def, rawCliArgs);
+    if (cliValidationError) throw new CLIError(cliValidationError);
+    const parsedArgs = parseCliArgs(restArgs);
+    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
     const result = await match.def.handler(parsedArgs);
     debug('command %s completed, isError: %s', match.name, result.isError ?? false);
     outputResult(result);

package/dist/es/key-alias-utils.mjs

@@ -0,0 +1,19 @@
+function kebabToCamel(str) {
+    return str.replace(/-([a-z])/g, (_, letter)=>letter.toUpperCase());
+}
+function camelToKebab(str) {
+    return str.replace(/[A-Z]/g, (letter)=>`-${letter.toLowerCase()}`).replace(/^-/, '');
+}
+function getKeyAliases(key) {
+    return [
+        ...new Set([
+            key,
+            kebabToCamel(key),
+            camelToKebab(key)
+        ])
+    ];
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value);
+}
+export { camelToKebab, getKeyAliases, isRecord, kebabToCamel };

package/dist/es/mcp/base-tools.mjs

@@ -1,5 +1,7 @@
 import { parseBase64 } from "@midscene/shared/img";
 import { getDebug } from "@midscene/shared/logger";
+import { camelToKebab, getKeyAliases } from "../key-alias-utils.mjs";
+import { createNamespacedInitArgSchema, extractNamespacedArgs, sanitizeNamespacedArgs } from "./init-arg-utils.mjs";
 import { generateCommonTools, generateToolsFromActionSpace } from "./tool-generator.mjs";
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
@@ -13,6 +15,47 @@ function _define_property(obj, key, value) {
 }
 const debug = getDebug('mcp:base-tools');
 class BaseMidsceneTools {
+    getInitArgKeys() {
+        return this.initArgSpec ? Object.keys(this.initArgSpec.shape) : [];
+    }
+    extractAgentInitParam(args) {
+        if (!this.initArgSpec) return;
+        const extracted = extractNamespacedArgs(args, this.initArgSpec.namespace, this.getInitArgKeys());
+        if (this.initArgSpec.adapt) return this.initArgSpec.adapt(extracted);
+        return extracted;
+    }
+    sanitizeToolArgs(args) {
+        if (!this.initArgSpec) return args;
+        return sanitizeNamespacedArgs(args, this.initArgSpec.namespace, this.getInitArgKeys());
+    }
+    getAgentInitArgSchema() {
+        if (!this.initArgSpec) return {};
+        return createNamespacedInitArgSchema(this.initArgSpec.namespace, this.initArgSpec.shape);
+    }
+    getAgentInitArgCliMetadata() {
+        if (!this.initArgSpec?.cli) return;
+        const options = Object.fromEntries(this.getInitArgKeys().map((key)=>{
+            const canonicalKey = `${this.initArgSpec.namespace}.${key}`;
+            const preferredName = this.initArgSpec.cli?.preferredNames?.[key] ?? (this.initArgSpec.cli?.preferBareKeys ? camelToKebab(key) : canonicalKey);
+            const acceptedNames = new Set([
+                preferredName,
+                ...this.initArgSpec.cli?.preferBareKeys ? getKeyAliases(key) : getKeyAliases(canonicalKey)
+            ]);
+            acceptedNames.delete(preferredName);
+            return [
+                canonicalKey,
+                {
+                    preferredName,
+                    aliases: [
+                        ...acceptedNames
+                    ]
+                }
+            ];
+        }));
+        return {
+            options
+        };
+    }
     preparePlatformTools() {
         return [];
     }
@@ -30,8 +73,8 @@ class BaseMidsceneTools {
             await tempDevice.destroy?.();
             debug('Action space from temporary device:', actionSpace.map((a)=>a.name).join(', '));
         }
-        const actionTools = generateToolsFromActionSpace(actionSpace, ()=>this.ensureAgent());
-        const commonTools = generateCommonTools(()=>this.ensureAgent());
+        const actionTools = generateToolsFromActionSpace(actionSpace, (args = {})=>this.ensureAgent(this.extractAgentInitParam(args)), (args = {})=>this.sanitizeToolArgs(args), this.getAgentInitArgSchema(), this.getAgentInitArgCliMetadata());
+        const commonTools = generateCommonTools((args = {})=>this.ensureAgent(this.extractAgentInitParam(args)), this.getAgentInitArgSchema(), this.getAgentInitArgCliMetadata());
         this.toolDefinitions.push(...actionTools, ...commonTools);
         debug('Total tools prepared:', this.toolDefinitions.length);
     }

package/dist/es/mcp/index.mjs

@@ -1,5 +1,6 @@
 export * from "./base-server.mjs";
 export * from "./base-tools.mjs";
+export * from "./init-arg-utils.mjs";
 export * from "./error-formatter.mjs";
 export * from "./tool-generator.mjs";
 export * from "./types.mjs";

package/dist/es/mcp/init-arg-utils.mjs

@@ -0,0 +1,38 @@
+import { getKeyAliases, isRecord } from "../key-alias-utils.mjs";
+function readAliasedValue(args, key) {
+    for (const alias of getKeyAliases(key))if (alias in args) return args[alias];
+}
+function readNamespacedArg(args, namespace, key) {
+    const namespacedArgs = readAliasedValue(args, namespace);
+    if (isRecord(namespacedArgs)) {
+        const nestedValue = readAliasedValue(namespacedArgs, key);
+        if (void 0 !== nestedValue) return nestedValue;
+    }
+    const dottedValue = readAliasedValue(args, `${namespace}.${key}`);
+    if (void 0 !== dottedValue) return dottedValue;
+    const directValue = readAliasedValue(args, key);
+    if (void 0 !== directValue) return directValue;
+}
+function extractNamespacedArgs(args, namespace, keys) {
+    const extracted = {};
+    for (const key of keys){
+        const value = readNamespacedArg(args, namespace, key);
+        if (void 0 !== value) extracted[key] = value;
+    }
+    return Object.keys(extracted).length > 0 ? extracted : void 0;
+}
+function sanitizeNamespacedArgs(args, namespace, keys) {
+    const excludedKeys = new Set(getKeyAliases(namespace));
+    for (const key of keys){
+        for (const alias of getKeyAliases(key))excludedKeys.add(alias);
+        for (const alias of getKeyAliases(`${namespace}.${key}`))excludedKeys.add(alias);
+    }
+    return Object.fromEntries(Object.entries(args).filter(([key])=>!excludedKeys.has(key)));
+}
+function createNamespacedInitArgSchema(namespace, shape) {
+    return Object.fromEntries(Object.entries(shape).map(([key, value])=>[
+            `${namespace}.${key}`,
+            value
+        ]));
+}
+export { createNamespacedInitArgSchema, extractNamespacedArgs, sanitizeNamespacedArgs };

package/dist/es/mcp/tool-generator.mjs

@@ -277,17 +277,30 @@ async function captureFailureResult(agent, actionName, errorMessage) {
         };
     }
 }
-function generateToolsFromActionSpace(actionSpace, getAgent) {
+function mergeToolCliMetadata(base, extra) {
+    const options = {
+        ...base?.options ?? {},
+        ...extra?.options ?? {}
+    };
+    return Object.keys(options).length > 0 ? {
+        options
+    } : void 0;
+}
+function generateToolsFromActionSpace(actionSpace, getAgent, sanitizeArgs = (args)=>args, initArgSchema = {}, initArgCliMetadata) {
     return actionSpace.map((action)=>{
-        const schema = extractActionSchema(action.paramSchema);
+        const schema = {
+            ...extractActionSchema(action.paramSchema),
+            ...initArgSchema
+        };
         return {
             name: action.name,
             description: describeActionForMCP(action),
             schema,
+            cli: initArgCliMetadata,
             handler: async (args)=>{
                 try {
-                    const agent = await getAgent();
-                    const normalizedArgs = normalizeActionArgs(args, action.paramSchema);
+                    const agent = await getAgent(args);
+                    const normalizedArgs = normalizeActionArgs(sanitizeArgs(args), action.paramSchema);
                     let actionResult;
                     try {
                         actionResult = await executeAction(agent, action.name, normalizedArgs);
@@ -306,15 +319,18 @@ function generateToolsFromActionSpace(actionSpace, getAgent) {
         };
     });
 }
-function generateCommonTools(getAgent) {
+function generateCommonTools(getAgent, initArgSchema = {}, initArgCliMetadata) {
     return [
         {
             name: 'take_screenshot',
             description: 'Capture screenshot of current page/screen',
-            schema: {},
-            handler: async ()=>{
+            schema: {
+                ...initArgSchema
+            },
+            cli: initArgCliMetadata,
+            handler: async (args = {})=>{
                 try {
-                    const agent = await getAgent();
+                    const agent = await getAgent(args);
                     const screenshot = await agent.page?.screenshotBase64();
                     if (!screenshot) return createErrorResult('Screenshot not available');
                     const { mimeType, body } = parseBase64(screenshot);
@@ -338,12 +354,14 @@ function generateCommonTools(getAgent) {
             name: 'act',
             description: 'Execute a natural language action. The AI will plan and perform multi-step operations in a single invocation, useful for transient UI interactions (e.g., Spotlight, dropdown menus) that disappear between separate commands.',
             schema: {
-                prompt: z.string().describe('Natural language description of the action to perform, e.g. "press Command+Space, type Safari, press Enter"')
+                prompt: z.string().describe('Natural language description of the action to perform, e.g. "press Command+Space, type Safari, press Enter"'),
+                ...initArgSchema
             },
-            handler: async (args)=>{
+            cli: mergeToolCliMetadata(void 0, initArgCliMetadata),
+            handler: async (args = {})=>{
                 const prompt = args.prompt;
                 try {
-                    const agent = await getAgent();
+                    const agent = await getAgent(args);
                     if (!agent.aiAction) return createErrorResult('act is not supported by this agent');
                     const result = await agent.aiAction(prompt, {
                         deepThink: false

package/dist/lib/cli/cli-runner.js

@@ -44,6 +44,8 @@ const external_node_os_namespaceObject = require("node:os");
 const external_node_path_namespaceObject = require("node:path");
 const external_dotenv_namespaceObject = require("dotenv");
 var external_dotenv_default = /*#__PURE__*/ __webpack_require__.n(external_dotenv_namespaceObject);
+const external_zod_namespaceObject = require("zod");
+const external_key_alias_utils_js_namespaceObject = require("../key-alias-utils.js");
 const external_logger_js_namespaceObject = require("../logger.js");
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
@@ -68,19 +70,48 @@ function parseValue(raw) {
     if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
     return raw;
 }
-function parseCliArgs(args) {
-    const result = {};
+function walkCliArgs(args, setArgValue) {
     for(let i = 0; i < args.length; i++){
         const arg = args[i];
         if (!arg.startsWith('--')) continue;
         const body = arg.slice(2);
         const eqIdx = body.indexOf('=');
-        if (eqIdx >= 0) result[body.slice(0, eqIdx)] = parseValue(body.slice(eqIdx + 1));
+        if (eqIdx >= 0) setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
         else if (args[i + 1] && !args[i + 1].startsWith('--')) {
             i++;
-            result[body] = parseValue(args[i]);
-        } else result[body] = true;
+            setArgValue(body, parseValue(args[i]));
+        } else setArgValue(body, true);
     }
+}
+function parseRawCliArgs(args) {
+    const result = {};
+    walkCliArgs(args, (key, value)=>{
+        result[key] = value;
+    });
+    return result;
+}
+function parseCliArgs(args) {
+    const result = {};
+    walkCliArgs(args, (key, value)=>{
+        if (!key.includes('.')) {
+            result[key] = value;
+            return;
+        }
+        const segments = key.split('.');
+        let current = result;
+        for (const segment of segments.slice(0, -1)){
+            const aliases = (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(segment);
+            const existing = aliases.map((alias)=>current[alias]);
+            const nestedRecord = existing.find(external_key_alias_utils_js_namespaceObject.isRecord);
+            const conflictingScalar = existing.find((entry)=>void 0 !== entry && !(0, external_key_alias_utils_js_namespaceObject.isRecord)(entry));
+            if (void 0 !== conflictingScalar) throw new CLIError(`Conflicting CLI args: "${segment}" is used both as a value and as a namespace`);
+            const target = nestedRecord ?? {};
+            for (const alias of aliases)current[alias] = target;
+            current = target;
+        }
+        const leafSegment = segments[segments.length - 1];
+        for (const alias of (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(leafSegment))current[alias] = value;
+    });
     return result;
 }
 function outputContentItem(item, isError) {
@@ -108,16 +139,86 @@ function removePrefix(name, prefix) {
     if (prefix && name.startsWith(prefix)) return name.slice(prefix.length);
     return name;
 }
+function formatCliOptionName(name) {
+    return `--${name}`;
+}
+function getCliOptionDisplay(key, cliOption) {
+    const label = formatCliOptionName(cliOption?.preferredName ?? key);
+    const aliases = [
+        ...new Set(cliOption?.aliases ?? [])
+    ].map((alias)=>formatCliOptionName(alias)).filter((alias)=>alias !== label);
+    return {
+        label,
+        aliases
+    };
+}
+function getAcceptedCliOptionNames(key, cliOption) {
+    return [
+        ...new Set(cliOption ? [
+            cliOption.preferredName ?? key,
+            ...cliOption.aliases ?? []
+        ] : [
+            key,
+            ...(0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(key)
+        ])
+    ];
+}
+function toOptionalCliSchemaField(field) {
+    if ('object' == typeof field && null !== field && 'function' == typeof field.optional) return field.optional();
+    const description = 'object' == typeof field && null !== field && "description" in field && 'string' == typeof field.description ? field.description : void 0;
+    return description ? external_zod_namespaceObject.z.any().describe(description) : external_zod_namespaceObject.z.any();
+}
+function buildCliArgSchema(def) {
+    return Object.fromEntries(Object.entries(def.schema).flatMap(([key, zodType])=>getAcceptedCliOptionNames(key, def.cli?.options?.[key]).map((cliKey)=>[
+                cliKey,
+                toOptionalCliSchemaField(zodType)
+            ])));
+}
+function buildDisallowedCliSpellings(def) {
+    const disallowedSpellings = new Map();
+    for (const [key] of Object.entries(def.schema)){
+        const cliOption = def.cli?.options?.[key];
+        const preferredLabel = formatCliOptionName(cliOption?.preferredName ?? key);
+        const acceptedNames = new Set(getAcceptedCliOptionNames(key, cliOption));
+        const knownSpellings = new Set([
+            key,
+            ...(0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(key),
+            ...cliOption?.preferredName ? (0, external_key_alias_utils_js_namespaceObject.getKeyAliases)(cliOption.preferredName) : [],
+            ...cliOption?.aliases ?? []
+        ]);
+        for (const spelling of knownSpellings)if (!acceptedNames.has(spelling)) disallowedSpellings.set(spelling, preferredLabel);
+    }
+    return disallowedSpellings;
+}
+function formatCliValidationError(scriptName, commandName, def, rawArgs) {
+    if (0 === Object.keys(def.schema).length) return;
+    const cliSchema = external_zod_namespaceObject.z.object(buildCliArgSchema(def)).strict();
+    const parsed = cliSchema.safeParse(rawArgs);
+    if (parsed.success) return;
+    const disallowedSpellings = buildDisallowedCliSpellings(def);
+    const unknownKeys = parsed.error.issues.flatMap((issue)=>'unrecognized_keys' === issue.code ? issue.keys : []);
+    if (unknownKeys.length > 0) return unknownKeys.map((key)=>{
+        const preferredLabel = disallowedSpellings.get(key);
+        if (preferredLabel) return `Unsupported option "--${key}" for ${scriptName} ${commandName}. Use "${preferredLabel}" instead.`;
+        return `Unknown option "--${key}" for ${scriptName} ${commandName}.`;
+    }).join('\n');
+    const [issue] = parsed.error.issues;
+    const optionName = 'string' == typeof issue?.path[0] ? `--${issue.path[0]}` : 'CLI arguments';
+    return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
+}
 function printCommandHelp(scriptName, cmd) {
     const { def } = cmd;
     console.log(`\nUsage: ${scriptName} ${cmd.name} [options]\n`);
     console.log(def.description);
     const schemaEntries = Object.entries(def.schema);
     if (schemaEntries.length > 0) {
+        const optionWidth = Math.max(22, ...schemaEntries.map(([key])=>getCliOptionDisplay(key, def.cli?.options?.[key]).label.length));
         console.log('\nOptions:');
         for (const [key, zodType] of schemaEntries){
+            const { label, aliases } = getCliOptionDisplay(key, def.cli?.options?.[key]);
             const desc = zodType.description ?? '';
-            console.log(`  --${key.padEnd(20)} ${desc}`);
+            const aliasText = aliases.length > 0 ? ` (aliases: ${aliases.join(', ')})` : '';
+            console.log(`  ${label.padEnd(optionWidth)} ${desc}${aliasText}`);
         }
     }
 }
@@ -178,13 +279,16 @@ async function runToolsCLI(tools, scriptName, options) {
         printHelp(scriptName, commands, cliVersion);
         throw new CLIError(`Unknown command: ${commandName}`);
     }
-    const parsedArgs = parseCliArgs(restArgs);
-    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
-    if (true === parsedArgs.help) {
+    const rawCliArgs = parseRawCliArgs(restArgs);
+    if (true === rawCliArgs.help) {
         debug('showing command help for: %s', match.name);
         printCommandHelp(scriptName, match);
         return;
     }
+    const cliValidationError = formatCliValidationError(scriptName, match.name, match.def, rawCliArgs);
+    if (cliValidationError) throw new CLIError(cliValidationError);
+    const parsedArgs = parseCliArgs(restArgs);
+    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
     const result = await match.def.handler(parsedArgs);
     debug('command %s completed, isError: %s', match.name, result.isError ?? false);
     outputResult(result);

package/dist/lib/key-alias-utils.js

@@ -0,0 +1,62 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    camelToKebab: ()=>camelToKebab,
+    getKeyAliases: ()=>getKeyAliases,
+    isRecord: ()=>isRecord,
+    kebabToCamel: ()=>kebabToCamel
+});
+function kebabToCamel(str) {
+    return str.replace(/-([a-z])/g, (_, letter)=>letter.toUpperCase());
+}
+function camelToKebab(str) {
+    return str.replace(/[A-Z]/g, (letter)=>`-${letter.toLowerCase()}`).replace(/^-/, '');
+}
+function getKeyAliases(key) {
+    return [
+        ...new Set([
+            key,
+            kebabToCamel(key),
+            camelToKebab(key)
+        ])
+    ];
+}
+function isRecord(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value);
+}
+exports.camelToKebab = __webpack_exports__.camelToKebab;
+exports.getKeyAliases = __webpack_exports__.getKeyAliases;
+exports.isRecord = __webpack_exports__.isRecord;
+exports.kebabToCamel = __webpack_exports__.kebabToCamel;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "camelToKebab",
+    "getKeyAliases",
+    "isRecord",
+    "kebabToCamel"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});