@xiuchang-midscene/shared 2.0.2

package/src/utils.ts

@@ -0,0 +1,149 @@
+import { sha256 } from 'js-sha256';
+import { v4 as generateUUID } from 'uuid';
+
+declare const WorkerGlobalScope: any;
+
+export const ifInBrowser = typeof window !== 'undefined';
+export const ifInWorker = typeof WorkerGlobalScope !== 'undefined';
+export const ifInNode =
+  typeof process !== 'undefined' && process.versions?.node;
+
+export function uuid(): string {
+  return generateUUID();
+}
+
+const hashMap: Record<string, string> = {}; // id - combined
+
+export function generateHashId(rect: any, content = ''): string {
+  // Combine the input into a string
+  const combined = JSON.stringify({
+    content,
+    rect,
+  });
+
+  // Generates the sha-256 hash value and converts to a-z chars
+  let sliceLength = 5;
+  let slicedHash = '';
+  const hashHex = sha256.create().update(combined).hex();
+
+  // Convert hex to a-z by mapping each hex char to a letter
+  const toLetters = (hex: string): string => {
+    return hex
+      .split('')
+      .map((char) => {
+        const code = Number.parseInt(char, 16);
+        return String.fromCharCode(97 + (code % 26)); // 97 is 'a' in ASCII
+      })
+      .join('');
+  };
+
+  const hashLetters = toLetters(hashHex);
+
+  while (sliceLength < hashLetters.length - 1) {
+    slicedHash = hashLetters.slice(0, sliceLength);
+    if (hashMap[slicedHash] && hashMap[slicedHash] !== combined) {
+      sliceLength++;
+      continue;
+    }
+    hashMap[slicedHash] = combined;
+    break;
+  }
+  return slicedHash;
+}
+
+/**
+ * A utility function that asserts a condition and throws an error with a message if the condition is false.
+ *
+ * @param condition - The condition to assert
+ * @param message - The error message to throw if the condition is false
+ * @throws Error with the provided message if the condition is false
+ */
+export function assert(condition: any, message?: string): asserts condition {
+  if (!condition) {
+    throw new Error(message || 'Assertion failed');
+  }
+}
+
+let isMcp = false;
+
+export function setIsMcp(value: boolean) {
+  isMcp = value;
+}
+
+//mcp need use obj format to console msg: https://github.com/modelcontextprotocol/typescript-sdk/issues/244
+export function logMsg(...message: Parameters<typeof console.log>) {
+  if (!isMcp) {
+    console.log(...message);
+  }
+}
+
+export async function repeat(
+  times: number,
+  fn: (index: number) => Promise<void>,
+) {
+  for (let i = 0; i < times; i++) {
+    await fn(i);
+  }
+}
+
+const REGEXP_LT = /</g;
+const REGEXP_GT = />/g;
+const REGEXP_LT_ESCAPE = '__midscene_lt__';
+const REGEXP_GT_ESCAPE = '__midscene_gt__';
+
+export const escapeScriptTag = (html: string) => {
+  return html
+    .replace(REGEXP_LT, REGEXP_LT_ESCAPE)
+    .replace(REGEXP_GT, REGEXP_GT_ESCAPE);
+};
+
+export const antiEscapeScriptTag = (html: string) => {
+  const REGEXP_LT = new RegExp(REGEXP_LT_ESCAPE, 'g');
+  const REGEXP_GT = new RegExp(REGEXP_GT_ESCAPE, 'g');
+
+  return html.replace(REGEXP_LT, '<').replace(REGEXP_GT, '>');
+};
+
+export function replaceIllegalPathCharsAndSpace(str: string) {
+  // Only replace characters that are illegal in filenames, but preserve path separators
+  return str.replace(/[:*?"<>|# ]/g, '-');
+}
+
+/**
+ * Check if a value is a plain object (not null, not array, not other types)
+ */
+export function isPlainObject(value: unknown): value is Record<string, any> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Normalize string for comparison: lowercase and remove spaces, dashes, and underscores.
+ * Useful for flexible app name matching.
+ */
+export function normalizeForComparison(str: string): string {
+  return str.toLowerCase().replace(/[\s\-_]+/g, '');
+}
+
+/**
+ * Merge and normalize app name mappings.
+ * Keys are normalized (lowercase, no spaces/dashes/underscores) for flexible matching.
+ * User-provided mapping takes precedence over default mapping.
+ */
+export function mergeAndNormalizeAppNameMapping(
+  defaultMapping: Record<string, string>,
+  userMapping?: Record<string, string>,
+): Record<string, string> {
+  const result: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(defaultMapping)) {
+    result[normalizeForComparison(key)] = value;
+  }
+
+  if (userMapping) {
+    for (const [key, value] of Object.entries(userMapping)) {
+      result[normalizeForComparison(key)] = value;
+    }
+  }
+
+  return result;
+}

package/src/zod-schema-utils.ts

@@ -0,0 +1,133 @@
+import type { z } from 'zod';
+
+/**
+ * Recursively unwrap optional, nullable, default, and effects wrapper types
+ * to get the actual inner Zod type
+ */
+export function unwrapZodField(field: unknown): unknown {
+  const f = field as {
+    _def?: { typeName?: string; innerType?: unknown; schema?: unknown };
+  };
+  if (!f._def) return f;
+
+  const typeName = f._def.typeName;
+
+  // Handle wrapper types that have innerType
+  if (
+    typeName === 'ZodOptional' ||
+    typeName === 'ZodNullable' ||
+    typeName === 'ZodDefault'
+  ) {
+    return unwrapZodField(f._def.innerType);
+  }
+
+  // Handle ZodEffects (transformations, refinements, preprocessors)
+  if (typeName === 'ZodEffects') {
+    if (f._def.schema) {
+      return unwrapZodField(f._def.schema);
+    }
+  }
+
+  return f;
+}
+
+/**
+ * Check if a field is a Midscene locator field
+ * Checks for either:
+ * 1. midscene_location_field_flag in shape (result schema)
+ * 2. prompt field in shape (input schema)
+ */
+export function isMidsceneLocatorField(field: unknown): boolean {
+  const actualField = unwrapZodField(field) as {
+    _def?: { typeName?: string; shape?: () => Record<string, unknown> };
+  };
+
+  if (actualField._def?.typeName === 'ZodObject') {
+    const shape = actualField._def.shape?.();
+    if (shape) {
+      // Method 1: Check for the location field flag (for result schema)
+      if ('midscene_location_field_flag' in shape) {
+        return true;
+      }
+      // Method 2: Check if it's the input schema by checking for 'prompt' field
+      if ('prompt' in shape && shape.prompt) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Get type name string from a Zod schema field
+ * @param field - Zod schema field
+ * @param locatorTypeDescription - Optional description for MidsceneLocation fields (used by core)
+ */
+export function getZodTypeName(
+  field: unknown,
+  locatorTypeDescription?: string,
+): string {
+  const actualField = unwrapZodField(field) as {
+    _def?: { typeName?: string; values?: unknown[]; options?: unknown[] };
+  };
+  const fieldTypeName = actualField._def?.typeName;
+
+  if (fieldTypeName === 'ZodString') return 'string';
+  if (fieldTypeName === 'ZodNumber') return 'number';
+  if (fieldTypeName === 'ZodBoolean') return 'boolean';
+  if (fieldTypeName === 'ZodArray') return 'array';
+  if (fieldTypeName === 'ZodObject') {
+    // Check if this is a Midscene locator field
+    if (isMidsceneLocatorField(actualField)) {
+      return locatorTypeDescription || 'object';
+    }
+    return 'object';
+  }
+  if (fieldTypeName === 'ZodEnum') {
+    const values =
+      (actualField._def?.values as unknown[] | undefined)
+        ?.map((option: unknown) => String(`'${option}'`))
+        .join(', ') ?? 'enum';
+    return `enum(${values})`;
+  }
+  // Handle ZodUnion by listing all option types
+  if (fieldTypeName === 'ZodUnion') {
+    const options = actualField._def?.options as unknown[] | undefined;
+    if (options && options.length > 0) {
+      const types = options.map((opt: unknown) =>
+        getZodTypeName(opt, locatorTypeDescription),
+      );
+      return types.join(' | ');
+    }
+    return 'union';
+  }
+
+  return 'unknown';
+}
+
+/**
+ * Get description from a Zod schema field
+ */
+export function getZodDescription(field: z.ZodTypeAny): string | null {
+  // Check for direct description on the original field (wrapper may have description)
+  if ('description' in field) {
+    return (field as { description?: string }).description || null;
+  }
+
+  const actualField = unwrapZodField(field) as {
+    description?: string;
+    _def?: { typeName?: string; shape?: () => Record<string, unknown> };
+  };
+
+  // Check for description on the unwrapped field
+  if ('description' in actualField) {
+    return actualField.description || null;
+  }
+
+  // Check for MidsceneLocation fields and add description
+  if (isMidsceneLocatorField(actualField)) {
+    return 'Location information for the target element';
+  }
+
+  return null;
+}