@midscene/shared 1.12.6 → 1.12.7-beta-20260911063016.0

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

@@ -1,28 +1,61 @@
 import { z } from "zod";
 import { getKeyAliases } from "../key-alias-utils.mjs";
+import { getZodValueKinds } from "../zod-schema-utils.mjs";
 import { CLIError } from "./cli-error.mjs";
+const cliNumberPattern = /^-?\d+(\.\d+)?$/;
 function parseValue(raw) {
     if (raw.startsWith('{') || raw.startsWith('[')) try {
         return JSON.parse(raw);
     } catch  {}
-    if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+    if (cliNumberPattern.test(raw)) return Number(raw);
     return raw;
 }
-function walkCliArgs(args, setArgValue) {
+function walkCliArgs(args, setArgValue, fieldByCliName) {
     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('--')) {
+        if (eqIdx >= 0) {
+            const key = body.slice(0, eqIdx);
+            setArgValue(key, parseCliValue(body.slice(eqIdx + 1), fieldByCliName?.get(key)));
+        } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
             i++;
-            setArgValue(body, parseValue(args[i]));
+            setArgValue(body, parseCliValue(args[i], fieldByCliName?.get(body)));
         } else setArgValue(body, true);
     }
 }
-function parseCliArgs(args) {
+function buildCliFieldIndex(def) {
+    const fieldByCliName = new Map();
+    for (const [schemaKey, field] of Object.entries(def.schema))for (const cliName of getAcceptedCliOptionNames(schemaKey, def.cli?.options?.[schemaKey]))fieldByCliName.set(cliName, field);
+    return fieldByCliName;
+}
+function parseJsonValue(raw) {
+    if (!raw.startsWith('{') && !raw.startsWith('[')) return raw;
+    try {
+        return JSON.parse(raw);
+    } catch  {
+        return raw;
+    }
+}
+function parseCliValue(raw, field) {
+    if (!field) return parseValue(raw);
+    const kinds = getZodValueKinds(field);
+    if (kinds.has('object') || kinds.has('array')) {
+        const parsedJson = parseJsonValue(raw);
+        if (parsedJson !== raw) return parsedJson;
+    }
+    if (kinds.has('string')) return raw;
+    if (kinds.has('number') && cliNumberPattern.test(raw)) return Number(raw);
+    if (kinds.has('boolean')) {
+        if ('true' === raw) return true;
+        if ('false' === raw) return false;
+    }
+    return kinds.has('unknown') ? parseValue(raw) : raw;
+}
+function parseCliArgs(args, def) {
     const result = {};
+    const fieldByCliName = def ? buildCliFieldIndex(def) : void 0;
     walkCliArgs(args, (key, value)=>{
         const existing = result[key];
         if (void 0 === existing) {
@@ -38,7 +71,7 @@ function parseCliArgs(args) {
             existing,
             value
         ];
-    });
+    }, fieldByCliName);
     return result;
 }
 function formatCliOptionName(name) {

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

@@ -155,7 +155,7 @@ async function runToolsCLI(tools, scriptName, options) {
     }
     const parsedArgs = {
         ...positionalArgs,
-        ...parseCliArgs(restArgs.slice(optionStartIndex))
+        ...parseCliArgs(restArgs.slice(optionStartIndex), match.def)
     };
     if (true === parsedArgs.help) {
         debug('showing command help for: %s', match.name);

package/dist/es/env/parse-model-config.mjs

@@ -5,7 +5,7 @@ import { assert } from "../utils.mjs";
 import { maskConfig, parseJson } from "./helper.mjs";
 import { initDebugConfig } from "./init-debug.mjs";
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.12.6";
+const getCurrentVersion = ()=>"1.12.7-beta-20260911063016.0";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: INSIGHT_MODEL_CONFIG_KEYS,

package/dist/es/zod-schema-utils.mjs

@@ -8,6 +8,60 @@ function unwrapZodField(field) {
     }
     return f;
 }
+function getLiteralValueKind(value) {
+    if ('string' == typeof value) return 'string';
+    if ('number' == typeof value) return 'number';
+    if ('boolean' == typeof value) return 'boolean';
+    return 'unknown';
+}
+function getNativeEnumValueKinds(values) {
+    const enumValues = Object.entries(values ?? {}).filter(([key])=>Number.isNaN(Number(key))).map(([, value])=>value);
+    return new Set(enumValues.map(getLiteralValueKind));
+}
+function getZodValueKinds(field) {
+    const actualField = unwrapZodField(field);
+    const definition = actualField._def;
+    switch(definition?.typeName){
+        case 'ZodString':
+        case 'ZodEnum':
+            return new Set([
+                'string'
+            ]);
+        case 'ZodNumber':
+            return new Set([
+                'number'
+            ]);
+        case 'ZodBoolean':
+            return new Set([
+                'boolean'
+            ]);
+        case 'ZodArray':
+        case 'ZodTuple':
+            return new Set([
+                'array'
+            ]);
+        case 'ZodObject':
+        case 'ZodRecord':
+        case 'ZodDiscriminatedUnion':
+            return new Set([
+                'object'
+            ]);
+        case 'ZodLiteral':
+            return new Set([
+                getLiteralValueKind(definition.value)
+            ]);
+        case 'ZodNativeEnum':
+            return getNativeEnumValueKinds(definition.values);
+        case 'ZodUnion':
+            return new Set((definition.options ?? []).flatMap((option)=>[
+                    ...getZodValueKinds(option)
+                ]));
+        default:
+            return new Set([
+                'unknown'
+            ]);
+    }
+}
 function isMidsceneLocatorField(field) {
     const actualField = unwrapZodField(field);
     if (actualField._def?.typeName === 'ZodObject') {
@@ -47,4 +101,4 @@ function getZodDescription(field) {
     if (isMidsceneLocatorField(actualField)) return 'Location information for the target element';
     return null;
 }
-export { getZodDescription, getZodTypeName, isMidsceneLocatorField, unwrapZodField };
+export { getZodDescription, getZodTypeName, getZodValueKinds, isMidsceneLocatorField, unwrapZodField };

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

@@ -32,29 +32,62 @@ __webpack_require__.d(__webpack_exports__, {
 });
 const external_zod_namespaceObject = require("zod");
 const external_key_alias_utils_js_namespaceObject = require("../key-alias-utils.js");
+const external_zod_schema_utils_js_namespaceObject = require("../zod-schema-utils.js");
 const external_cli_error_js_namespaceObject = require("./cli-error.js");
+const cliNumberPattern = /^-?\d+(\.\d+)?$/;
 function parseValue(raw) {
     if (raw.startsWith('{') || raw.startsWith('[')) try {
         return JSON.parse(raw);
     } catch  {}
-    if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+    if (cliNumberPattern.test(raw)) return Number(raw);
     return raw;
 }
-function walkCliArgs(args, setArgValue) {
+function walkCliArgs(args, setArgValue, fieldByCliName) {
     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('--')) {
+        if (eqIdx >= 0) {
+            const key = body.slice(0, eqIdx);
+            setArgValue(key, parseCliValue(body.slice(eqIdx + 1), fieldByCliName?.get(key)));
+        } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
             i++;
-            setArgValue(body, parseValue(args[i]));
+            setArgValue(body, parseCliValue(args[i], fieldByCliName?.get(body)));
         } else setArgValue(body, true);
     }
 }
-function parseCliArgs(args) {
+function buildCliFieldIndex(def) {
+    const fieldByCliName = new Map();
+    for (const [schemaKey, field] of Object.entries(def.schema))for (const cliName of getAcceptedCliOptionNames(schemaKey, def.cli?.options?.[schemaKey]))fieldByCliName.set(cliName, field);
+    return fieldByCliName;
+}
+function parseJsonValue(raw) {
+    if (!raw.startsWith('{') && !raw.startsWith('[')) return raw;
+    try {
+        return JSON.parse(raw);
+    } catch  {
+        return raw;
+    }
+}
+function parseCliValue(raw, field) {
+    if (!field) return parseValue(raw);
+    const kinds = (0, external_zod_schema_utils_js_namespaceObject.getZodValueKinds)(field);
+    if (kinds.has('object') || kinds.has('array')) {
+        const parsedJson = parseJsonValue(raw);
+        if (parsedJson !== raw) return parsedJson;
+    }
+    if (kinds.has('string')) return raw;
+    if (kinds.has('number') && cliNumberPattern.test(raw)) return Number(raw);
+    if (kinds.has('boolean')) {
+        if ('true' === raw) return true;
+        if ('false' === raw) return false;
+    }
+    return kinds.has('unknown') ? parseValue(raw) : raw;
+}
+function parseCliArgs(args, def) {
     const result = {};
+    const fieldByCliName = def ? buildCliFieldIndex(def) : void 0;
     walkCliArgs(args, (key, value)=>{
         const existing = result[key];
         if (void 0 === existing) {
@@ -70,7 +103,7 @@ function parseCliArgs(args) {
             existing,
             value
         ];
-    });
+    }, fieldByCliName);
     return result;
 }
 function formatCliOptionName(name) {

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

@@ -198,7 +198,7 @@ async function runToolsCLI(tools, scriptName, options) {
     }
     const parsedArgs = {
         ...positionalArgs,
-        ...(0, external_cli_args_js_namespaceObject.parseCliArgs)(restArgs.slice(optionStartIndex))
+        ...(0, external_cli_args_js_namespaceObject.parseCliArgs)(restArgs.slice(optionStartIndex), match.def)
     };
     if (true === parsedArgs.help) {
         debug('showing command help for: %s', match.name);

package/dist/lib/env/parse-model-config.js

@@ -37,7 +37,7 @@ const external_utils_js_namespaceObject = require("../utils.js");
 const external_helper_js_namespaceObject = require("./helper.js");
 const external_init_debug_js_namespaceObject = require("./init-debug.js");
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.12.6";
+const getCurrentVersion = ()=>"1.12.7-beta-20260911063016.0";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${external_types_js_namespaceObject.MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: external_constants_js_namespaceObject.INSIGHT_MODEL_CONFIG_KEYS,

package/dist/lib/zod-schema-utils.js

@@ -26,6 +26,7 @@ __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     getZodDescription: ()=>getZodDescription,
     getZodTypeName: ()=>getZodTypeName,
+    getZodValueKinds: ()=>getZodValueKinds,
     isMidsceneLocatorField: ()=>isMidsceneLocatorField,
     unwrapZodField: ()=>unwrapZodField
 });
@@ -39,6 +40,60 @@ function unwrapZodField(field) {
     }
     return f;
 }
+function getLiteralValueKind(value) {
+    if ('string' == typeof value) return 'string';
+    if ('number' == typeof value) return 'number';
+    if ('boolean' == typeof value) return 'boolean';
+    return 'unknown';
+}
+function getNativeEnumValueKinds(values) {
+    const enumValues = Object.entries(values ?? {}).filter(([key])=>Number.isNaN(Number(key))).map(([, value])=>value);
+    return new Set(enumValues.map(getLiteralValueKind));
+}
+function getZodValueKinds(field) {
+    const actualField = unwrapZodField(field);
+    const definition = actualField._def;
+    switch(definition?.typeName){
+        case 'ZodString':
+        case 'ZodEnum':
+            return new Set([
+                'string'
+            ]);
+        case 'ZodNumber':
+            return new Set([
+                'number'
+            ]);
+        case 'ZodBoolean':
+            return new Set([
+                'boolean'
+            ]);
+        case 'ZodArray':
+        case 'ZodTuple':
+            return new Set([
+                'array'
+            ]);
+        case 'ZodObject':
+        case 'ZodRecord':
+        case 'ZodDiscriminatedUnion':
+            return new Set([
+                'object'
+            ]);
+        case 'ZodLiteral':
+            return new Set([
+                getLiteralValueKind(definition.value)
+            ]);
+        case 'ZodNativeEnum':
+            return getNativeEnumValueKinds(definition.values);
+        case 'ZodUnion':
+            return new Set((definition.options ?? []).flatMap((option)=>[
+                    ...getZodValueKinds(option)
+                ]));
+        default:
+            return new Set([
+                'unknown'
+            ]);
+    }
+}
 function isMidsceneLocatorField(field) {
     const actualField = unwrapZodField(field);
     if (actualField._def?.typeName === 'ZodObject') {
@@ -80,11 +135,13 @@ function getZodDescription(field) {
 }
 exports.getZodDescription = __webpack_exports__.getZodDescription;
 exports.getZodTypeName = __webpack_exports__.getZodTypeName;
+exports.getZodValueKinds = __webpack_exports__.getZodValueKinds;
 exports.isMidsceneLocatorField = __webpack_exports__.isMidsceneLocatorField;
 exports.unwrapZodField = __webpack_exports__.unwrapZodField;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
     "getZodDescription",
     "getZodTypeName",
+    "getZodValueKinds",
     "isMidsceneLocatorField",
     "unwrapZodField"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];

package/dist/types/cli/cli-args.d.ts

@@ -1,6 +1,6 @@
 import type { ToolCliOption, ToolDefinition } from '../agent-tools/types';
 export declare function parseValue(raw: string): unknown;
-export declare function parseCliArgs(args: string[]): Record<string, unknown>;
+export declare function parseCliArgs(args: string[], def?: ToolDefinition): Record<string, unknown>;
 export declare function getCliOptionDisplay(key: string, cliOption?: ToolCliOption): {
     label: string;
     aliases: string[];

package/dist/types/zod-schema-utils.d.ts

@@ -1,9 +1,16 @@
 import type { z } from 'zod';
+export type ZodValueKind = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'unknown';
 /**
  * Recursively unwrap optional, nullable, default, and effects wrapper types
  * to get the actual inner Zod type
  */
 export declare function unwrapZodField(field: unknown): unknown;
+/**
+ * Return every top-level value kind accepted by a Zod field. Unlike
+ * `getZodTypeName`, this normalizes enums, literals, and unions so consumers
+ * can make type-directed decisions without parsing its display label.
+ */
+export declare function getZodValueKinds(field: unknown): Set<ZodValueKind>;
 /**
  * Check if a field is a Midscene locator field
  * Locator input schemas are identified by their prompt field.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/shared",
-  "version": "1.12.6",
+  "version": "1.12.7-beta-20260911063016.0",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",

package/src/cli/cli-args.ts

@@ -1,8 +1,11 @@
 import { z } from 'zod';
 import type { ToolCliOption, ToolDefinition } from '../agent-tools/types';
 import { getKeyAliases } from '../key-alias-utils';
+import { getZodValueKinds } from '../zod-schema-utils';
 import { CLIError } from './cli-error';
 
+const cliNumberPattern = /^-?\d+(\.\d+)?$/;
+
 export function parseValue(raw: string): unknown {
   if (raw.startsWith('{') || raw.startsWith('[')) {
     try {
@@ -12,7 +15,7 @@ export function parseValue(raw: string): unknown {
     }
   }
 
-  if (/^-?\d+(\.\d+)?$/.test(raw)) {
+  if (cliNumberPattern.test(raw)) {
     return Number(raw);
   }
 
@@ -22,6 +25,7 @@ export function parseValue(raw: string): unknown {
 function walkCliArgs(
   args: string[],
   setArgValue: (key: string, value: unknown) => void,
+  fieldByCliName?: ReadonlyMap<string, z.ZodTypeAny>,
 ): void {
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -31,34 +35,98 @@ function walkCliArgs(
     const eqIdx = body.indexOf('=');
 
     if (eqIdx >= 0) {
-      setArgValue(body.slice(0, eqIdx), parseValue(body.slice(eqIdx + 1)));
+      const key = body.slice(0, eqIdx);
+      setArgValue(
+        key,
+        parseCliValue(body.slice(eqIdx + 1), fieldByCliName?.get(key)),
+      );
     } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
       i++;
-      setArgValue(body, parseValue(args[i]));
+      setArgValue(body, parseCliValue(args[i], fieldByCliName?.get(body)));
     } else {
       setArgValue(body, true);
     }
   }
 }
 
-export function parseCliArgs(args: string[]): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-
-  walkCliArgs(args, (key, value) => {
-    const existing = result[key];
-    if (existing === undefined) {
-      result[key] = value;
-      return;
+function buildCliFieldIndex(
+  def: ToolDefinition,
+): ReadonlyMap<string, z.ZodTypeAny> {
+  const fieldByCliName = new Map<string, z.ZodTypeAny>();
+
+  for (const [schemaKey, field] of Object.entries(def.schema)) {
+    for (const cliName of getAcceptedCliOptionNames(
+      schemaKey,
+      def.cli?.options?.[schemaKey],
+    )) {
+      fieldByCliName.set(cliName, field);
     }
+  }
 
-    if (Array.isArray(existing)) {
-      existing.push(value);
-      result[key] = existing;
-      return;
-    }
+  return fieldByCliName;
+}
+
+function parseJsonValue(raw: string): unknown {
+  if (!raw.startsWith('{') && !raw.startsWith('[')) return raw;
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function parseCliValue(raw: string, field?: z.ZodTypeAny): unknown {
+  if (!field) return parseValue(raw);
+
+  const kinds = getZodValueKinds(field);
+  if (kinds.has('object') || kinds.has('array')) {
+    const parsedJson = parseJsonValue(raw);
+    if (parsedJson !== raw) return parsedJson;
+  }
+
+  // CLI input cannot distinguish a numeric-looking identifier from a number.
+  // Prefer the lossless representation whenever the schema accepts strings.
+  if (kinds.has('string')) return raw;
 
-    result[key] = [existing, value];
-  });
+  if (kinds.has('number') && cliNumberPattern.test(raw)) {
+    return Number(raw);
+  }
+
+  if (kinds.has('boolean')) {
+    if (raw === 'true') return true;
+    if (raw === 'false') return false;
+  }
+
+  return kinds.has('unknown') ? parseValue(raw) : raw;
+}
+
+export function parseCliArgs(
+  args: string[],
+  def?: ToolDefinition,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const fieldByCliName = def ? buildCliFieldIndex(def) : undefined;
+
+  walkCliArgs(
+    args,
+    (key, value) => {
+      const existing = result[key];
+      if (existing === undefined) {
+        result[key] = value;
+        return;
+      }
+
+      if (Array.isArray(existing)) {
+        existing.push(value);
+        result[key] = existing;
+        return;
+      }
+
+      result[key] = [existing, value];
+    },
+    fieldByCliName,
+  );
 
   return result;
 }

package/src/cli/cli-runner.ts

@@ -295,7 +295,7 @@ export async function runToolsCLI(
   }
   const parsedArgs = {
     ...positionalArgs,
-    ...parseCliArgs(restArgs.slice(optionStartIndex)),
+    ...parseCliArgs(restArgs.slice(optionStartIndex), match.def),
   };
   if (parsedArgs.help === true) {
     debug('showing command help for: %s', match.name);

package/src/zod-schema-utils.ts

@@ -1,5 +1,13 @@
 import type { z } from 'zod';
 
+export type ZodValueKind =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'array'
+  | 'object'
+  | 'unknown';
+
 /**
  * Recursively unwrap optional, nullable, default, and effects wrapper types
  * to get the actual inner Zod type
@@ -31,6 +39,68 @@ export function unwrapZodField(field: unknown): unknown {
   return f;
 }
 
+function getLiteralValueKind(value: unknown): ZodValueKind {
+  if (typeof value === 'string') return 'string';
+  if (typeof value === 'number') return 'number';
+  if (typeof value === 'boolean') return 'boolean';
+  return 'unknown';
+}
+
+function getNativeEnumValueKinds(
+  values: Record<string, unknown> | undefined,
+): Set<ZodValueKind> {
+  const enumValues = Object.entries(values ?? {})
+    .filter(([key]) => Number.isNaN(Number(key)))
+    .map(([, value]) => value);
+  return new Set(enumValues.map(getLiteralValueKind));
+}
+
+/**
+ * Return every top-level value kind accepted by a Zod field. Unlike
+ * `getZodTypeName`, this normalizes enums, literals, and unions so consumers
+ * can make type-directed decisions without parsing its display label.
+ */
+export function getZodValueKinds(field: unknown): Set<ZodValueKind> {
+  const actualField = unwrapZodField(field) as {
+    _def?: {
+      typeName?: string;
+      options?: unknown[];
+      value?: unknown;
+      values?: Record<string, unknown>;
+    };
+  };
+  const definition = actualField._def;
+
+  switch (definition?.typeName) {
+    case 'ZodString':
+    case 'ZodEnum':
+      return new Set(['string']);
+    case 'ZodNumber':
+      return new Set(['number']);
+    case 'ZodBoolean':
+      return new Set(['boolean']);
+    case 'ZodArray':
+    case 'ZodTuple':
+      return new Set(['array']);
+    case 'ZodObject':
+    case 'ZodRecord':
+    case 'ZodDiscriminatedUnion':
+      return new Set(['object']);
+    case 'ZodLiteral':
+      return new Set([getLiteralValueKind(definition.value)]);
+    case 'ZodNativeEnum':
+      return getNativeEnumValueKinds(definition.values);
+    case 'ZodUnion':
+      return new Set(
+        (definition.options ?? []).flatMap((option) => [
+          ...getZodValueKinds(option),
+        ]),
+      );
+    default:
+      return new Set(['unknown']);
+  }
+}
+
 /**
  * Check if a field is a Midscene locator field
  * Locator input schemas are identified by their prompt field.