@midscene/shared 1.7.5-beta-20260421030751.0 → 1.7.5

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

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import { getKeyAliases } from "../key-alias-utils.mjs";
+function parseValue(raw) {
+    if (raw.startsWith('{') || raw.startsWith('[')) try {
+        return JSON.parse(raw);
+    } catch  {}
+    if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+    return raw;
+}
+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) setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
+        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
+            i++;
+            setArgValue(body, parseValue(args[i]));
+        } else setArgValue(body, true);
+    }
+}
+function parseCliArgs(args) {
+    const result = {};
+    walkCliArgs(args, (key, value)=>{
+        result[key] = value;
+    });
+    return result;
+}
+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 Set();
+    for (const [key] of Object.entries(def.schema)){
+        const cliOption = def.cli?.options?.[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.add(spelling);
+    }
+    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)=>{
+        if (disallowedSpellings.has(key)) return `Unsupported option "--${key}" for ${scriptName} ${commandName}.`;
+        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}`;
+}
+export { formatCliValidationError, getCliOptionDisplay, parseCliArgs, parseValue };

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

@@ -0,0 +1,24 @@
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+class CLIError extends Error {
+    constructor(message, exitCode = 1){
+        super(message), _define_property(this, "exitCode", void 0), this.exitCode = exitCode;
+    }
+}
+function reportCLIError(error, log = console.error) {
+    if (error instanceof CLIError) {
+        log(error.message);
+        return error.exitCode;
+    }
+    log(error);
+    return 1;
+}
+export { CLIError, reportCLIError };

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

@@ -3,44 +3,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import dotenv from "dotenv";
 import { getDebug } from "../logger.mjs";
-function _define_property(obj, key, value) {
-    if (key in obj) Object.defineProperty(obj, key, {
-        value: value,
-        enumerable: true,
-        configurable: true,
-        writable: true
-    });
-    else obj[key] = value;
-    return obj;
-}
+import { formatCliValidationError, getCliOptionDisplay, parseCliArgs, parseValue } from "./cli-args.mjs";
+import { CLIError, reportCLIError } from "./cli-error.mjs";
 const debug = getDebug('cli-runner');
-class CLIError extends Error {
-    constructor(message, exitCode = 1){
-        super(message), _define_property(this, "exitCode", void 0), this.exitCode = exitCode;
-    }
-}
-function parseValue(raw) {
-    if (raw.startsWith('{') || raw.startsWith('[')) try {
-        return JSON.parse(raw);
-    } catch  {}
-    if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
-    return raw;
-}
-function parseCliArgs(args) {
-    const result = {};
-    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));
-        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
-            i++;
-            result[body] = parseValue(args[i]);
-        } else result[body] = true;
-    }
-    return result;
-}
 function outputContentItem(item, isError) {
     switch(item.type){
         case 'text':
@@ -72,10 +37,13 @@ function printCommandHelp(scriptName, cmd) {
     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}`);
         }
     }
 }
@@ -137,16 +105,18 @@ async function runToolsCLI(tools, scriptName, options) {
         throw new CLIError(`Unknown command: ${commandName}`);
     }
     const parsedArgs = parseCliArgs(restArgs);
-    debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
     if (true === parsedArgs.help) {
         debug('showing command help for: %s', match.name);
         printCommandHelp(scriptName, match);
         return;
     }
+    const cliValidationError = formatCliValidationError(scriptName, match.name, match.def, parsedArgs);
+    if (cliValidationError) throw new CLIError(cliValidationError);
+    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);
     await tools.destroy();
     if (result.isError) throw new CLIError('Command failed', 1);
 }
-export { CLIError, parseCliArgs, parseValue, removePrefix, runToolsCLI };
+export { CLIError, parseCliArgs, parseValue, removePrefix, reportCLIError, runToolsCLI };

package/dist/es/cli/index.mjs

@@ -1,2 +1,4 @@
-import { CLIError, parseCliArgs, parseValue, removePrefix, runToolsCLI } from "./cli-runner.mjs";
-export { CLIError, parseCliArgs, parseValue, removePrefix, runToolsCLI };
+import { CLIError, reportCLIError } from "./cli-error.mjs";
+import { parseCliArgs, parseValue } from "./cli-args.mjs";
+import { removePrefix, runToolsCLI } from "./cli-runner.mjs";
+export { CLIError, parseCliArgs, parseValue, removePrefix, reportCLIError, runToolsCLI };

package/dist/es/constants/index.mjs

@@ -15,13 +15,14 @@ var constants_NodeType = /*#__PURE__*/ function(NodeType) {
 }({});
 const PLAYGROUND_SERVER_PORT = 5800;
 const SCRCPY_SERVER_PORT = 5700;
+const SCRCPY_ADB_CONNECT_TIMEOUT_MS = 10000;
 const SCRCPY_PUSH_TIMEOUT_MS = 10000;
 const SCRCPY_START_TIMEOUT_MS = 15000;
 const SCRCPY_VIDEO_STREAM_TIMEOUT_MS = 15000;
