@midscene/shared 1.7.5-beta-20260421030751.0 → 1.7.5

package/dist/types/mcp/base-tools.d.ts

@@ -1,13 +1,52 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { BaseAgent, BaseDevice, IMidsceneTools, ToolDefinition } from './types';
+import type { z } from 'zod';
+import type { BaseAgent, BaseDevice, IMidsceneTools, ToolCliMetadata, ToolDefinition, ToolSchema } from './types';
 /**
- * Base class for platform-specific MCP tools
- * Generic type TAgent allows subclasses to use their specific agent types
+ * Declarative description of a platform's agent init args.
+ * Collapses the `extractAgentInitParam` / `sanitizeToolArgs` /
+ * `getAgentInitArgSchema` trio into a single data declaration.
  */
-export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent> implements IMidsceneTools {
+export interface InitArgSpec<TInitParam> {
+    /** Arg namespace, e.g. `android`, `ios`. */
+    namespace: string;
+    /** Zod shape describing the init args. Field names drive the MCP schema. */
+    shape: Record<string, z.ZodTypeAny>;
+    /**
+     * Optional CLI presentation hints. These affect `--help` output for
+     * single-platform CLIs but do not alter MCP/YAML protocol keys.
+     */
+    cli?: {
+        /** Prefer bare `--device-id`-style options in platform CLI help output. */
+        preferBareKeys?: boolean;
+        /** Override the displayed option name for specific init arg fields. */
+        preferredNames?: Record<string, string>;
+    };
+    /**
+     * Adapt extracted namespaced args into the concrete `TInitParam` passed to
+     * `ensureAgent`. Defaults to returning the raw extracted record.
+     */
+    adapt?: (extracted: Record<string, unknown> | undefined) => TInitParam | undefined;
+}
+/**
+ * Base class for platform-specific MCP tools.
+ * @typeParam TAgent - Platform-specific agent type.
+ * @typeParam TInitParam - Platform-specific init parameter consumed by
+ *   `ensureAgent`. Defaults to `undefined` for platforms that take no args.
+ */
+export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent, TInitParam = unknown> implements IMidsceneTools {
     protected mcpServer?: McpServer;
     protected agent?: TAgent;
     protected toolDefinitions: ToolDefinition[];
+    /**
+     * Declarative init-arg spec. Subclasses that accept CLI/MCP init args should
+     * set this once and get `extractAgentInitParam` / `sanitizeToolArgs` /
+     * `getAgentInitArgSchema` auto-implemented.
+     *
+     * Declared with `declare` so that TS doesn't emit an `Object.defineProperty`
+     * for this field on the base constructor, which would otherwise overwrite
+     * a subclass field initializer under `useDefineForClassFields`.
+     */
+    protected readonly initArgSpec?: InitArgSpec<TInitParam>;
     /**
      * Ensure agent is initialized and ready for use.
      * Must be implemented by subclasses to create platform-specific agent.
@@ -15,7 +54,28 @@ export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseA
      * @returns Promise resolving to initialized agent instance
      * @throws Error if agent initialization fails
      */
-    protected abstract ensureAgent(initParam?: string): Promise<TAgent>;
+    protected abstract ensureAgent(initParam?: TInitParam): Promise<TAgent>;
+    private getInitArgKeys;
+    /**
+     * Extract a platform-specific agent init parameter from CLI/MCP tool args.
+     */
+    protected extractAgentInitParam(args: Record<string, unknown>): TInitParam | undefined;
+    /**
+     * Remove platform-specific init args before dispatching a tool payload to the action itself.
+     */
+    protected sanitizeToolArgs(args: Record<string, unknown>): Record<string, unknown>;
+    /**
+     * Expose platform-specific init args on action/common tool schemas.
+     */
+    protected getAgentInitArgSchema(): ToolSchema;
+    /**
+     * Expose CLI-only metadata for platform init args so single-platform help can
+     * show ergonomic bare flags while the underlying schema stays namespaced.
+     * When `preferBareKeys` is enabled, single-platform CLIs only accept the
+     * bare spellings; namespaced dotted spellings remain available through the
+     * MCP/YAML schema instead of the platform CLI surface.
+     */
+    protected getAgentInitArgCliMetadata(): ToolCliMetadata | undefined;
     /**
      * Optional: prepare platform-specific tools (e.g., device connection)
      */

package/dist/types/mcp/index.d.ts

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

package/dist/types/mcp/init-arg-utils.d.ts

@@ -0,0 +1,13 @@
+import type { z } from 'zod';
+import type { ToolSchema } from './types';
+export declare function extractNamespacedArgs<TFieldName extends string, TArgs extends Record<string, unknown> = Record<string, unknown>>(args: Record<string, unknown>, namespace: string, keys: readonly TFieldName[]): TArgs | undefined;
+export declare function sanitizeNamespacedArgs(args: Record<string, unknown>, namespace: string, keys: readonly string[]): Record<string, unknown>;
+/**
+ * Build a flat MCP tool schema whose keys are dotted `"<namespace>.<field>"`.
+ *
+ * We intentionally stay flat (rather than `{ namespace: z.object({...}) }`) so
+ * that CLI (`--android.device-id`), MCP clients, and `--help` output all share
+ * the same spelling. `readNamespacedArg` understands all three input shapes:
+ * nested namespace object, dotted flat key, and bare key fallback.
+ */
+export declare function createNamespacedInitArgSchema(namespace: string, shape: Record<string, z.ZodTypeAny>): ToolSchema;

package/dist/types/mcp/tool-generator.d.ts

@@ -1,10 +1,10 @@
-import type { ActionSpaceItem, BaseAgent, ToolDefinition } from './types';
+import type { ActionSpaceItem, BaseAgent, ToolCliMetadata, ToolDefinition, ToolSchema } from './types';
 /**
  * Converts DeviceAction from actionSpace into MCP ToolDefinition
  * This is the core logic that removes need for hardcoded tool definitions
  */
-export declare function generateToolsFromActionSpace(actionSpace: ActionSpaceItem[], getAgent: () => Promise<BaseAgent>): ToolDefinition[];
+export declare function generateToolsFromActionSpace(actionSpace: ActionSpaceItem[], getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>, sanitizeArgs?: (args: Record<string, unknown>) => Record<string, unknown>, initArgSchema?: ToolSchema, initArgCliMetadata?: ToolCliMetadata): ToolDefinition[];
 /**
  * Generate common tools (screenshot, act)
  */
-export declare function generateCommonTools(getAgent: () => Promise<BaseAgent>): ToolDefinition[];
+export declare function generateCommonTools(getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>, initArgSchema?: ToolSchema, initArgCliMetadata?: ToolCliMetadata): ToolDefinition[];

package/dist/types/mcp/types.d.ts

@@ -49,6 +49,13 @@ export type ToolHandler<T = Record<string, unknown>> = (args: T) => Promise<Tool
  * Tool schema type using Zod
  */
 export type ToolSchema = Record<string, z.ZodTypeAny>;
+export interface ToolCliOption {
+    preferredName?: string;
+    aliases?: string[];
+}
+export interface ToolCliMetadata {
+    options?: Record<string, ToolCliOption>;
+}
 /**
  * Tool definition for MCP server
  */
@@ -57,6 +64,7 @@ export interface ToolDefinition<T = Record<string, unknown>> {
     description: string;
     schema: ToolSchema;
     handler: ToolHandler<T>;
+    cli?: ToolCliMetadata;
 }
 /**
  * Tool type for mcpKitForAgent return value

package/package.json

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

package/src/cli/cli-args.ts

@@ -0,0 +1,173 @@
+import { z } from 'zod';
+import { getKeyAliases } from '../key-alias-utils';
+import type { ToolCliOption, ToolDefinition } from '../mcp/types';
+
+export function parseValue(raw: string): unknown {
+  if (raw.startsWith('{') || raw.startsWith('[')) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      // Not valid JSON, treat as string below
+    }
+  }
+
+  if (/^-?\d+(\.\d+)?$/.test(raw)) {
+    return Number(raw);
+  }
+
+  return raw;
+}
+
+function walkCliArgs(
+  args: string[],
+  setArgValue: (key: string, value: unknown) => void,
+): void {
+  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);
+    }
+  }
+}
+
+export function parseCliArgs(args: string[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  walkCliArgs(args, (key, value) => {
+    result[key] = value;
+  });
+
+  return result;
+}
+
+function formatCliOptionName(name: string): string {
+  return `--${name}`;
+}
+
+export function getCliOptionDisplay(
+  key: string,
+  cliOption?: ToolCliOption,
+): { label: string; aliases: string[] } {
+  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: string,
+  cliOption?: ToolCliOption,
+): string[] {
+  return [
+    ...new Set(
+      cliOption
+        ? [cliOption.preferredName ?? key, ...(cliOption.aliases ?? [])]
+        : [key, ...getKeyAliases(key)],
+    ),
+  ];
+}
+
+function toOptionalCliSchemaField(field: unknown): z.ZodTypeAny {
+  if (
+    typeof field === 'object' &&
+    field !== null &&
+    typeof (field as z.ZodTypeAny).optional === 'function'
+  ) {
+    return (field as z.ZodTypeAny).optional();
+  }
+
+  const description =
+    typeof field === 'object' &&
+    field !== null &&
+    'description' in field &&
+    typeof (field as { description?: unknown }).description === 'string'
+      ? (field as { description: string }).description
+      : undefined;
+  return description ? z.any().describe(description) : z.any();
+}
+
+function buildCliArgSchema(def: ToolDefinition): Record<string, z.ZodTypeAny> {
+  return Object.fromEntries(
+    Object.entries(def.schema).flatMap(([key, zodType]) =>
+      getAcceptedCliOptionNames(key, def.cli?.options?.[key]).map((cliKey) => [
+        cliKey,
+        toOptionalCliSchemaField(zodType),
+      ]),
+    ),
+  );
+}
+
+function buildDisallowedCliSpellings(def: ToolDefinition): Set<string> {
+  const disallowedSpellings = new Set<string>();
+
+  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<string>([
+      key,
+      ...getKeyAliases(key),
+      ...(cliOption?.preferredName
+        ? getKeyAliases(cliOption.preferredName)
+        : []),
+      ...(cliOption?.aliases ?? []),
+    ]);
+
+    for (const spelling of knownSpellings) {
+      if (!acceptedNames.has(spelling)) {
+        disallowedSpellings.add(spelling);
+      }
+    }
+  }
+
+  return disallowedSpellings;
+}
+
+export function formatCliValidationError(
+  scriptName: string,
+  commandName: string,
+  def: ToolDefinition,
+  rawArgs: Record<string, unknown>,
+): string | undefined {
+  if (Object.keys(def.schema).length === 0) {
+    return undefined;
+  }
+
+  const cliSchema = z.object(buildCliArgSchema(def)).strict();
+  const parsed = cliSchema.safeParse(rawArgs);
+  if (parsed.success) {
+    return undefined;
+  }
+
+  const disallowedSpellings = buildDisallowedCliSpellings(def);
+  const unknownKeys = parsed.error.issues.flatMap((issue) =>
+    issue.code === 'unrecognized_keys' ? 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 =
+    typeof issue?.path[0] === 'string' ? `--${issue.path[0]}` : 'CLI arguments';
+  return `Invalid value for "${optionName}" in ${scriptName} ${commandName}: ${issue?.message ?? parsed.error.message}`;
+}

package/src/cli/cli-error.ts

@@ -0,0 +1,24 @@
+export class CLIError extends Error {
+  constructor(
+    message: string,
+    public exitCode = 1,
+  ) {
+    super(message);
+  }
+}
+
+export function reportCLIError(
+  error: unknown,
+  log: (
+    message?: unknown,
+    ...optionalParams: unknown[]
+  ) => void = console.error,
+): number {
+  if (error instanceof CLIError) {
+    log(error.message);
+    return error.exitCode;
+  }
+
+  log(error);
+  return 1;
+}

package/src/cli/cli-runner.ts

@@ -9,6 +9,12 @@ import type {
   ToolResult,
   ToolResultContent,
 } from '../mcp/types';
+import {
+  formatCliValidationError,
+  getCliOptionDisplay,
+  parseCliArgs,
+} from './cli-args';
+import { CLIError } from './cli-error';
 
 const debug = getDebug('cli-runner');
 
@@ -32,58 +38,8 @@ export interface CLIRunnerOptions {
   extraCommands?: CLIExtraCommand[];
 }
 
-export class CLIError extends Error {
-  constructor(
-    message: string,
-    public exitCode = 1,
-  ) {
-    super(message);
-  }
-}
-
-export function parseValue(raw: string): unknown {
-  // JSON objects/arrays
-  if (raw.startsWith('{') || raw.startsWith('[')) {
-    try {
-      return JSON.parse(raw);
-    } catch {
-      // Not valid JSON, treat as string below
-    }
-  }
-
-  // Numbers
-  if (/^-?\d+(\.\d+)?$/.test(raw)) {
-    return Number(raw);
-  }
-
-  return raw;
-}
-
-export function parseCliArgs(args: string[]): Record<string, unknown> {
-  const result: Record<string, unknown> = {};
-
-  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) {
-      // --key=value
-      result[body.slice(0, eqIdx)] = parseValue(body.slice(eqIdx + 1));
-    } else if (args[i + 1] && !args[i + 1].startsWith('--')) {
-      // --key value
-      i++;
-      result[body] = parseValue(args[i]);
-    } else {
-      // --flag (boolean)
-      result[body] = true;
-    }
-  }
-
-  return result;
-}
+export { parseCliArgs, parseValue } from './cli-args';
+export { CLIError, reportCLIError } from './cli-error';
 
 function outputContentItem(item: ToolResultContent, isError: boolean): void {
   switch (item.type) {
@@ -128,10 +84,23 @@ function printCommandHelp(scriptName: string, cmd: CLICommand): void {
 
   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}`);
     }
   }
 }
@@ -158,8 +127,10 @@ function printHelp(
   console.log(`\nRun "${scriptName} <command> --help" for more info.`);
 }
 
+type AnyMidsceneTools = BaseMidsceneTools<any, any>;
+
 export async function runToolsCLI(
-  tools: BaseMidsceneTools,
+  tools: AnyMidsceneTools,
   scriptName: string,
   options?: CLIRunnerOptions,
 ): Promise<void> {
@@ -227,14 +198,24 @@ export async function runToolsCLI(
   }
 
   const parsedArgs = parseCliArgs(restArgs);
-  debug('command: %s, args: %s', match.name, JSON.stringify(parsedArgs));
-
   if (parsedArgs.help === true) {
     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',

package/src/cli/index.ts

@@ -1,8 +1,4 @@
-export {
-  runToolsCLI,
-  CLIError,
-  parseValue,
-  parseCliArgs,
-  removePrefix,
-} from './cli-runner';
+export { CLIError, reportCLIError } from './cli-error';
+export { parseCliArgs, parseValue } from './cli-args';
+export { runToolsCLI, removePrefix } from './cli-runner';
 export type { CLIRunnerOptions, CLIExtraCommand } from './cli-runner';

package/src/constants/index.ts

@@ -17,10 +17,12 @@ export enum NodeType {
 
 export const PLAYGROUND_SERVER_PORT = 5800;
 export const SCRCPY_SERVER_PORT = 5700;
+export const SCRCPY_ADB_CONNECT_TIMEOUT_MS = 10_000;
 export const SCRCPY_PUSH_TIMEOUT_MS = 10_000;
 export const SCRCPY_START_TIMEOUT_MS = 15_000;
 export const SCRCPY_VIDEO_STREAM_TIMEOUT_MS = 15_000;
 export const SCRCPY_PREVIEW_METADATA_TIMEOUT_MS =
+  SCRCPY_ADB_CONNECT_TIMEOUT_MS +
   SCRCPY_PUSH_TIMEOUT_MS +
   SCRCPY_START_TIMEOUT_MS +
   SCRCPY_VIDEO_STREAM_TIMEOUT_MS +

package/src/key-alias-utils.ts

@@ -0,0 +1,23 @@
+/**
+ * Internal-only helpers for CLI/MCP argument key aliasing.
+ * Not re-exported from the package entry point — keep consumers within
+ * `cli/` and `mcp/`.
+ */
+
+export function kebabToCamel(str: string): string {
+  return str.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+export function camelToKebab(str: string): string {
+  return str
+    .replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+    .replace(/^-/, '');
+}
+
+export function getKeyAliases(key: string): string[] {
+  return [...new Set([key, kebabToCamel(key), camelToKebab(key)])];
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}