-const SCRCPY_PREVIEW_METADATA_TIMEOUT_MS = SCRCPY_PUSH_TIMEOUT_MS + SCRCPY_START_TIMEOUT_MS + SCRCPY_VIDEO_STREAM_TIMEOUT_MS + 5000;
+const SCRCPY_PREVIEW_METADATA_TIMEOUT_MS = SCRCPY_ADB_CONNECT_TIMEOUT_MS + SCRCPY_PUSH_TIMEOUT_MS + SCRCPY_START_TIMEOUT_MS + SCRCPY_VIDEO_STREAM_TIMEOUT_MS + 5000;
 const WEBDRIVER_ELEMENT_ID_KEY = 'element-6066-11e4-a52e-4f735466cecf';
 const DEFAULT_WDA_PORT = 8100;
 const DEFAULT_WAIT_FOR_NAVIGATION_TIMEOUT = 5000;
 const DEFAULT_WAIT_FOR_NETWORK_IDLE_TIMEOUT = 2000;
 const DEFAULT_WAIT_FOR_NETWORK_IDLE_CONCURRENCY = 2;
-export { CONTAINER_MINI_HEIGHT, CONTAINER_MINI_WIDTH, DEFAULT_WAIT_FOR_NAVIGATION_TIMEOUT, DEFAULT_WAIT_FOR_NETWORK_IDLE_CONCURRENCY, DEFAULT_WAIT_FOR_NETWORK_IDLE_TIMEOUT, DEFAULT_WDA_PORT, constants_NodeType as NodeType, PLAYGROUND_SERVER_PORT, PLAYWRIGHT_EXAMPLE_CODE, SCRCPY_PREVIEW_METADATA_TIMEOUT_MS, SCRCPY_PUSH_TIMEOUT_MS, SCRCPY_SERVER_PORT, SCRCPY_START_TIMEOUT_MS, SCRCPY_VIDEO_STREAM_TIMEOUT_MS, TEXT_MAX_SIZE, TEXT_SIZE_THRESHOLD, WEBDRIVER_ELEMENT_ID_KEY, YAML_EXAMPLE_CODE };
+export { CONTAINER_MINI_HEIGHT, CONTAINER_MINI_WIDTH, DEFAULT_WAIT_FOR_NAVIGATION_TIMEOUT, DEFAULT_WAIT_FOR_NETWORK_IDLE_CONCURRENCY, DEFAULT_WAIT_FOR_NETWORK_IDLE_TIMEOUT, DEFAULT_WDA_PORT, constants_NodeType as NodeType, PLAYGROUND_SERVER_PORT, PLAYWRIGHT_EXAMPLE_CODE, SCRCPY_ADB_CONNECT_TIMEOUT_MS, SCRCPY_PREVIEW_METADATA_TIMEOUT_MS, SCRCPY_PUSH_TIMEOUT_MS, SCRCPY_SERVER_PORT, SCRCPY_START_TIMEOUT_MS, SCRCPY_VIDEO_STREAM_TIMEOUT_MS, TEXT_MAX_SIZE, TEXT_SIZE_THRESHOLD, WEBDRIVER_ELEMENT_ID_KEY, YAML_EXAMPLE_CODE };

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-args.js

@@ -0,0 +1,138 @@
+"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__, {
+    parseCliArgs: ()=>parseCliArgs,
+    parseValue: ()=>parseValue,
+    formatCliValidationError: ()=>formatCliValidationError,
+    getCliOptionDisplay: ()=>getCliOptionDisplay
+});
+const external_zod_namespaceObject = require("zod");
+const external_key_alias_utils_js_namespaceObject = require("../key-alias-utils.js");
+function parseValue(raw) {
+    if (raw.startsWith('{') || raw.startsWith('[')) try {
+        return JSON.parse(raw);
+    } catch  {}
+    if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+    return raw;
+}
+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) setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
+        else if (args[i + 1] && !args[i + 1].startsWith('--')) {
+            i++;
+            setArgValue(body, parseValue(args[i]));
+        } else setArgValue(body, true);
+    }
+}
+function parseCliArgs(args) {
+    const result = {};
+    walkCliArgs(args, (key, value)=>{
+        result[key] = value;
+    });
+    return result;
+}
+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 Set();
+    for (const [key] of Object.entries(def.schema)){
+        const cliOption = def.cli?.options?.[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.add(spelling);
+    }
+    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)=>{
+        if (disallowedSpellings.has(key)) return `Unsupported option "--${key}" for ${scriptName} ${commandName}.`;
+        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}`;
+}
+exports.formatCliValidationError = __webpack_exports__.formatCliValidationError;
+exports.getCliOptionDisplay = __webpack_exports__.getCliOptionDisplay;
+exports.parseCliArgs = __webpack_exports__.parseCliArgs;
+exports.parseValue = __webpack_exports__.parseValue;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "formatCliValidationError",
+    "getCliOptionDisplay",
+    "parseCliArgs",
+    "parseValue"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

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

@@ -0,0 +1,61 @@
+"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__, {
+    CLIError: ()=>CLIError,
+    reportCLIError: ()=>reportCLIError
+});
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+class CLIError extends Error {
+    constructor(message, exitCode = 1){
+        super(message), _define_property(this, "exitCode", void 0), this.exitCode = exitCode;
+    }
+}
+function reportCLIError(error, log = console.error) {
+    if (error instanceof CLIError) {
+        log(error.message);
+        return error.exitCode;
+    }
+    log(error);
+    return 1;
+}
+exports.CLIError = __webpack_exports__.CLIError;
+exports.reportCLIError = __webpack_exports__.reportCLIError;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "CLIError",
+    "reportCLIError"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});